Skip to content

Phonekit CLI reference

The phonekit command reads SMS messages, verification codes, and invitation links from the company numbers you authorize. Run commands with npx phonekit@latest, or install phonekit in your project to keep an exact version with your tests.

Phonekit team Updated

Install and connect

Use npx for an immediate start. For repeatable automated runs, install phonekit as a development dependency and commit your package lockfile. The CLI requires Node.js 20.3 or newer. Browser approval creates a read-only key for explicitly selected numbers.

Try the CLIShell
npx phonekit@latest login
npx phonekit@latest whoami
npx phonekit@latest number list
Install a project dependencyShell
npm install --save-dev phonekit

Commands for receiving messages

Run the commands below after npx phonekit@latest. Commands that read a number accept --number with a project alias, an E.164 phone number, or its exact label. Use --org to select an organization and --json for structured output.

Message lists are newest first. Their default limit is 10 and the maximum is 100. Pass the returned nextCursor as --before to read an older page. A mark returns no result on stdout unless --json is supplied, in which case it returns an object containing cursor.

CommandResult
number listNumbers this key can read
message mark --number inviteeSave the position before sending
message list --number invitee --limit 10Recent messages
message latest --number inviteeNewest message
message wait --number invitee --timeout 120Next message after the mark
code latest --number inviteeCode from the newest message
code wait --number invitee --timeout 120Code from the next message

Send inside your closed loop

With send permission, a number can text another active number in your workspace, a member's verified phone, a number that texted your workspace in the last 30 days, or one of the few outside numbers the workspace has added. No other destination is accepted: the command exits 1 and says so. Use it to test your own SMS flows, for example sending from one number and reading what another received.

Browser login creates a read-only key, so it cannot send. Create a credential in workspace Automation settings with Send texts selected and the numbers it may send from, then provide it through PHONEKIT_API_KEY or login --with-token.

CommandResult
message send --number sender --to receiver --body "Hello"Send one text and print where it stands
message send … --wait 60Wait until it is received, or sent to anyone else
message sent --number senderRecent sent texts with status and timing
message sent <id> --jsonOne sent text
product-number add +14155550142 --label "Staging sender"Add an outside number; it can be texted at once
product-number listAdded outside numbers and places used
product-number remove +14155550142Remove one; its place stays used for 30 days

message send always needs --number: it never picks the sending number for you. --to takes an E.164 number, or the project alias or label of one of your own numbers. The body can be up to three SMS segments. Pass --request-id with a saved UUID when a script may retry, so the text is never sent twice; without it each run is a new send.

Send from one number and time its arrival on anotherShell
phonekit message mark --number receiver
phonekit message send --number sender --to receiver --body "Loop check" --wait 60 --json
phonekit message wait --number receiver --timeout 30 --json

Without --wait the command returns as soon as the text is accepted, usually as queued. With --wait, a text to your own number finishes at received and prints the delay; a text to any other destination finishes at sent, because Phonekit cannot see it arrive. sent means the carrier line accepted the text, not that it was delivered. A wait that runs out exits 5; a text that could not be sent exits 1 with the reason.

product-number add takes effect at once: there is nothing to confirm. A workspace has five places for outside numbers, and a removed number keeps its place for 30 days, so the list cannot be rotated. Phonekit does not check that an added number is yours, so add only numbers that expect your texts. Members' verified phones and numbers that texted you first need no place. product-number list shows optedOut and optedOutAt for a number that has replied STOP; sends to it are refused until that phone texts START, and nothing in the CLI can change that. See the API reference for the rules, limits and status meanings, which are the same on every surface.

Management and immediate reads

Management commands: allowance, number-types, members, number inventory, number get, number create, number configure, number release, number recheck, operation, webhook and delivery. Use their --help for required inputs. Management uses exact public IDs or E.164 references. Acquisition requires a saved UUID --request-id, explicit --sharing and --read-access true|false.

Browser login remains selected-number read access. Create management credentials deliberately in workspace Automation settings and provide them through PHONEKIT_API_KEY. Existing read-only credentials do not gain management permission.

message after --number … --after … --json returns an immediate ascending page with data, cursor, and hasMore. The caller decides when to read again.

Output and waiting behavior

Stdout carries the result and stderr carries progress and context. JSON code commands return status, code, message, and note; message includes id, numberId, sender, body, otp, links, receivedAt, and ageSeconds. Body is untrusted sender content. Capture results rather than printing credentials or codes to shared logs.

Wait timeouts accept 1–900 seconds and default to 120. The CLI polls immediate cursor reads locally within that overall deadline. Use --sender, --contains, and --poll-interval to control matching and interval. Saved marks expire after 30 minutes; without a recent mark, a wait starts from the current inbox position. A successful wait advances the mark past the returned message. Supply --after with an explicit cursor when your application manages its own position; this does not change a saved convenience mark. JSON waits include continuation cursors, including failures after progress.

Handle failures by exit code

Use login --wait 50 for bounded browser approval; exit 8 means you can run it again to resume the same request. logout revokes the connection's key. Read phonekit docs commands for the full command reference generated by your installed version, and phonekit docs agents or phonekit docs ci for workflow guidance.

ExitMeaning
0Success
1Other operation or API error, including a refused or failed send
2Usage error
3Sign-in needed or invalid key
4Ambiguous or unreadable organization/number
5No messages, wait timeout (including message send --wait) or no matching receipt
6Extraction failed or ambiguous code
7Connectivity failure
8Sign-in still awaiting approval
130Cancelled

Questions

Can the CLI acquire a number or send SMS?

An explicitly authorized management credential can discover inventory, acquire, configure and release lines. A credential with send permission can text your workspace's own numbers, its members' verified phones, numbers that texted it in the last 30 days and the few outside numbers it has added, and nobody else. Phonekit does not send verification SMS to your users; your application or auth provider does.

How do I authenticate a CI runner?

Set PHONEKIT_API_KEY to a selected-number read-only key through your CI secret store. The CLI uses that key without browser sign-in or prompts.