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.
Install#
The CLI needs Node.js 22 or later. Install it from npm:
npm install --global @polymorfa/cli@dev
polymorfa versionpolymorfa 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.
export POLYMORFA_API_KEY='...'
polymorfa session listMessaging 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:
printf '%s' "$POLYMORFA_API_KEY" | \
polymorfa auth login --with-api-key --profile work
polymorfa auth use work
polymorfa auth statusThe 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:
- The
--projectflag. - The nearest
polymorfa.jsonin the current directory or a parent, written bypolymorfa link. - The project stored on the profile by
polymorfa project use.
polymorfa project use my-app
polymorfa link --project my-app
polymorfa project currentpolymorfa.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 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 valueOverride the API version for this request.
--jsonbooleanPrint one JSON document.
--no-colorbooleanDisable color output.
--owner <value>takes a valueSelect project-owned or team-owned resources.
Allowed valuesprojectteam--profile <value>takes a valueUse a named authentication profile.
--project <value>takes a valueUse a project other than the active context.
--quietbooleanSuppress successful output.
--timeout <value>takes a valueFail the request after this many milliseconds.
--verbosebooleanExplain context and workflow decisions.
Commands by topic
This reference documents CLI version 0.1.0-dev.0.
Get started
- polymorfa initCreate a credential-free Node.js and TypeScript starter in the current directory.1 command
- polymorfa authManage authentication profiles and credentials.5 commands
- polymorfa projectSelect, list, and inspect the project context.3 commands
- polymorfa linkLink the current directory to a project by writing polymorfa.json.1 command
- polymorfa doctorCheck Node.js, config, keyring access, API reachability, and server API key validity. Exits 1 if validation fails or is skipped.1 command
- polymorfa versionPrint the Polymorfa CLI and SDK versions.1 command
- polymorfa completionPrint a Bash, Zsh, or Fish completion script using local command metadata.1 command
- polymorfa docs2 commands
- polymorfa agentSet up coding agents with the Polymorfa agent kit.1 command
- polymorfa mcp6 commands
- polymorfa apiMake an authenticated request through the Polymorfa SDK.1 command
Messaging
- polymorfa messageSend messages and perform message actions.20 commands
- polymorfa chatRead stored chats on enrolled HMS Numbers (beta).5 commands
- polymorfa mediaInspect, download, and persist Messaging media.3 commands
- polymorfa contactInspect contacts and manage the contact blocklist.10 commands
- polymorfa groupInspect and manage Messaging groups.13 commands
- polymorfa labelManage Messaging labels and chat assignments.6 commands
- polymorfa quick-replyManage observed business quick replies.4 commands
- polymorfa presenceView and manage Messaging presence state.4 commands
- polymorfa privacyView and manage account-level Messaging privacy.3 commands
- polymorfa profileView and manage the connected account profile.5 commands
- polymorfa channelInspect and manage Messaging channels.13 commands
- polymorfa identityResolve phone numbers and usernames to Polymorfa user IDs.1 command
- polymorfa userInspect Linked Device user identity data.1 command
- polymorfa templateSubmit saved project templates for approval.1 command
- polymorfa flowManage project Flow drafts and their Official API lifecycle.19 commands
Calls
- polymorfa callsPlace and manage calls, check consent, carry audio, and report on past calls.31 commands
- polymorfa callReject incoming calls through the Linked Device session route.1 command
- polymorfa voiceVoice Automation (beta): audio library and text-to-speech provider credentials.12 commands
- polymorfa sip-trunkConnect a PBX to WhatsApp calls with SIP trunks.7 commands
Numbers
- polymorfa sessionManage Platform sessions.12 commands
- polymorfa quicklinkCreate, inspect, and cancel persistent onboarding QuickLinks.4 commands
- polymorfa widgetInspect and update saved QuickLink widget settings.2 commands
- polymorfa customerManage project Customers, pairing links, and assigned Numbers.14 commands
- polymorfa cloudOfficial API Number operations (beta). Team enrollment and scopes apply.23 commands
- polymorfa businessManage Linked Device Business App resources.25 commands
- polymorfa hybrid-link3 commands
- polymorfa routing-policy2 commands
- polymorfa testingManage simulated session fixtures.1 command
Campaigns
Events
- polymorfa eventInspect and replay durable developer events.4 commands
- polymorfa webhookInspect and manage developer webhooks.12 commands
- polymorfa listenListen for project events and optionally forward their exact payloads.1 command
- polymorfa triggerSend a signed test event for a Test number to your webhooks, event history, and a running `polymorfa listen`. Real numbers are refused.1 command
- polymorfa operation5 commands
- polymorfa logsRead and follow a project's API request log.2 commands
Safety
Account
- polymorfa analyticsRead WhatsApp number activity and operational vitals.2 commands
- polymorfa usage3 commands
- polymorfa billing7 commands
- polymorfa keyInspect and revoke team API keys.2 commands
- polymorfa project-tokenInspect project-token metadata.1 command
- polymorfa memberInspect team members.1 command
- polymorfa audit-logInspect team audit activity.1 command