# Polymorfa CLI

> Install the Polymorfa CLI, sign in, and look up every command with its arguments, flags and examples.

The Polymorfa CLI runs Polymorfa operations from your terminal: send messages,
place calls, manage Numbers, campaigns and webhooks, forward events to a local
handler and send raw API requests. Every command on these pages comes from the
CLI's own command list, so its flags and defaults match the installed version.

For worked tasks, such as reading every page of a response or forwarding events
to a local handler, see [CLI API requests](https://docs.polymorfa.com/development/cli).

## Install

The CLI needs Node.js 22 or later. Install it from npm:

```bash
npm install --global @polymorfa/cli@dev
polymorfa version
```

> **Warning**
>
> The CLI is a development prerelease. The `dev` tag installs the latest
> prerelease build, and commands, flags and output can change between builds.
> Pin an exact version, such as `@polymorfa/cli@0.1.0-dev.0`, in scripts.

`polymorfa version` prints the CLI version and the version of the SDK it uses.

The CLI is open source under the MIT license. Its source code and issue
tracker are at [polymorfa/cli on GitHub](https://github.com/polymorfa/cli).

## Authenticate

Give the CLI a credential through an environment variable or a saved
authentication profile. Keep credentials out of command arguments.

```bash
export POLYMORFA_API_KEY='...'
polymorfa session list
```

Messaging commands accept exactly one of `POLYMORFA_API_KEY`,
`POLYMORFA_PROJECT_TOKEN` or `POLYMORFA_CLIENT_TOKEN`. Supplying more than one
fails before a request is sent. Raw Platform requests with `polymorfa api`
accept only `POLYMORFA_API_KEY`.

To save a profile, pipe a team key or a project token to
`auth login` through standard input:

```bash
printf '%s' "$POLYMORFA_API_KEY" | \
  polymorfa auth login --with-api-key --profile work

polymorfa auth use work
polymorfa auth status
```

The CLI stores the credential in the operating system's keyring: macOS
Keychain, Windows Credential Manager or Linux Secret Service. If the keyring is
unavailable, the command fails; the CLI never writes the credential to a plain
file. Environment credentials take precedence over the active profile, and
`--profile <name>` takes precedence over environment credentials.

Create and revoke team keys and project tokens in the
[Console](https://docs.polymorfa.com/development/api-keys). The API still enforces each credential's
permissions and project access. Run `polymorfa doctor` to check your setup.

## Choose a project

Commands that work on one project resolve it in this order:

1. The `--project` flag.
2. The nearest `polymorfa.json` in the current directory or a parent, written
   by `polymorfa link`.
3. The project stored on the profile by `polymorfa project use`.

```bash
polymorfa project use my-app
polymorfa link --project my-app
polymorfa project current
```

`polymorfa.json` holds only the project ID, never a credential, so you can
commit it. Team-owned commands ignore linked and profile projects.

## Output

Commands print human-readable output by default. `--json` prints exactly one
JSON document on standard output, and `--quiet` suppresses successful output
without hiding failures. Diagnostics and errors go to standard error. With
`--json`, the error on standard error carries the error code in `error.code`,
plus the request ID and a documentation link when the API returns them.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | The command succeeded. |
| `1` | A check or setup step failed, for example in `doctor` or `agent setup`. |
| `2` | The input is invalid, or the command does not accept the credential. |
| `3` | Authentication or authorization failed. |
| `4` | A conflict, a missing resource or a payment error. |
| `5` | A network failure, rate limit, server error or timeout. |

[Voice commands](https://docs.polymorfa.com/cli/voice) also use `6` when the team is not enrolled in
Voice Automation, `7` when a voice limit is reached and `13` when audio awaited
with `--wait` fails processing.

## Global flags

Most commands accept these flags.

- `--api-version <value>` (value). Override the API version for this request.
- `--json` (boolean). Print one JSON document.
- `--no-color` (boolean). Disable color output.
- `--owner <value>` (value). Select project-owned or team-owned resources. Values: `project`, `team`.
- `--profile <value>` (value). Use a named authentication profile.
- `--project <value>` (value). Use a project other than the active context.
- `--quiet` (boolean). Suppress successful output.
- `--timeout <value>` (value). Fail the request after this many milliseconds.
- `--verbose` (boolean). Explain context and workflow decisions.

## Commands

This reference documents CLI version 0.1.0-dev.0.

### Get started

- [polymorfa init](https://docs.polymorfa.com/cli/init.md): Create a credential-free Node.js and TypeScript starter in the current directory.
- [polymorfa auth](https://docs.polymorfa.com/cli/auth.md): Manage authentication profiles and credentials.
- [polymorfa project](https://docs.polymorfa.com/cli/project.md): Select, list, and inspect the project context.
- [polymorfa link](https://docs.polymorfa.com/cli/link.md): Link the current directory to a project by writing polymorfa.json.
- [polymorfa doctor](https://docs.polymorfa.com/cli/doctor.md): Check Node.js, config, keyring access, API reachability, and server API key validity. Exits 1 if validation fails or is skipped.
- [polymorfa version](https://docs.polymorfa.com/cli/version.md): Print the Polymorfa CLI and SDK versions.
- [polymorfa completion](https://docs.polymorfa.com/cli/completion.md): Print a Bash, Zsh, or Fish completion script using local command metadata.
- [polymorfa docs](https://docs.polymorfa.com/cli/docs.md): Commands under polymorfa docs.
- [polymorfa agent](https://docs.polymorfa.com/cli/agent.md): Set up coding agents with the Polymorfa agent kit.
- [polymorfa mcp](https://docs.polymorfa.com/cli/mcp.md): Commands under polymorfa mcp.
- [polymorfa api](https://docs.polymorfa.com/cli/api.md): Make an authenticated request through the Polymorfa SDK.

### Messaging

- [polymorfa message](https://docs.polymorfa.com/cli/message.md): Send messages and perform message actions.
- [polymorfa chat](https://docs.polymorfa.com/cli/chat.md): Read stored chats on enrolled HMS Numbers (beta).
- [polymorfa media](https://docs.polymorfa.com/cli/media.md): Inspect, download, and persist Messaging media.
- [polymorfa contact](https://docs.polymorfa.com/cli/contact.md): Inspect contacts and manage the contact blocklist.
- [polymorfa group](https://docs.polymorfa.com/cli/group.md): Inspect and manage Messaging groups.
- [polymorfa label](https://docs.polymorfa.com/cli/label.md): Manage Messaging labels and chat assignments.
- [polymorfa quick-reply](https://docs.polymorfa.com/cli/quick-reply.md): Manage observed business quick replies.
- [polymorfa presence](https://docs.polymorfa.com/cli/presence.md): View and manage Messaging presence state.
- [polymorfa privacy](https://docs.polymorfa.com/cli/privacy.md): View and manage account-level Messaging privacy.
- [polymorfa profile](https://docs.polymorfa.com/cli/profile.md): View and manage the connected account profile.
- [polymorfa channel](https://docs.polymorfa.com/cli/channel.md): Inspect and manage Messaging channels.
- [polymorfa identity](https://docs.polymorfa.com/cli/identity.md): Resolve phone numbers and usernames to Polymorfa user IDs.
- [polymorfa user](https://docs.polymorfa.com/cli/user.md): Inspect Linked Device user identity data.
- [polymorfa template](https://docs.polymorfa.com/cli/template.md): Submit saved project templates for approval.
- [polymorfa flow](https://docs.polymorfa.com/cli/flow.md): Manage project Flow drafts and their Official API lifecycle.

### Calls

- [polymorfa calls](https://docs.polymorfa.com/cli/calls.md): Place and manage calls, check consent, carry audio, and report on past calls.
- [polymorfa call](https://docs.polymorfa.com/cli/call.md): Reject incoming calls through the Linked Device session route.
- [polymorfa voice](https://docs.polymorfa.com/cli/voice.md): Voice Automation (beta): audio library and text-to-speech provider credentials.
- [polymorfa sip-trunk](https://docs.polymorfa.com/cli/sip-trunk.md): Connect a PBX to WhatsApp calls with SIP trunks.

### Numbers

- [polymorfa session](https://docs.polymorfa.com/cli/session.md): Manage Platform sessions.
- [polymorfa quicklink](https://docs.polymorfa.com/cli/quicklink.md): Create, inspect, and cancel persistent onboarding QuickLinks.
- [polymorfa widget](https://docs.polymorfa.com/cli/widget.md): Inspect and update saved QuickLink widget settings.
- [polymorfa customer](https://docs.polymorfa.com/cli/customer.md): Manage project Customers, pairing links, and assigned Numbers.
- [polymorfa cloud](https://docs.polymorfa.com/cli/cloud.md): Official API Number operations (beta). Team enrollment and scopes apply.
- [polymorfa business](https://docs.polymorfa.com/cli/business.md): Manage Linked Device Business App resources.
- [polymorfa hybrid-link](https://docs.polymorfa.com/cli/hybrid-link.md): Commands under polymorfa hybrid-link.
- [polymorfa routing-policy](https://docs.polymorfa.com/cli/routing-policy.md): Commands under polymorfa routing-policy.
- [polymorfa testing](https://docs.polymorfa.com/cli/testing.md): Manage simulated session fixtures.

### Campaigns

- [polymorfa campaign](https://docs.polymorfa.com/cli/campaign.md): Inspect and manage Messaging campaigns.
- [polymorfa audience](https://docs.polymorfa.com/cli/audience.md): Manage campaign audiences and their members.
- [polymorfa optout](https://docs.polymorfa.com/cli/optout.md): Manage team opt-out suppression.

### Events

- [polymorfa event](https://docs.polymorfa.com/cli/event.md): Inspect and replay durable developer events.
- [polymorfa webhook](https://docs.polymorfa.com/cli/webhook.md): Inspect and manage developer webhooks.
- [polymorfa listen](https://docs.polymorfa.com/cli/listen.md): Listen for project events and optionally forward their exact payloads.
- [polymorfa trigger](https://docs.polymorfa.com/cli/trigger.md): Send a signed test event for a Test number to your webhooks, event history, and a running `polymorfa listen`. Real numbers are refused.
- [polymorfa operation](https://docs.polymorfa.com/cli/operation.md): Commands under polymorfa operation.
- [polymorfa logs](https://docs.polymorfa.com/cli/logs.md): Read and follow a project's API request log.

### Safety

- [polymorfa bansafe](https://docs.polymorfa.com/cli/bansafe.md): Commands under polymorfa bansafe.
- [polymorfa session-ban](https://docs.polymorfa.com/cli/session-ban.md): Inspect recorded team session bans.
- [polymorfa security-incident](https://docs.polymorfa.com/cli/security-incident.md): Inspect and acknowledge team security incidents.

### Account

- [polymorfa analytics](https://docs.polymorfa.com/cli/analytics.md): Read WhatsApp number activity and operational vitals.
- [polymorfa usage](https://docs.polymorfa.com/cli/usage.md): Commands under polymorfa usage.
- [polymorfa billing](https://docs.polymorfa.com/cli/billing.md): Commands under polymorfa billing.
- [polymorfa key](https://docs.polymorfa.com/cli/key.md): Inspect and revoke team API keys.
- [polymorfa project-token](https://docs.polymorfa.com/cli/project-token.md): Inspect project-token metadata.
- [polymorfa member](https://docs.polymorfa.com/cli/member.md): Inspect team members.
- [polymorfa audit-log](https://docs.polymorfa.com/cli/audit-log.md): Inspect team audit activity.
