Phonekit CLI reference

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.

npx phonekit@latest login
npx phonekit@latest whoami
npx phonekit@latest number list

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.

Management and immediate reads

CLI 0.4.0 adds allowance, number-types, members, number inventory, number get, number create, number configure, number release, number recheck, operation, webhook and delivery commands. 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.