Commands Reference
Complete list of all CLI commands, grouped by module. Each command maps to one REST API operation.
Special Commands
| Command | Description |
|---|---|
soat configure | Add or update a profile in ~/.soat/config.json |
soat list-commands | Print all available API commands |
soat listen | Start a local webhook listener for testing deliveries |
Listener Examples
# Basic webhook listener
soat listen --port 8787 --path /webhook
# Filter only session generation lifecycle events
soat listen --port 8787 --path /webhook --filter sessions.generation.*
# Verify webhook signatures and output JSON lines
soat listen --port 8787 --path /webhook --secret "<webhook-secret>" --json
Actors
See Actors module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-actors | GET | /api/v1/api/v1/actors | --project-id, --external-id, --limit, --offset | List actors |
soat create-actor | POST | /api/v1/api/v1/actors | --<body fields> | Create an actor |
soat get-actor | GET | /api/v1/api/v1/actors/{actor_id} | --actor-id | Get an actor by ID |
soat delete-actor | DELETE | /api/v1/api/v1/actors/{actor_id} | --actor-id | Delete an actor |
soat update-actor | PATCH | /api/v1/api/v1/actors/{actor_id} | --actor-id, --<body fields> | Update an actor |
soat get-actor-tags | GET | /api/v1/api/v1/actors/{actor_id}/tags | --actor-id | Get actor tags |
soat replace-actor-tags | PUT | /api/v1/api/v1/actors/{actor_id}/tags | --actor-id, --<body fields> | Replace actor tags |
soat merge-actor-tags | PATCH | /api/v1/api/v1/actors/{actor_id}/tags | --actor-id, --<body fields> | Merge actor tags |
AgentFormations
See AgentFormations module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat validate-agent-formation | POST | /api/v1/api/v1/agent-formations/validate | --<body fields> | Validate a formation template |
soat plan-agent-formation | POST | /api/v1/api/v1/agent-formations/plan | --<body fields> | Plan a formation deployment |
soat list-agent-formations | GET | /api/v1/api/v1/agent-formations | --project-id | List agent formations |
soat create-agent-formation | POST | /api/v1/api/v1/agent-formations | --<body fields> | Create a new agent formation |
soat get-agent-formation | GET | /api/v1/api/v1/agent-formations/{formation_id} | --formation-id | Get a specific agent formation |
soat update-agent-formation | PUT | /api/v1/api/v1/agent-formations/{formation_id} | --formation-id, --<body fields> | Update an agent formation |
soat delete-agent-formation | DELETE | /api/v1/api/v1/agent-formations/{formation_id} | --formation-id | Delete an agent formation |
soat list-agent-formation-events | GET | /api/v1/api/v1/agent-formations/{formation_id}/events | --formation-id | List formation operation events |
Agents
See Agents module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat create-agent-tool | POST | /api/v1/api/v1/agents/tools | --<body fields> | Create an agent tool |
soat list-agent-tools | GET | /api/v1/api/v1/agents/tools | --project-id | List agent tools |
soat get-agent-tool | GET | /api/v1/api/v1/agents/tools/{tool_id} | --tool-id | Get an agent tool |
soat update-agent-tool | PUT | /api/v1/api/v1/agents/tools/{tool_id} | --tool-id, --<body fields> | Update an agent tool |
soat delete-agent-tool | DELETE | /api/v1/api/v1/agents/tools/{tool_id} | --tool-id | Delete an agent tool |
soat create-agent | POST | /api/v1/api/v1/agents | --<body fields> | Create an agent |
soat list-agents | GET | /api/v1/api/v1/agents | --project-id | List agents |
soat get-agent | GET | /api/v1/api/v1/agents/{agent_id} | --agent-id | Get an agent |
soat update-agent | PUT | /api/v1/api/v1/agents/{agent_id} | --agent-id, --<body fields> | Update an agent |
soat delete-agent | DELETE | /api/v1/api/v1/agents/{agent_id} | --agent-id | Delete an agent |
soat create-agent-generation | POST | /api/v1/api/v1/agents/{agent_id}/generate | --agent-id, --<body fields> | Run an agent generation |
soat submit-agent-tool-outputs | POST | /api/v1/api/v1/agents/{agent_id}/generate/{generation_id}/tool-outputs | --agent-id, --generation-id, --<body fields> | Submit tool outputs for a paused generation |
soat create-agent-actor | POST | /api/v1/api/v1/agents/{agent_id}/actors | --agent-id, --<body fields> | Create an actor for an agent |
AI Providers
See AI Providers module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-ai-providers | GET | /api/v1/api/v1/ai-providers | --project-id, --limit, --offset | List AI providers |
soat create-ai-provider | POST | /api/v1/api/v1/ai-providers | --<body fields> | Create an AI provider |
soat get-ai-provider | GET | /api/v1/api/v1/ai-providers/{ai_provider_id} | --ai-provider-id | Get an AI provider |
soat update-ai-provider | PATCH | /api/v1/api/v1/ai-providers/{ai_provider_id} | --ai-provider-id, --<body fields> | Update an AI provider |
soat delete-ai-provider | DELETE | /api/v1/api/v1/ai-providers/{ai_provider_id} | --ai-provider-id | Delete an AI provider |
API Keys
See API Keys module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-api-keys | GET | /api/v1/api/v1/api-keys | — | List API keys |
soat create-api-key | POST | /api/v1/api/v1/api-keys | --<body fields> | Create an API key |
soat get-api-key | GET | /api/v1/api/v1/api-keys/{api_key_id} | --api-key-id | Get an API key |
soat update-api-key | PUT | /api/v1/api/v1/api-keys/{api_key_id} | --api-key-id, --<body fields> | Update an API key |
soat delete-api-key | DELETE | /api/v1/api/v1/api-keys/{api_key_id} | --api-key-id | Delete an API key |
Chats
See Chats module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat create-chat | POST | /api/v1/api/v1/chats | --<body fields> | Create a chat |
soat list-chats | GET | /api/v1/api/v1/chats | --project-id | List chats |
soat get-chat | GET | /api/v1/api/v1/chats/{chat_id} | --chat-id | Get a chat |
soat delete-chat | DELETE | /api/v1/api/v1/chats/{chat_id} | --chat-id | Delete a chat |
soat create-chat-completion-for-chat | POST | /api/v1/api/v1/chats/{chat_id}/completions | --chat-id, --<body fields> | Create a chat completion for a stored chat |
soat create-chat-completion | POST | /api/v1/api/v1/chats/completions | --<body fields> | Create a chat completion (stateless) |
soat create-chat-actor | POST | /api/v1/api/v1/chats/{chat_id}/actors | --chat-id, --<body fields> | Create an actor for a chat |
Conversations
See Conversations module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-conversations | GET | /api/v1/api/v1/conversations | --project-id, --actor-id, --limit, --offset | List conversations |
soat create-conversation | POST | /api/v1/api/v1/conversations | --<body fields> | Create a conversation |
soat get-conversation | GET | /api/v1/api/v1/conversations/{conversation_id} | --conversation-id | Get a conversation by ID |
soat update-conversation | PATCH | /api/v1/api/v1/conversations/{conversation_id} | --conversation-id, --<body fields> | Update a conversation |
soat delete-conversation | DELETE | /api/v1/api/v1/conversations/{conversation_id} | --conversation-id | Delete a conversation |
soat list-conversation-messages | GET | /api/v1/api/v1/conversations/{conversation_id}/messages | --conversation-id, --limit, --offset | List conversation messages |
soat add-conversation-message | POST | /api/v1/api/v1/conversations/{conversation_id}/messages | --conversation-id, --<body fields> | Add a message to a conversation |
soat generate-conversation-message | POST | /api/v1/api/v1/conversations/{conversation_id}/generate | --conversation-id, --<body fields> | Generate the next message in a conversation |
soat list-conversation-actors | GET | /api/v1/api/v1/conversations/{conversation_id}/actors | --conversation-id | List actors in a conversation |
soat remove-conversation-message | DELETE | /api/v1/api/v1/conversations/{conversation_id}/messages/{document_id} | --conversation-id, --document-id | Remove a message from a conversation |
soat get-conversation-tags | GET | /api/v1/api/v1/conversations/{conversation_id}/tags | --conversation-id | Get conversation tags |
soat replace-conversation-tags | PUT | /api/v1/api/v1/conversations/{conversation_id}/tags | --conversation-id, --<body fields> | Replace conversation tags |
soat merge-conversation-tags | PATCH | /api/v1/api/v1/conversations/{conversation_id}/tags | --conversation-id, --<body fields> | Merge conversation tags |
Documents
See Documents module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-documents | GET | /api/v1/api/v1/documents | --project-id | List documents |
soat create-document | POST | /api/v1/api/v1/documents | --<body fields> | Create a document |
soat get-document | GET | /api/v1/api/v1/documents/{document_id} | --document-id | Get a document by ID |
soat delete-document | DELETE | /api/v1/api/v1/documents/{document_id} | --document-id | Delete a document |
soat update-document | PATCH | /api/v1/api/v1/documents/{document_id} | --document-id, --<body fields> | Update a document |
soat get-document-tags | GET | /api/v1/api/v1/documents/{document_id}/tags | --document-id | Get document tags |
soat replace-document-tags | PUT | /api/v1/api/v1/documents/{document_id}/tags | --document-id, --<body fields> | Replace document tags |
soat merge-document-tags | PATCH | /api/v1/api/v1/documents/{document_id}/tags | --document-id, --<body fields> | Merge document tags |
Files
See Files module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-files | GET | /api/v1/api/v1/files | --project-id, --limit, --offset | List all files |
soat create-file | POST | /api/v1/api/v1/files | --<body fields> | Create a file |
soat upload-file | POST | /api/v1/api/v1/files/upload | --<body fields> | Upload a file |
soat upload-file-base64 | POST | /api/v1/api/v1/files/upload/base64 | --<body fields> | Upload a file using base64 encoding |
soat get-file | GET | /api/v1/api/v1/files/{file_id} | --file-id | Get a file by ID |
soat delete-file | DELETE | /api/v1/api/v1/files/{file_id} | --file-id | Delete a file |
soat download-file | GET | /api/v1/api/v1/files/{file_id}/download | --file-id | Download a file |
soat update-file-metadata | PATCH | /api/v1/api/v1/files/{file_id}/metadata | --file-id, --<body fields> | Update file metadata |
soat download-file-base64 | GET | /api/v1/api/v1/files/{file_id}/download/base64 | --file-id | Download file as base64 |
soat get-file-tags | GET | /api/v1/api/v1/files/{file_id}/tags | --file-id | Get file tags |
soat replace-file-tags | PUT | /api/v1/api/v1/files/{file_id}/tags | --file-id, --<body fields> | Replace file tags |
soat merge-file-tags | PATCH | /api/v1/api/v1/files/{file_id}/tags | --file-id, --<body fields> | Merge file tags |
Knowledge
See Knowledge module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat search-knowledge | POST | /api/v1/api/v1/knowledge/search | --<body fields> | Search knowledge |
Memories
See Memories module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-memories | GET | /api/v1/api/v1/memories | --project-id, --tags | List memories |
soat create-memory | POST | /api/v1/api/v1/memories | --<body fields> | Create a memory |
soat get-memory | GET | /api/v1/api/v1/memories/{memory_id} | --memory-id | Get a memory |
soat update-memory | PUT | /api/v1/api/v1/memories/{memory_id} | --memory-id, --<body fields> | Update a memory |
soat delete-memory | DELETE | /api/v1/api/v1/memories/{memory_id} | --memory-id | Delete a memory |
MemoryEntries
See MemoryEntries module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-memory-entries | GET | /api/v1/api/v1/memories/{memory_id}/entries | --memory-id | List memory entries |
soat create-memory-entry | POST | /api/v1/api/v1/memories/{memory_id}/entries | --memory-id, --<body fields> | Create a memory entry |
soat get-memory-entry | GET | /api/v1/api/v1/memories/{memory_id}/entries/{entry_id} | --memory-id, --entry-id | Get a memory entry |
soat update-memory-entry | PUT | /api/v1/api/v1/memories/{memory_id}/entries/{entry_id} | --memory-id, --entry-id, --<body fields> | Update a memory entry |
soat delete-memory-entry | DELETE | /api/v1/api/v1/memories/{memory_id}/entries/{entry_id} | --memory-id, --entry-id | Delete a memory entry |
Policies
See Policies module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-policies | GET | /api/v1/api/v1/policies | — | List all policies |
soat create-policy | POST | /api/v1/api/v1/policies | --<body fields> | Create a policy |
soat get-policy | GET | /api/v1/api/v1/policies/{policy_id} | --policy-id | Get a policy |
soat update-policy | PUT | /api/v1/api/v1/policies/{policy_id} | --policy-id, --<body fields> | Update a policy |
soat delete-policy | DELETE | /api/v1/api/v1/policies/{policy_id} | --policy-id | Delete a policy |
Projects
See Projects module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat create-project | POST | /api/v1/api/v1/projects | --<body fields> | Create a project |
soat get-project | GET | /api/v1/api/v1/projects/{project_id} | --project-id | Get a project |
soat delete-project | DELETE | /api/v1/api/v1/projects/{project_id} | --project-id | Delete a project |
Secrets
See Secrets module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-secrets | GET | /api/v1/api/v1/secrets | --project-id, --limit, --offset | List secrets |
soat create-secret | POST | /api/v1/api/v1/secrets | --<body fields> | Create a secret |
soat get-secret | GET | /api/v1/api/v1/secrets/{secret_id} | --secret-id | Get a secret |
soat update-secret | PATCH | /api/v1/api/v1/secrets/{secret_id} | --secret-id, --<body fields> | Update a secret |
soat delete-secret | DELETE | /api/v1/api/v1/secrets/{secret_id} | --secret-id | Delete a secret |
Sessions
See Sessions module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat create-agent-session | POST | /api/v1/api/v1/agents/{agent_id}/sessions | --<body fields> | Create a session |
soat list-agent-sessions | GET | /api/v1/api/v1/agents/{agent_id}/sessions | --actor-id, --status, --limit, --offset | List sessions |
soat get-agent-session | GET | /api/v1/api/v1/agents/{agent_id}/sessions/{session_id} | — | Get a session |
soat update-session | PATCH | /api/v1/api/v1/agents/{agent_id}/sessions/{session_id} | --<body fields> | Update a session |
soat delete-agent-session | DELETE | /api/v1/api/v1/agents/{agent_id}/sessions/{session_id} | — | Delete a session |
soat list-agent-session-messages | GET | /api/v1/api/v1/agents/{agent_id}/sessions/{session_id}/messages | --limit, --offset | List session messages |
soat add-session-message | POST | /api/v1/api/v1/agents/{agent_id}/sessions/{session_id}/messages | --<body fields> | Add a user message |
soat generate-session-response | POST | /api/v1/api/v1/agents/{agent_id}/sessions/{session_id}/generate | --async, --<body fields> | Trigger agent generation |
soat submit-session-tool-outputs | POST | /api/v1/api/v1/agents/{agent_id}/sessions/{session_id}/tool-outputs | --<body fields> | Submit tool outputs |
soat get-session-tags | GET | /api/v1/api/v1/agents/{agent_id}/sessions/{session_id}/tags | — | Get session tags |
soat replace-session-tags | PUT | /api/v1/api/v1/agents/{agent_id}/sessions/{session_id}/tags | --<body fields> | Replace session tags |
soat merge-session-tags | PATCH | /api/v1/api/v1/agents/{agent_id}/sessions/{session_id}/tags | --<body fields> | Merge session tags |
Traces
See Traces module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-traces | GET | /api/v1/api/v1/traces | --project-id, --limit, --offset | List traces |
soat get-trace | GET | /api/v1/api/v1/traces/{trace_id} | --trace-id | Get a trace |
soat get-trace-tree | GET | /api/v1/api/v1/traces/{trace_id}/tree | --trace-id | Get trace tree |
Users
See Users module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-users | GET | /api/v1/api/v1/users | — | List all users |
soat create-user | POST | /api/v1/api/v1/users | --<body fields> | Create a user |
soat get-user | GET | /api/v1/api/v1/users/{user_id} | --user-id | Get a user by ID |
soat delete-user | DELETE | /api/v1/api/v1/users/{user_id} | --user-id | Delete a user by ID |
soat bootstrap-user | POST | /api/v1/api/v1/users/bootstrap | --<body fields> | Create the first admin user |
soat login-user | POST | /api/v1/api/v1/users/login | --<body fields> | Login user |
soat get-user-policies | GET | /api/v1/api/v1/users/{user_id}/policies | --user-id | Get policies attached to a user |
soat attach-user-policies | PUT | /api/v1/api/v1/users/{user_id}/policies | --user-id, --<body fields> | Attach policies to a user |
Webhooks
See Webhooks module docs for permissions and data model.
| Command | HTTP | Path | Flags | Description |
|---|---|---|---|---|
soat list-webhooks | GET | /api/v1/api/v1/projects/{project_id}/webhooks | --project-id | List webhooks for a project |
soat create-webhook | POST | /api/v1/api/v1/projects/{project_id}/webhooks | --project-id, --<body fields> | Create a webhook |
soat get-webhook | GET | /api/v1/api/v1/projects/{project_id}/webhooks/{webhook_id} | --project-id, --webhook-id | Get a webhook |
soat update-webhook | PUT | /api/v1/api/v1/projects/{project_id}/webhooks/{webhook_id} | --project-id, --webhook-id, --<body fields> | Update a webhook |
soat delete-webhook | DELETE | /api/v1/api/v1/projects/{project_id}/webhooks/{webhook_id} | --project-id, --webhook-id | Delete a webhook |
soat list-webhook-deliveries | GET | /api/v1/api/v1/projects/{project_id}/webhooks/{webhook_id}/deliveries | --project-id, --webhook-id, --limit, --offset | List deliveries for a webhook |
soat get-webhook-delivery | GET | /api/v1/api/v1/projects/{project_id}/webhooks/{webhook_id}/deliveries/{delivery_id} | --project-id, --webhook-id, --delivery-id | Get a delivery |
soat rotate-webhook-secret | POST | /api/v1/api/v1/projects/{project_id}/webhooks/{webhook_id}/rotate-secret | --project-id, --webhook-id, --<body fields> | Rotate webhook secret |