Skip to main content

Using the Resonate CLI

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
Shell
resonate --help
resonate <command> --help
resonate <command> <subcommand> --help

Examples:

See all available commands
Shell
resonate --help
Learn about the promises command
Shell
resonate promises --help
See how to resolve a promise
Shell
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
Shell
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
Shell
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
Shell
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
Shell
resonate promises create approval-456 --timeout 24h

Resolve a promise:

Unblock a waiting workflow
Shell
resonate promises resolve approval-456 --data '{"approved": true}'

Check promise state:

Inspect a promise
Shell
resonate promises get order-123

Search for promises:

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

Work with schedules​

Create a recurring schedule:

Run a function every hour
Shell
resonate schedules create hourly-sync \
  --cron "0 * * * *" \
  --promise-id "sync-{{.timestamp}}" \
  --description "Hourly data sync"

List schedules:

See all schedules
Shell
resonate schedules search "*"

Delete a schedule:

Remove a schedule
Shell
resonate schedules delete hourly-sync

Authentication​

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

Use bearer token
Shell
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
Shell
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
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​

Search for promises by pattern
Shell
resonate promises search "order-*" --limit 20

Format output as JSON​

Get machine-readable output
Shell
resonate promises get order-123 --output json

Useful for scripting and automation.

Check server health​

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

View metrics​

Prometheus metrics
Shell
curl http://localhost:9090/metrics

Connect to remote server​

Point CLI to a remote server
Shell
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:

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

Authentication failed​

Error: 401 Unauthorized

Solution:

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

Promise not found​

Error: 404 Not Found

Solution:

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

Next steps​