Skip to main content

Usage Examples

Common workflows using the SOAT CLI. All examples assume a configured profile — see introduction for setup.

Configure a Profile​

soat configure
# Base URL: http://localhost:5047
# Token (hidden): <your-jwt-or-sdk-key>

Use --profile to work with multiple environments:

soat configure --profile prod
# Base URL: https://api.example.com
# Token (hidden): sk_...

soat --profile prod list-actors --project-id proj_01

List All Commands​

soat list-commands

Users​

Bootstrap the first admin user, then log in to obtain a session token:

soat bootstrap-user --username admin --password supersecret
soat login-user --username admin --password supersecret

Projects​

# Create a project
soat create-project --name "My Project"

# List all projects
soat list-projects

# Get a specific project
soat get-project --project-id proj_01

Actors​

# List actors for a project
soat list-actors --project-id proj_01

# Create an actor
soat create-actor --name "Support Bot" --project-id proj_01

# Get a specific actor
soat get-actor --actor-id actor_01

# Delete an actor
soat delete-actor --actor-id actor_01

Files​

# List files in a project
soat list-files --project-id proj_01

# Get a specific file
soat get-file --file-id file_01

# Delete a file
soat delete-file --file-id file_01

Testing Webhooks Locally​

soat listen starts a local HTTP server that receives webhook deliveries — both outbound Webhook deliveries and inbound Trigger X-Soat-Signature payloads — so you can inspect them before wiring up a real endpoint:

soat listen --port 8787 --path /webhook --secret "$WEBHOOK_SECRET"
# Listening for SOAT webhooks on http://localhost:8787/webhook

Point a webhook's url (or a webhook-type trigger's target, via a tunnel such as ngrok) at this address during development. Options:

  • --port — port to listen on (default 8787)
  • --path — request path to accept (default /webhook)
  • --secret — verify X-Soat-Signature against this webhook/trigger secret; the request is rejected with 401 on a signature mismatch
  • --filter — only print events matching a pattern, e.g. sessions.generation.*,files.* (comma-separated, trailing * wildcard)
  • --json — print one JSON object per line instead of a human-readable block

Each accepted delivery prints its event_type, delivery_id, and (when --secret is set) whether the signature was valid, followed by the pretty-printed payload.

Passing Body Fields​

All request body fields are passed as --flag value arguments. Field names follow the REST API contract but are exposed in kebab-case, and path parameters keep their resource-specific names:

soat create-actor --name "My Bot" --project-id proj_01
soat update-actor --actor-id actor_01 --name "Renamed Bot"

JSON Output​

Every command prints the API response as formatted JSON:

soat get-actor --actor-id actor_01
# {
#   "id": "actor_01",
#   "name": "Support Bot",
#   "type": "ai",
#   ...
# }

Pipe to jq for filtering:

soat list-actors --project-id proj_01 | jq '.[].name'