The developer command line (CLI) — nine commands with honest receipts

Who this guide is for: customer ADMINISTRATORS and their technical teammates who want to automate ConvoTide from a terminal. You need Node 18+ and an API key created in-app beforehand.

ConvoTide ships a developer CLI: one zero-dependency Node script (integrations/cli/ct.mjs) that drives the same documented public API the automation recipes use. It adds no endpoint the recipes do not already call — every route it can build sits in its frozen COMMAND_ROUTES table, and an offline contract test fails if any route there is missing from the generated OpenAPI document (services/wa-app/docs/openapi.json). There is nothing to install: the script uses Node built-ins only, and auth is the same pre-created API key the recipes send.

This guide documents candidate tooling, not a deployed service. Every command shape, refusal, receipt rule and exit code below was proven offline against deterministic local doubles and a loopback server through the real entrypoint — no live deployment, no remote API, no database and no messaging provider was contacted in any run behind this guide. Your deployment origin and a pre-created API key are named dependencies (below); using the CLI against a real origin is your configuration, not a tested claim of this guide.


Evidence record (kept for honesty)

(The body above is developer guidance; the receipts below are the internal record. Each behavior in the body is marked [tested · accepted] where the accepted suite proves it.)

The CLI's contract suite (integrations/cli/cli.contract.test.mjs, node --test) was independently executed by Chief review: 25/25 tests passed, exit 0, on 2026-10-24T20:22:29Z in worktree C:/CT-ZC-3637-p15sdk — receipt C:/CT-ZCODE-CONTINUE3637/CHIEF-P15-CLI-ACCEPTANCE3692.json. The PR (Chief's

361) is merged to Main, and the three source files on this guide branch's

base are byte-identical to the sha256 pins recorded in that receipt (re-verified from this checkout at authoring time):

File Bytes sha256 (receipt pin = this branch)
integrations/cli/ct.mjs 21214 eca2aee9…94a85d9cd — match
integrations/cli/cli.contract.test.mjs 27261 555d188b…ca1e5d51a — match
integrations/README.md 13392 cb1d19b9…de332f3eb — match

The receipt's own scope statement is the boundary of the claims here: "Node/injectedHTTPandloopbackonly; not remoteAPI/PG/liveprovider/Main/prod." The suite proves: contract membership of every command route; observed request paths can only be contract routes; send/subscribe/rotate/deliveries/delete journeys including two verbatim reproductions of malformed one-time-secret receipts (subscribe non-JSON 201 and rotate non-JSON 200 → exit 1 OUTCOME UNKNOWN), the definite 4xx refusal envelope, 5xx and malformed-body ambiguity, boundary validation, missing-credentials exit 2, and the real subprocess entrypoint (--help exit 0; send end-to-end against a loopback HTTP server). The guide body marks each behavior [tested · accepted]; anything outside that set is named as a dependency or not claimed.

The same surface is described from the integration side in integrations/README.md § "Developer CLI" and cross-linked from the scripted quickstarts in integrations/examples/README.md (same environment values, same documented routes, same idempotency discipline).

Getting started — nothing to install

Requirements: Node 18 or newer (for fetch, AbortSignal.timeout and the built-in test runner). Zero dependencies — ct.mjs imports only node:url and the vector-checked verifier the Node example ships (integrations/examples/node/verify-webhook-signature.mjs). Run it straight from a checkout of this repository:

node integrations/cli/ct.mjs --help

Configuration is the same three environment values as the automation recipes, plus optional knobs:

Variable Required Meaning
CONVOTIDE_BASE_URL yes (all but help/verify) Your deployment origin, e.g. https://wa.example.com. The contract's servers entry is / on purpose — scheme, host and port are deployment concerns. Named dependency: this chapter does not test any live origin.
CONVOTIDE_API_KEY yes (all but help/verify) A key pre-created in-app; key management is an in-app member act and the CLI deliberately cannot create keys. Sent as the Authorization: ApiKey … header (your key secret after ApiKey). Named dependency.
CONVOTIDE_ORG_ID no Org UUID sent as x-convotide-org. It selects among the key-holder's memberships; it never grants one. Omitted, your default org is used.
CONVOTIDE_IDEMPOTENCY_KEY no Default idempotency key for send.
CONVOTIDE_TIMEOUT_MS no Request timeout; default 15000.
CONVOTIDE_SIGNING_SECRET, CONVOTIDE_SIGNATURE_HEADER no Alternative to verify's --secret/--header flags.

--help is answered before any credential requirement and exits 0 [tested · accepted], so you can inspect the full usage text with no environment set.

The command surface

Nine commands drive contract routes (the frozen COMMAND_ROUTES table in ct.mjs; membership in docs/openapi.json enforced by the suite), plus one offline utility:

Command Route What it does
ct send POST /v1/messages Queue a template message; 202 only counts as accepted with the full receipt contract (below).
ct inbox GET /v1/inbox Read the inbox.
ct analytics summary GET /v1/analytics/summary The aggregated dashboard summary for your org.
ct contacts export GET /v1/contacts/export CSV export with per-channel consent state — your data stays yours.
ct webhooks list GET /v1/webhooks/subscriptions List subscriptions; the list projection never returns secrets.
ct webhooks subscribe POST /v1/webhooks/subscriptions Register an HTTPS receiver; prints the one-time signing secret exactly once.
ct webhooks rotate {subscriptionId} POST /v1/webhooks/subscriptions/{subscriptionId}/rotate Mint a new one-time secret; the old one stops verifying immediately.
ct webhooks deliveries {subscriptionId} GET /v1/webhooks/subscriptions/{subscriptionId}/deliveries The visible attempt/outcome ledger — failures are shown, never silently dropped.
ct webhooks delete {subscriptionId} DELETE /v1/webhooks/subscriptions/{subscriptionId} Delete a subscription.
ct verify offline (no route, no env) Timing-safe HMAC check of a delivery signature over the exact raw body.

All examples below are the script's own documented examples (from its built-in help and integrations/README.md), with flags exactly as the argument parser accepts them (--flag value or --flag=value; positionals for ids).

Sending a message — the 202 acceptance contract

node integrations/cli/ct.mjs send \
  --to +15551234567 \
  --template order_update \
  --idempotency-key k-1234 \
  --payload '{"order_id":"A-1"}'

A 202 response is a durable queue acknowledgement only when its body carries the documented acceptance contract [tested · accepted]:

{ "intentId": "…", "status": "…", "deduplicated": false }

intentId (string), status (string) and deduplicated (boolean) are all required — the suite pins the CLI's acceptance map to the OpenAPI 202 schema so it cannot drift. On a full-contract receipt the CLI prints either:

A 202 whose body is malformed, missing any acceptance field, or carries wrong-typed fields is OUTCOME UNKNOWN (exit 1) [tested · accepted]: the status line alone never establishes acceptance.

Webhooks — one-time secrets shown exactly once

# Register a receiver (events: a unique, non-empty subset — the CLI's help
# names the vocabulary: message.inbound, message.status, consent.changed,
# deal.created, deal.stage_changed, journey.enrolled, journey.completed,
# journey.exited, bot.api_request)
node integrations/cli/ct.mjs webhooks subscribe \
  --url https://receiver.example/hook \
  --events message.inbound,message.status

# Mint a fresh secret (old one invalid immediately)
node integrations/cli/ct.mjs webhooks rotate {subscriptionId}

# Inspect state — never returns secrets
node integrations/cli/ct.mjs webhooks list

# The visible per-attempt ledger
node integrations/cli/ct.mjs webhooks deliveries {subscriptionId} --limit 20

# Delete
node integrations/cli/ct.mjs webhooks delete {subscriptionId}

Client-side guards run before any request [tested · accepted]: --url must be https:// (the server refuses anything else), --events must be present and must not repeat — each violation is exit 2 with zero requests sent.

subscribe (201) and rotate (200) are the two one-time-secret mutations. The CLI calls the mutation a success only when the receipt carries subscriptionId and secret — the implemented SubscriptionWithSecret shape in services/wa-app/src/db/webhooks-out.ts. (The generated OpenAPI document records these two responses description-only — no content schema; the suite pins that recorded gap so a future schema addition forces the control to be revisited.) On a valid receipt the secret is printed once with an explicit store-it-now warning: it can never be read back — list never returns secrets, and there is no "show the secret again" path. Rotating again mints a new one-time secret and invalidates the lost one at commit.

A malformed or field-missing 201/200 is OUTCOME UNKNOWN, exit 1 — the secret may have been consumed and shown only in that unusable receipt. The documented recovery, printed by the CLI itself [tested · accepted, both verbatim reproductions in the accepted run]: check current state (ct webhooks list; ct webhooks deliveries {subscriptionId}), and if the subscription exists but you could not capture the secret, rotate again — never fabricate or reuse a secret you did not receive.

Verifying a delivery signature — offline, no credentials

node integrations/cli/ct.mjs verify \
  --secret whsec_... \
  --header 'sha256=HEX' \
  < raw-body-file

verify performs a timing-safe HMAC-SHA256 comparison over the exact raw body bytes (not re-serialized JSON), reusing the vector-checked verifier shared with the Node/Python/PHP example scripts rather than re-implementing HMAC handling. It needs no network, no base URL and no API key; --secret/--header may instead come from CONVOTIDE_SIGNING_SECRET/CONVOTIDE_SIGNATURE_HEADER. Output is a plain signature: VALID / signature: INVALID — reject the delivery; do not process the body verdict (exit 0/1; missing flags exit 2) [tested · accepted, including the shared test vectors]. Only verify reads stdin, so other commands never block on an open terminal.

The honest receipt discipline — what failure output means

The CLI never tells you "nothing happened" unless a receipt actually proves it. Every networked command funnels through one seam with a strict split [all tested · accepted]:

Exit code Meaning
0 Success — and for send/subscribe/rotate, only with a full-contract receipt.
1 Failure: a definite refusal (envelope code named) or an ambiguous OUTCOME-UNKNOWN receipt.
2 Usage/configuration error; no request was made.

Honest boundaries