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
  • gRPC API: localhost:50051
  • Metrics: http://localhost:9090

See resonate dev --help for options.

Start a production server​

Start with persistent SQLite storage
Shell
resonate serve --aio-store-sqlite-path /var/lib/resonate/resonate.db
Start with PostgreSQL
Shell
resonate serve \
  --aio-store-postgres-enable \
  --aio-store-postgres-host localhost \
  --aio-store-postgres-database resonate \
  --aio-store-postgres-username resonate \
  --aio-store-postgres-password secret

See resonate serve --help for all configuration options.

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 authentication, pass credentials with every command:

Token authentication:

Use bearer token
Shell
resonate promises get order-123 --token YOUR_TOKEN

Basic authentication:

Use username and password
Shell
resonate promises get order-123 --username admin --password secret

Or set environment variables:

Set auth via environment
Shell
export RESONATE_TOKEN="YOUR_TOKEN"
# or
export RESONATE_USERNAME="admin"
export RESONATE_PASSWORD="secret"

resonate promises get order-123  # Uses env vars automatically

Configuration files​

Instead of passing flags every time, create a configuration file:

resonate.yaml
YAML
api:
  http:
    addr: ":8001"
    auth:
      admin: "secret"
  
aio:
  store:
    postgres:
      enable: true
      host: "localhost"
      database: "resonate"
      username: "resonate"
      password: "secret"

Then start the server with the config:

Use configuration file
Shell
resonate serve --config resonate.yaml

See the server configuration reference for all available options.

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 http://localhost:8001/healthz

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​