resonate-cli

Overview

The resonate binary is one program with three jobs:

1. Run the Resonate server — resonate serve (persistent storage) and resonate dev (in-memory, for development).
2. Talk to a running server over HTTP — every subcommand under resonate promises, resonate schedules, resonate tasks, plus the top-level resonate invoke and resonate tree.
3. Expose an MCP shim — resonate mcp is a stdio MCP server that wraps the same HTTP API for skill-aware agents (see resonate-bash for the durable-bash tool that ships through this shim).

This skill is the agent's reference for #2 and #3 — when you need to interact with a Resonate server from a shell. For long-form server deployment, see resonate-server-deployment and resonate-server-deployment-cloud-run.

The CLI is the source of truth. The hosted docs occasionally drift — see Docs-vs-binary deltas below. When in doubt: resonate <cmd> --help.

When to use this skill

Reach for the CLI when any of the following is true:

• You need to resolve, reject, or cancel a Durable Promise from outside any worker — typically to unblock a human-in-the-loop workflow, simulate a webhook callback, or recover a stuck process.
• You need to inspect server state — promises get, promises search, schedules search, tasks search, tree.
• You need to trigger a function manually — invoke creates the promise and routes it to a worker target, no client SDK required.
• You need to register or remove a cron schedule.
• You're scripting a smoke test against a running server.

Prefer the SDK over the CLI in application code. The CLI is for operators, debuggers, and one-off tooling. Anything you'd commit as a workflow step should live in the SDK.

Installation and version check

brew install resonatehq/tap/resonate   # macOS
resonate --version                     # expect 0.9.7 or newer

Linux: download from GitHub releases and put the binary on $PATH.

All command surface in this skill is from resonate 0.9.7. Use resonate <cmd> --help to confirm against your installed version — the built-in help is always authoritative.

Top-level command map

resonate
├── serve       Start the production server (persistent storage)
├── dev         Start the development server (in-memory)
├── promises    Promise operations (CRUD + search + callbacks/listeners)
├── tasks       Task operations (low-level; usually SDK-owned)
├── schedules   Schedule operations (cron-driven promise creation)
├── invoke      Invoke a function via a durable promise
├── tree        Display the call-graph tree rooted at a promise ID
└── mcp         Start the Resonate MCP server (stdio transport)

Global flags

Every client subcommand (promises, tasks, schedules, invoke, tree, mcp) accepts:

resonate --version and resonate --help work at the top level.

There is no --output json flag in resonate 0.9.7, despite older docs mentioning one. Subcommand stdout is human-formatted; if you need structured output, call the HTTP API directly with curl.

Server commands

resonate dev — in-memory development server

resonate dev

Storage defaults to :memory: (SQLite in-RAM), so every restart is a clean slate. Useful for local development and tests.

Listens on:

• HTTP API: http://localhost:8001
• Prometheus metrics: http://localhost:9090/metrics
• Health probe: http://localhost:8001/health (200 when healthy — note: it is /health, not /healthz)

Common flags (full set: resonate dev --help):

--transports-bash-exec-enabled (and every --transports-*-enabled flag) requires an explicit true / false. A bare flag errors with a value is required for '--transports-bash-exec-enabled <BOOL>'.

resonate serve — production server

export RESONATE_STORAGE__POSTGRES__URL="$DATABASE_URL"   # e.g. postgres://<user>:<password>@<host>:5432/resonate
resonate serve --storage-type postgres

Same flag surface as dev plus storage and auth options. The full reference is resonate serve --help; the highlights:

Storage gotcha: --storage-type defaults to sqlite. If you set --storage-postgres-url alone, the server boots on SQLite and silently ignores the URL. Always pair them.

Health route: /health returns 200 when the server is up. /healthz does not exist on Resonate — don't wire that into your readiness probes.

resonate promises

The most common subcommand tree. Every promise command takes <ID> as the trailing arg (or two IDs for callbacks/listeners) and respects the global -S / -T flags.

promises create <ID> --timeout <DURATION>

resonate promises create approval-456 --timeout 24h

promises get <ID>

resonate promises get order-123

Returns state, timestamps, param, value, and tags.

promises resolve <ID> [--value <JSON>]

resonate promises resolve approval-456 --value '{"approved": true}'

The flag is --value, not --data (older docs sometimes show --data — the binary doesn't accept it).

promises reject <ID> [--value <JSON>]

Same shape as resolve — the JSON ends up in the value field with promise state rejected.

promises cancel <ID> [--value <JSON>]

Same shape; promise state becomes rejected_canceled.

promises search

resonate promises search --state pending --limit 20
resonate promises search --tags '{"project":"checkout"}' --limit 50

promises search does not take a positional ID pattern — there is no search "order-*" form in resonate 0.9.7. Filter via --tags or paginate --state results client-side.

promises register-callback <AWAITED> <AWAITER>

Wires a server-side callback so that resolving AWAITED notifies the AWAITER promise. Rarely used from the CLI — most callers register callbacks via the SDK.

promises register-listener <AWAITED> <ADDRESS>

Registers a delivery address (e.g. http://my-host/cb or poll://group@worker) to be notified on settlement of AWAITED. Useful for ad-hoc webhook wiring during debugging.

resonate schedules

Cron-driven promise creation. Every cron tick stamps out a new promise from a template.

schedules create <ID> --cron <EXPR> --promise-id <TEMPLATE> --promise-timeout <DURATION>

resonate schedules create hourly-sync \
  --cron "0 * * * *" \
  --promise-id "sync-{{.timestamp}}" \
  --promise-timeout 30m \
  --promise-param '{"job":"sync"}' \
  --promise-tags '{"system":"etl"}'

--description exists in older docs but not in resonate 0.9.7. Use --promise-tags to label.

schedules get <ID> / schedules search / schedules delete <ID>

resonate schedules search --limit 50
resonate schedules get hourly-sync
resonate schedules delete hourly-sync

schedules search accepts --tags and --limit/--cursor. There is no positional pattern arg — same shape as promises search.

resonate invoke

resonate invoke <PROMISE_ID> --func <FUNC_NAME> [--arg <ARG> | --json-args <JSON_ARRAY>]

Creates a Durable Promise and routes it to a worker that has registered FUNC_NAME. The agent uses this to trigger workflows manually — for reproducing a bug, smoke-testing a worker after deploy, or kicking off one-off jobs.

# Single arg, default worker group
resonate invoke order-123 --func processOrder --arg '{"orderId":"123"}'

# Multiple args
resonate invoke checkout-7 --func charge --arg '"customer_42"' --arg '99.50'

# JSON-array form
resonate invoke checkout-7 --func charge --json-args '["customer_42", 99.50]'

# Route to a specific worker group
resonate invoke daily-report --func runReport --arg '{}' --target poll://any@reports

# Delayed kickoff
resonate invoke recheck-cdn --func ping --arg '"edge-1"' --delay 5m

Default target. poll://any@default routes to any worker polling the default group. If your worker polls a non-default group, override with --target poll://any@<group> or the invoke sits pending forever. The same trap bites ctx.detached() / ctx.Detached() in the TypeScript and Go SDKs — both call into the same routing layer.

resonate tree

resonate tree <ROOT_PROMISE_ID>

Prints the call-graph tree rooted at the given promise. Use this when a workflow is stuck and you want to see which child promise is blocking. No flags beyond -S / -T.

resonate tasks (low-level)

Tasks are the leases workers claim to execute promises. The CLI exposes the full task lifecycle (get, create, claim, fence, heartbeat, suspend, complete, release, halt, continue, search), but agents writing application code should not touch these — the SDK owns task lifecycle. The two cases where the CLI task surface is useful:

1. Diagnostics. resonate tasks search --state <STATE> to inspect what's claimed / pending / suspended; resonate tasks get <ID> to look at one task in detail.
2. Manual recovery. resonate tasks release <ID> --version <N> to release a leaked lease back to pending so a fresh worker can claim it. --version is the optimistic-concurrency version returned by tasks get.

The full surface, for completeness:

If you find yourself writing CLI scripts that compose these task primitives, you almost certainly want the SDK instead — see the per-SDK basic-ephemeral-world and basic-durable-world skills.

resonate mcp

resonate mcp --server http://localhost:8001

Starts a stdio MCP server that wraps the Resonate HTTP API. Skill-aware agents (Claude Code, Cursor) launch this as a child process and call its tools (promise-create, promise-get, promise-listen, promise-search, promise-settle, plus resonate-bash when the bash transport is enabled). Direct CLI use of resonate mcp is rare — agents wire it up via their MCP config. See resonate-bash for the full setup story.

Configuration layering

For resonate serve and resonate dev, configuration loads in this order — each layer overrides the previous:

1. Defaults — what --help shows.
2. `resonate.toml` — if present, picked up from the working directory.
3. *`RESONATE_ environment variables** — every CLI flag has an env-var equivalent. The leading -- becomes the RESONATE_ prefix; nested config segments are joined by a **double underscore** __ (a multi-word leaf key keeps a single _). E.g. --storage-postgres-url ⇄ RESONATE_STORAGE__POSTGRES__URL, --server-url ⇄ RESONATE_SERVER__URL, --auth-publickey ⇄ RESONATE_AUTH__PUBLICKEY, --tasks-retry-timeout ⇄ RESONATE_TASKS__RETRY_TIMEOUT. Run resonate serve --help` for exact names.
4. CLI flags — highest precedence.

Example resonate.toml:

[auth]
publickey = "/etc/resonate/auth/public.pem"

[storage]
type = "postgres"

[storage.postgres]
url = "${DATABASE_URL}"   # postgres://<user>:<password>@<host>:5432/resonate

This layering applies to the server, not the client subcommands. --server / --token on promises, schedules, etc. are read from flags or RESONATE_SERVER / RESONATE_TOKEN in the environment if set — they don't read resonate.toml.

Common workflows

Unblock a human-in-the-loop promise

A workflow is parked on ctx.promise({ id: "approval-456" }). To resolve it from outside any worker:

resonate promises resolve approval-456 --value '{"approved": true}'

Or reject with a reason:

resonate promises reject approval-456 --value '{"reason": "denied by reviewer"}'

Reproduce a bug by invoking a workflow manually

resonate invoke repro-$(date +%s) \
  --func processOrder \
  --arg '{"orderId":"123","forceFailure":true}' \
  --target poll://any@workers

The new promise gets a unique ID, the worker claims it, and you can resonate tree repro-… afterward to see the call graph.

Find stuck promises by project tag

Tag every promise on creation:

resonate promises create order-123 --timeout 24h --tags '{"project":"checkout"}'

Later, find every pending checkout promise:

resonate promises search --state pending --tags '{"project":"checkout"}' --limit 100

Audit what a schedule has produced

Tag promises emitted by a schedule and search by tag:

resonate schedules create nightly-report \
  --cron "0 2 * * *" \
  --promise-id "report-{{.timestamp}}" \
  --promise-timeout 1h \
  --promise-tags '{"source":"nightly-report"}'

# A week later:
resonate promises search --tags '{"source":"nightly-report"}' --limit 200

Smoke-test a deploy

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8001/health   # → 200
resonate invoke smoke-$(date +%s) --func ping --arg '{}' --timeout 30s

Connect to a remote server

resonate promises get order-123 \
  --server https://resonate.example.com \
  --token "$RESONATE_TOKEN"

Or export once for a shell session:

export RESONATE_SERVER=https://resonate.example.com
export RESONATE_TOKEN=eyJhbGciOi...
resonate promises search --state pending

Docs-vs-binary deltas

Older copies of the hosted docs show flags that the resonate 0.9.7 binary does not accept. When the docs disagree with resonate <cmd> --help, the binary wins. Known deltas at the time of writing:

Always check resonate <cmd> --help before scripting. The help text is generated from the binary and matches what the binary will accept.

Troubleshooting