# Phonekit CLI reference

> Commands, JSON output, selected-number access, closed-loop sending, project aliases, timeouts, and exit codes for the Phonekit CLI.

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.

## 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.

```bash title="Try the CLI"
npx phonekit@latest login
npx phonekit@latest whoami
npx phonekit@latest number list
```

```bash title="Install a project dependency"
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.

| Command                                       | Result                           |
| --------------------------------------------- | -------------------------------- |
| `number list`                                 | Numbers this key can read        |
| `message mark --number invitee`               | Save the position before sending |
| `message list --number invitee --limit 10`    | Recent messages                  |
| `message latest --number invitee`             | Newest message                   |
| `message wait --number invitee --timeout 120` | Next message after the mark      |
| `code latest --number invitee`                | Code from the newest message     |
| `code wait --number invitee --timeout 120`    | Code 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`.

| Command                                                     | Result                                            |
| ----------------------------------------------------------- | ------------------------------------------------- |
| `message send --number sender --to receiver --body "Hello"` | Send one text and print where it stands           |
| `message send … --wait 60`                                  | Wait until it is received, or sent to anyone else |
| `message sent --number sender`                              | Recent sent texts with status and timing          |
| `message sent <id> --json`                                  | One sent text                                     |
| `product-number add +14155550142 --label "Staging sender"`  | Add an outside number; it can be texted at once   |
| `product-number list`                                       | Added outside numbers and places used             |
| `product-number remove +14155550142`                        | Remove 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.

```bash title="Send from one number and time its arrival on another"
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](https://www.phonekit.io/docs/api#sending) 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.

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

## 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.

---

Source: https://www.phonekit.io/docs/cli
