Skip to content
Shortcut: /, ⌘K or Ctrl+K

Polymorfa CLI

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

View as Markdown

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.

Install#

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

Shell
npm install --global @polymorfa/cli@dev
polymorfa version

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.

Authenticate#

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

Shell
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:

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

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

Voice commands 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. Each command section says when it does.

  • --api-version <value>takes a value

    Override the API version for this request.

  • --jsonboolean

    Print one JSON document.

  • --no-colorboolean

    Disable color output.

  • --owner <value>takes a value

    Select project-owned or team-owned resources.

    Allowed valuesprojectteam
  • --profile <value>takes a value

    Use a named authentication profile.

  • --project <value>takes a value

    Use a project other than the active context.

  • --quietboolean

    Suppress successful output.

  • --timeout <value>takes a value

    Fail the request after this many milliseconds.

  • --verboseboolean

    Explain context and workflow decisions.

Commands by topic

This reference documents CLI version 0.1.0-dev.0.

Get started

Messaging

Calls

Numbers

Campaigns

Events

Safety

Account