CLI

Requires Node.js 20.19 or later. Check it with cymatics --version.

cymatics login opens the dashboard in your browser. Confirm there and the CLI receives a new key on a one-time local callback. It checks the key with GET /v1/project before saving it to profiles.json, readable only by you. In CI, pipe an existing key to --key-stdin so it never appears in your shell history.

$ cymatics login               # confirm in the browser
$ cymatics login --live        # a live key instead
$ cymatics login --no-browser  # print the URL instead
$ printf '%s' "$KEY" | cymatics login --key-stdin --profile ci

Test mode is the default; --live selects live credentials. The key comes from, in order, CYMO_TEST_API_KEY or CYMO_LIVE_API_KEY, then CYMO_API_KEY, then the selected profile. The API decides a key's project and mode, and the CLI rejects responses from the other mode.

$ cymatics auth status            # verify the key online
$ cymatics auth status --offline  # which key, no request
$ cymatics projects current       # the key's project
$ cymatics profiles list          # never shows the keys
$ cymatics profiles use staging   # the new default
$ cymatics logout --profile staging

Commands are cymatics <group> <action>, generated from the API contract, so they always match the API reference. Parameters are flags in kebab case, such as --room-id or its alias --room. A single path parameter can be passed positionally. cymatics api runs any operation by its ID.

$ cymatics rooms get --room room_bedroom --json
$ cymatics results list --room room_bedroom --limit 100 --paginate
$ cymatics webhooks create --input webhook.json \
    --idempotency-key "$(uuidgen)"
$ cymatics api get-room --room room_bedroom --dry-run

Results go to stdout as JSON, the same envelope as the API; streams and listen print one NDJSON line per message. A failure prints one {"error": {"code", "message"}} object on stderr and nothing on stdout.

Stream commands run until Ctrl-C unless you bound them with --max-events or --duration-ms. Binary data is only ever written to a new --output-file.

$ cymatics rooms stream --room room_bedroom --max-events 5
$ cymatics vitals stream --room room_bedroom --duration-ms 10000
$ cymatics raw-data exports download EXPORT_ID \
    --output-file capture.bin --max-bytes 1048576

cymatics mock start runs the real API gateway on 127.0.0.1 with the test simulator, in memory and offline. It has built-in keys: cym_test_local with every scope, cym_test_readonly with results:read, and cym_test_other for a second project.

$ cymatics mock start --port 8787

# in another terminal
$ export CYMO_API_URL=http://127.0.0.1:8787
$ export CYMO_TEST_API_KEY=cym_test_local
$ cymatics rooms get --room room_bedroom --json

Start a preset or custom timeline with scenarios run, then pause, resume or advance it with scenario-runs control. The run's rooms answer every read and stream. See Scenarios for the presets.

$ echo '{"scenario_id":"bed_exit","seed":42}' | cymatics scenarios run --input -
$ echo '{"action":"pause"}' | cymatics scenario-runs control RUN_ID --input -
$ echo '{"action":"advance","duration_ms":6000}' \
    | cymatics scenario-runs control RUN_ID --input -
$ cymatics events list --room ROOM_ID --json

listen forwards your project's new events to a local URL (localhost, 127.0.0.1 or [::1]) with the production body and headers, signed with a fresh whsec_ secret it prints first. Verify them with verifyWebhookSignature exactly as in production. Deliveries add Cymo-Forwarded: cli, and --events or --webhook-id filter the types.

$ cymatics listen --forward-to http://localhost:3000/api/cymo-webhook
$ cymatics listen --forward-to http://localhost:3000/hook \
    --events bed.exited,fall.detected
$ cymatics listen --forward-to http://localhost:3000/hook \
    --webhook-id wh_123 --max-events 10

Agents in a terminal can discover everything offline, without a key. agent guide returns the recommended workflow and agent schema every command's JSON Schema with a readOnlyHint. Combine --dry-run, --read-only and --agent to keep an agent's calls safe and bounded. For agents that speak MCP, use the MCP server.

$ cymatics agent guide                 # workflow, exit codes
$ cymatics agent schema --group rooms  # JSON Schemas
$ cymatics schema get-room             # one operation
$ cymatics rooms stream --room room_bedroom --agent

quota_exceeded is never retried: the message says how to raise the key's live-hour cap in the dashboard.