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"}'
--tois an E.164-style number;--templatea registered template name;--payloadan optional JSON object literal (anything else is a usage error, exit 2).- The CLI refuses to run
sendwithout a caller-chosen--idempotency-keyof 8–128 characters (exit 2, before any network call) — so a retry can never double-send. Reuse the same key verbatim for the same business intent; never invent a new key to "retry".
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:
deduplicated: true→ the same durable intent came back — a safe retry, not a second send; ordeduplicated: false→accepted: durably queued, with the honest note that dispatch is a later worker step — this response does not prove delivery.
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]:
- Definite 4xx refusal (exit 1): the server answered with the uniform
envelope
{"error":{"code":"…","message":"…"}}. The CLI prints the status, the body, and names the errorcode— for example a scripted402 QUOTA_EXCEEDEDin the accepted loopback run. A refusal means the server refused the request; nothing was accepted. - OUTCOME UNKNOWN (exit 1): 5xx, malformed/unparseable bodies,
unexpected statuses (e.g. a 204 where 202 was contracted), or a
transport/timeout failure. The receipt neither confirms nor refuses the
request, so the CLI states the uncertainty and directs reconciliation:
for
send, retry with the SAME--idempotency-key(a same-key retry returns the same durable intent, never a duplicate — never invent a new key for the same intent); for other commands, check current state first (e.g.ct webhooks list) before repeating a create. The same honesty applies when no receipt arrives at all (connection or timeout error). - Usage or configuration errors (exit 2): missing base URL or API key, unknown command or subcommand, bad flags, missing/short idempotency key, non-https subscribe URL, repeated events. These fail before any network call — the suite asserts zero requests were sent.
| 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
- No live-endpoint claim. Everything above was proven on Node, injected
HTTP doubles and loopback servers only. Against your deployment, the
origin (
CONVOTIDE_BASE_URL) and a valid pre-created API key are named dependencies — behavior at a live origin is not a claim of this guide. - The CLI creates no API keys. Creating and revoking keys
(
/v1/apikeys,/v1/apikeys/{keyId}/revoke) stays an in-app member act; automations consume a pre-created key. - Receipt limits stated, not papered over. The OpenAPI document records
the subscribe/rotate responses description-only and has no subscribe
requestBody; the CLI's stricter maps are pinned to the implemented
SubscriptionWithSecret/202 shapes by the accepted suite, and the description-only gap is itself pinned so it cannot silently drift. - 202 is not delivery. Acceptance queues a durable intent; dispatch is a later worker step, and the CLI's own success line says so.
- Candidate tooling over the candidate API: the CLI's routes are exactly the generated contract at this tip — no route exists only for the CLI, and the offline membership gate keeps it that way.