Skip to main content
The agent command runs an agent turn via the Gateway, and the agents command manages isolated agents with their own workspaces, authentication, and routing.

​
agent

Run an agent turn via the Gateway (use --local for embedded execution). 
simpleclaw agent --message <text>
​
--message
string
required
Message body for the agent
​
--to
string
Recipient number in E.164 format used to derive the session key
​
--session-id
string
Use an explicit session id
​
--agent
string
Agent id (overrides routing bindings)
​
--thinking
string
Thinking level: off, minimal, low, medium, or high
​
--verbose
string
Persist agent verbose level for the session: on or off
​
--channel
string
Delivery channel (omit to use the main session channel)
​
--reply-to
string
Delivery target override (separate from session routing)
​
--reply-channel
string
Delivery channel override (separate from routing)
​
--reply-account
string
Delivery account id override
​
--local
boolean
Run the embedded agent locally (requires model provider API keys in your shell)
​
--deliver
boolean
Send the agent’s reply back to the selected channel
​
--json
boolean
Output result as JSON
​
--timeout
number
Override agent command timeout in seconds (default: 600 or config value)

​
Examples

# Start a new session
simpleclaw agent --to +15555550123 --message "status update"

# Use a specific agent
simpleclaw agent --agent ops --message "Summarize logs"

# Target a session with explicit thinking level
simpleclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium

# Enable verbose logging and JSON output
simpleclaw agent --to +15555550123 --message "Trace logs" --verbose on --json

# Deliver reply
simpleclaw agent --to +15555550123 --message "Summon reply" --deliver

# Send reply to a different channel/target
simpleclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"

​
agents

Manage isolated agents (workspaces, auth, and routing).

​
agents list

List configured agents. 
simpleclaw agents list
​
--json
boolean
Output JSON instead of text
​
--bindings
boolean
Include routing bindings

​
agents add

Add a new isolated agent. 
simpleclaw agents add [name]
​
name
string
Agent name (optional positional argument)
​
--workspace
string
Workspace directory for the new agent
​
--model
string
Model id for this agent
​
--agent-dir
string
Agent state directory for this agent
​
--bind
string
Route channel binding (repeatable): channel[:accountId]
​
--non-interactive
boolean
Disable prompts; requires --workspace
​
--json
boolean
Output JSON summary

​
agents set-identity

Update an agent identity (name, theme, emoji, avatar). 
simpleclaw agents set-identity
​
--agent
string
Agent id to update
​
--workspace
string
Workspace directory used to locate the agent and IDENTITY.md
​
--identity-file
string
Explicit IDENTITY.md path to read
​
--from-identity
boolean
Read values from IDENTITY.md
​
--name
string
Identity name
​
--theme
string
Identity theme
​
--emoji
string
Identity emoji
​
--avatar
string
Identity avatar (workspace path, http(s) URL, or data URI)
​
--json
boolean
Output JSON summary
Examples: 
# Set name and emoji
simpleclaw agents set-identity --agent main --name "SimpleClaw" --emoji "🦞"

# Set avatar path
simpleclaw agents set-identity --agent main --avatar avatars/simpleclaw.png

# Load from IDENTITY.md
simpleclaw agents set-identity --workspace ~/.simpleclaw/workspace --from-identity

# Use a specific IDENTITY.md
simpleclaw agents set-identity --identity-file ~/.simpleclaw/workspace/IDENTITY.md --agent main

​
agents delete

Delete an agent and prune workspace/state. 
simpleclaw agents delete <id>
​
id
string
required
Agent id to delete
​
--force
boolean
Skip confirmation
​
--json
boolean
Output JSON summary

Build docs developers (and LLMs) love

Get started for freeTalk to us