Using the Resonate CLI

Learn how to use the Resonate command-line interface effectively.

The Resonate CLI is your primary tool for running the server, managing Durable Promises, and interacting with the Resonate system.

Getting help#

The CLI has excellent built-in help. Use --help on any command to see detailed usage:

Get help on any command

resonate --help
resonate <command> --help
resonate <command> <subcommand> --help

Examples:

See all available commands

resonate --help

Learn about the promises command

resonate promises --help

See how to resolve a promise

resonate promises resolve --help

Always check --help first

The CLI help is always up-to-date with your installed version. The built-in examples show exactly what syntax to use.

Common workflows#

Start a development server#

Start server with in-memory storage

resonate dev

The server starts on:

HTTP API: http://localhost:8001
Metrics: http://localhost:9090

See resonate dev --help for options.

Start a production server#

Start with PostgreSQL

resonate serve \
  --storage-type postgres \
  --storage-postgres-url "postgres://resonate:secret@localhost:5432/resonate"

See resonate serve --help for all flags, or Run a server for the full configuration story (resonate.toml + env vars + flags).

Invoke a function#

Trigger a function manually

resonate invoke order-123 --func processOrder --arg '{"orderId": "123"}'

Useful for:

Testing functions outside your application
Triggering workflows manually
Debugging function behavior

Manage Durable Promises#

Create a promise:

Create a promise for human-in-the-loop

resonate promises create approval-456 --timeout 24h

Resolve a promise:

Unblock a waiting workflow

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

Check promise state:

Inspect a promise

resonate promises get order-123

Search for promises:

Find pending promises

resonate promises search "*" --state pending --limit 10

Work with schedules#

Create a recurring schedule:

Run a function every hour

resonate schedules create hourly-sync \
  --cron "0 * * * *" \
  --promise-id "sync-{{.timestamp}}" \
  --description "Hourly data sync"

List schedules:

See all schedules

resonate schedules search "*"

Delete a schedule:

Remove a schedule

resonate schedules delete hourly-sync

Authentication#

If your server requires JWT auth, pass a bearer token with every CLI call:

Use bearer token

resonate promises get order-123 --token YOUR_TOKEN

The --token flag is a global option — it works on every subcommand.

See Security for how to enable JWT auth on the server.

Configuration#

The Resonate server is configured by layering, in this order: defaults → resonate.toml (optional) → RESONATE_* env vars → CLI flags. Any of the four can override the previous.

Example: serve with auth and PostgreSQL via flags

resonate serve \
  --auth-publickey /etc/resonate/auth/public.pem \
  --storage-type postgres \
  --storage-postgres-url "postgres://resonate:secret@localhost:5432/resonate"

The same configuration as a resonate.toml:

resonate.toml

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

[storage]
type = "postgres"

[storage.postgres]
url = "postgres://resonate:secret@localhost:5432/resonate"

Run resonate serve --help for all available flags.

Tips and tricks#

Use wildcards for search#

Search for promises by pattern

resonate promises search "order-*" --limit 20

Format output as JSON#

Get machine-readable output

resonate promises get order-123 --output json

Useful for scripting and automation.

Check server health#

Verify server is running

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8001/health
# 200 when healthy

View metrics#

Prometheus metrics

curl http://localhost:9090/metrics

Connect to remote server#

Point CLI to a remote server

resonate promises get order-123 --server https://resonate.yourcompany.com

Troubleshooting#

Command not found#

Error: resonate: command not found

Solution: Install the Resonate CLI using Homebrew or download from GitHub releases.

Connection refused#

Error: connect: connection refused

Solution:

Is the server running? Start it with resonate dev
Using the correct URL? Default is http://localhost:8001
Check the --server flag points to the right address

Authentication failed#

Error: 401 Unauthorized

Solution:

Does your server require auth? Check the server configuration
Providing correct credentials? Use --token or --username/--password
Using the right auth method? (token vs basic)

Promise not found#

Error: 404 Not Found

Solution:

Check the promise ID is correct (IDs are case-sensitive)
Was the promise created? Use resonate promises search to verify
Did the promise expire? Check timeout settings

Next steps#

Start a development server (resonate dev) and connect your SDK
Explore example applications that show real-world CLI usage
Read about production deployment with persistent storage
Review the TypeScript SDK guide or Python SDK guide