CLI errors and exit codes

Exit codes

Branch on the exit status first, then on the error code.

The two exit-68 codes:

• NEEDS_BROWSER — the pipeline requires Turnstile, which only a browser can solve. Use a fresh end-user token with the sending command's --turnstile-token, or intentionally enable dev-mode bypasses: akedly pipelines dev-mode set <pipelineId> --dev-mode on --bypass-turnstile on --bypass-pow on --yes. Dev mode loosens live verification on the pipeline; it is not a production workaround.
• SETUP_REQUIRED — finish phone setup on the Personal Notifications page of the dashboard, then retry.

Commands that end in the browser, such as akedly whatsapp connect, are not failures: they print the dashboard link (see Progress events), and with --wait they then check for the result.

Error shape

{
  "status": "error",
  "code": "PERMISSION_DENIED",
  "message": "<message from the server>",
  "httpStatus": 403,
  "details": { "permission": "api_keys:create" },
  "hint": "<the next step to take>"
}

In JSON mode the error is the one document on stdout. In human mode it goes to stderr.

Progress events

Some commands report progress on stderr while they work. In JSON mode each event is one JSON line; in human mode it is a sentence. stdout still carries only the final result. stderr can also contain plain-text warnings and notices in JSON mode. Do not parse the whole stderr stream as JSON lines.

Opening a browser is always best effort; the link is printed either way, and akedly login keeps waiting for your approval. In human mode akedly login --open prints Could not open the browser. Open the approval URL yourself. instead of the event.

Retries

A timeout reads The request observation timed out; the server may still have processed it. The request may have worked. Check the state, for example with the matching list or get command, before you repeat anything that changes or sends.

Login and rate-limit errors

A CLI Login can end while you use it: when you or a team admin end it, when you leave the team, when the account is deleted, or, for a login that Akedly staff approved, when their staff session ends. The ending takes effect on the credential's next use; leaving the team can take up to about 60 seconds to reach it. The next command then fails with LOGIN_REQUIRED (exit 66). Run akedly login again.

How the CLI retries a CLI_RATE_LIMITED refusal is under Retries: it waits and tries again, at most 3 tries, only when the wait is 30 seconds or less. While akedly login waits for your approval, it slows its checks instead of stopping.

Commands that send or change things

Changes that need --yes

Some setup changes are not deletes, sends or payments, but they still change who can do what or where messages and results go. They need --yes too. Without it they stop with CONFIRMATION_REQUIRED (exit 65) and change nothing; --dry-run previews them.

akedly team members set-role ana@example.com --role support --yes
akedly team roles create --key support --name Support --permissions pipelines:read --yes
akedly team roles update <id> --permissions pipelines:read --yes
akedly whatsapp set-primary <phoneNumberId> --yes
akedly pipelines update <id> --webhook-url https://example.com/webhooks/akedly --yes
akedly api-keys create --label <name> --save --yes
akedly quickstart --yes
akedly byo-sms update <id> --sender-name <name> --yes

Teammate commands such as team members set-role take <member>: the teammate's email or their member ID from akedly team members list. If the CLI cannot find exactly one teammate, it stops with one of these codes, exit 1, before it changes anything.

Other commands to check before you repeat

• Requests to Akedly staff. akedly sso-request create answers HTTP 409 when a request is already open: check akedly sso-request status. akedly demo-extension request answers HTTP 409 when a request is already pending, and DEMO_EXTENSION_NOT_ELIGIBLE (409) when the account cannot get demo credits: check akedly demo-extension status. akedly quotation-requests create has no such check: each run files a new request and notifies staff.
• Secrets that stop at once. api-keys create --replaces-api-key-id, pipelines webhook-secret regenerate and utilities pipelines signing-secret regenerate stop the old secret immediately. If the response is lost, the old secret may already be dead. Reveal the current secret to a new file before anything else, or for an API key, use akedly api-keys recover-secret. Prefer --secret-file or --save to stdout: stdout can end up in agent transcripts and logs.
• Utilities sandbox sends (akedly utilities sandbox send):
  • The CLI does not retry it after a timeout or server error. Only a refusal coded CLI_RATE_LIMITED, which sends nothing, is retried.
  • A rejected WhatsApp sandbox send still counts against the rolling 60-minute allowance.
  • Each idempotency key belongs to one attempt. The same key replays the saved attempt, even a failed one. A new key starts a new, separately billed send.
  • After a refusal such as INSUFFICIENT_BALANCE, whether to reuse the key depends on whether an attempt was saved for it. Follow that code's hint under utilities sandbox send.
• Test-send limit. akedly utilities templates test-send can be refused with 429 TEST_SEND_LIMIT (Daily test-send limit of N reached.), which exits 69. The response does not say when the limit resets.

TOTP enrollment errors

Authenticator enrollment is unavailable through the CLI. totp users create is not a command; a direct enrollment request authenticated with a CLI Login is refused with CLI_TOTP_ENROLLMENT_UNAVAILABLE before provisioning. Use the supported TOTP setup flow instead.

Existing TOTP users, pipelines, history and authentication-request commands remain available in the TOTP reference. This restriction does not remove WhatsApp OTP-template creation.

Settings errors

The settings refusals below exit 1, except malformed flags or conflicting inputs (USAGE, exit 64) and missing --yes (CONFIRMATION_REQUIRED, exit 65). A local refusal has no HTTP status. In a multi-resource command, a refusal can be wrapped in PARTIAL_UPDATE; check its saved resources before retrying.

Local planning and partial saves

SETTING_NOT_FOR_THIS_PIPELINE and VERIFICATION_METHOD_UNAVAILABLE can also be raised during CLI planning, with no HTTP status; their remedies are the same as below.

Server settings refusals

For TURNSTILE_SETUP_TOKEN_MISSING or TURNSTILE_SETUP_VERIFICATION_FAILED, follow the CLI's setup-token link, check the Cloudflare Hostnames and key pair, and use a fresh token. Never reuse one after a refused or uncertain save.

Fields and JSON paths

--fields keeps only the paths you name, separated by commas. Missing paths are left out.

akedly commands --json --fields name,auth

akedly whoami --fields user,cliLogin.expiresAt

Where to look next

• Codes and hints

  —

  every shared error code, its exit status and its fallback hint

• Retry rules

  —

  the full retry legend used in each command's details

• Server guards

  —

  where each command's server-side checks are described

• Use the CLI with AI agents

  —

  rules for scripts and agents that run the CLI