> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI API requests

> Send an authenticated API request and choose how the CLI prints the response.

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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
source <(polymorfa completion bash)
```

For Zsh, initialize completion before loading the script:

```zsh theme={null}
autoload -Uz compinit && compinit
source <(polymorfa completion zsh)
```

For Fish:

```fish theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/integrations/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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/api/event-streams#read-an-event)
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](/sdks/overview),
pass the unparsed request bytes, `Polymorfa-Local-Signature` header, and the
per-run secret to `webhooks.verifyLocal`:

```ts theme={null}
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).

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
polymorfa api /platform/customers --surface platform --paginate \
  --jq '.data[].id'
```

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

```bash theme={null}
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:

```bash theme={null}
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.