CLI API requests

The CLI package is not yet published on npm. These examples describe the command in a CLI source build; there is no npm install command for it yet. Use polymorfa api to send a request through the CLI with your selected credential. Pass a relative path beginning with / and choose messaging or platform as the credential surface:

polymorfa api /platform/customers --surface platform

The command uses GET unless you set -X/--method. Give the CLI a credential through POLYMORFA_API_KEY or a configured authentication profile. Keep team keys in a trusted environment. The API still enforces that credential’s permissions and project access.

Check your CLI setup

Run polymorfa doctor before troubleshooting an API request. It checks your Node.js version, profile configuration, keyring access, API reachability, and server API key authentication:

polymorfa doctor --json

The command exits 0 when every required check completes. It exits 1 if a check fails or credential validation is skipped. A missing credential or multiple credential environment variables fail the check. A project or client token is reported as present, but doctor cannot validate it remotely and exits 1; this does not determine whether that token can access a particular command. Use one server API key to verify authentication. A 401 response fails; a 403 response warns that the key authenticated but project listing was denied. --profile <name> selects that profile instead of environment credentials. The output does not include credential values.

Complete commands in your shell

After installing a CLI source build, load the completion script for your shell:

source <(polymorfa completion bash)

For Zsh, initialize completion before loading the script:

autoload -Uz compinit && compinit
source <(polymorfa completion zsh)

For Fish:

polymorfa completion fish | source

Press Tab after polymorfa to complete commands, or after a command to complete its flags. The script also suggests fixed flag choices where a command defines them. It uses information from the installed CLI and does not look up profiles, project IDs, credentials, or other argument values. You can add the loading command to your shell startup file for later sessions.

Start a Node project

If you have access to the private CLI source repository, install a CLI source build and run init in a directory where you want a Node.js and TypeScript starter:

polymorfa init

The command writes package.json, src/index.ts, .env.example, and a README. It refuses an existing starter file or src directory before writing anything. No credential or project link is created. The package pins the exact published SDK development version. Run npm install and npm run typecheck in the starter directory, then set POLYMORFA_API_KEY in your shell or secret manager before npm start. Use polymorfa link separately when you want CLI commands to use a project. The CLI package is not yet published on npm.

Inspect sessions

Use a CLI source build that lists list, view, and status under polymorfa session --help. Earlier builds do not have these commands. Use a team API key with sessions:read to inspect session metadata:

polymorfa session list
polymorfa session list --project PROJECT_ID --json
polymorfa session view SESSION_ID
polymorfa session status SESSION_ID --json

session list returns every session in the team unless you pass a project ID. Use a session ID from that list for view or status. Those two commands reject --project because the session ID identifies one session across the team. status shows the stored status and reason; it does not test the live connection. The CLI package is not yet published on npm.

Discover project sessions through local MCP

Use a CLI source build where polymorfa mcp tools lists polymorfa_session_list. Earlier builds do not have this tool. The CLI package is not yet published on npm. Install the local MCP server for your agent client with polymorfa mcp install codex or polymorfa mcp install claude. Give the CLI a team API key with sessions:read. The read-only polymorfa_session_list tool requires an explicit project UUID and returns each session’s ID, name, stored status, and test-mode flag. It does not return phone numbers, credentials, or message data, and it does not probe a live connection. Project tokens and Messaging client tokens cannot use this tool. The local MCP server also exposes listener start, status, and stop tools. The hosted MCP server is a separate connection.

Find documentation

If you have access to the private CLI source repository, install a CLI source build to use these commands. The CLI package is not yet published on npm. Search the published documentation:

polymorfa docs search "rate limits"

The command prints matching page titles, paths, and links. It searches the published documentation index and needs network access, but does not use your Polymorfa credentials. Add --json to get the same results as a JSON array. Open a page by the path shown in the results:

polymorfa docs open api/rate-limits

Use --print to get the URL without starting a browser. A short final path segment works only when it identifies one page; use the full path when several pages share the same name.

Forward events to a local handler

polymorfa listen streams project events and forwards available exact event bodies to a handler. This command is available in a CLI source build; the package is not published on npm. Use a team key or project credential with events:listen. Set POLYMORFA_API_KEY or POLYMORFA_PROJECT_TOKEN, or select an authentication profile. Pass the handler address and write the per-run local signing secret to a private file:

polymorfa listen --project PROJECT_ID \
  --forward-to https://127.0.0.1:3000/webhooks \
  --forward-secret-out ./local-forwarding.secret \
  -H 'X-Local-Mode: test' --skip-verify --json

Forwarding requires the exact payload bytes. For events from a Number, enable hosted message storage for that Number; message bodies are not retained by default. If the body is unavailable, the listener reports event_unavailable and stops forwarding with forwarding_failed instead of sending metadata in its place. See event payload availability for the other conditions that can make a body unavailable. Verify the local signature before processing a forwarded body. For a TypeScript handler using the SDK development prerelease, pass the unparsed request bytes, Polymorfa-Local-Signature header, and the per-run secret to webhooks.verifyLocal:

import { readFile } from "node:fs/promises";
import { webhooks } from "@polymorfa/sdk";

async function verifyForwardedEvent(request: Request) {
  const rawBody = new Uint8Array(await request.arrayBuffer());
  const signature = request.headers.get("Polymorfa-Local-Signature") ?? "";
  const secret = (await readFile("./local-forwarding.secret", "utf8")).trim();
  return webhooks.verifyLocal({ body: rawBody, signature, secret });
}

verifyLocal rejects an invalid signature or a timestamp more than 300 seconds from the handler’s clock. Reject the request when verification fails. Do not parse and reserialize the body before verification. The local signing secret is separate from your production webhook secret. -H adds a custom header to forwarded requests. Repeat it for more headers. It cannot replace authentication, body framing, or Polymorfa signature headers. The CLI does not echo rejected header values. Custom headers cannot cross an origin-changing redirect. Keep secret values out of command arguments. --skip-verify accepts a self-signed certificate only for a loopback HTTPS forwarding destination. It does not change TLS verification for the Polymorfa API or public forwarding destinations. Omit it when your handler has a trusted certificate. --json prints JSONL records for listener transitions, including received events; server heartbeats do not produce output records. Forwarding in JSON or a noninteractive terminal requires --forward-secret-out.

Read every page

For an endpoint that returns page.nextCursor, add --paginate. The CLI sends each cursor back in the cursor query parameter. It stops if the API reports more pages without a cursor, repeats a cursor, or exceeds --max-pages (100 by default).

polymorfa api /platform/customers --surface platform --paginate

Human output prints each page as it arrives. --json prints one document with data set to an array of page bodies. Its metadata contains the final response’s status and request ID, when present, plus the page count. Use --include for human output that includes each response’s metadata. To collect those page results into one array, combine it with --slurp:

polymorfa api /platform/customers --surface platform --paginate --slurp --include

--paginate accepts GET requests only. Leave the cursor query parameter out of the path when the CLI manages pagination.

Filter or format a response

--jq runs a jq expression on each page. It prints strings without quotes and preserves spaces and newlines inside string values:

polymorfa api /platform/customers --surface platform --paginate \
  --jq '.data[].id'

Use --slurp to give one array of page bodies to the expression instead:

polymorfa api /platform/customers --surface platform --paginate --slurp \
  --jq 'map(.data | length) | add'

--template accepts paths, range, if, and string literals. Quoted strings can contain }} without closing the action:

polymorfa api /platform/customers --surface platform \
  --template '{{range .data}}{{.id}}{{"\\n"}}{{end}}'

--jq, --template, and --json are mutually exclusive. --include cannot be combined with either filter. --slurp requires --paginate.

Get started

Tools and clients

Connect numbers

WhatsApp

Campaigns

Your team

Testing

Help and updates

Check your CLI setup

Complete commands in your shell

Start a Node project

Inspect sessions

Discover project sessions through local MCP

Find documentation

Forward events to a local handler

Read every page

Filter or format a response

​Check your CLI setup

​Complete commands in your shell

​Start a Node project

​Inspect sessions

​Discover project sessions through local MCP

​Find documentation

​Forward events to a local handler

​Read every page

​Filter or format a response

Check your CLI setup

Complete commands in your shell

Start a Node project

Inspect sessions

Discover project sessions through local MCP

Find documentation

Forward events to a local handler

Read every page

Filter or format a response