Quick Reference

ash Command Cheat Sheet

Agent Lifecycle

ash spawn <manifest.yaml>          # Spawn agent from manifest
ash validate <manifest.yaml>       # Validate manifest (no daemon needed)
ash list                           # List all running agents (alias: ash ls)
ash info <agent-id>                # Show agent details
ash kill <agent-id>                # Terminate an agent
ash transition <agent-id> <state>  # Force lifecycle transition (plan/act/observe/terminate)
ash ping                           # Check daemon is alive
ash status                         # Show daemon status

Tools

ash tools list                             # List all tools
ash tools list --agent <id>                # Tools accessible to a specific agent
ash tools invoke <agent-id> <tool> <json>  # Invoke a tool
ash tools schema <tool-name>               # Show tool input/output schema
ash tools proposed                         # List pending dynamic tool proposals
ash tools approve <proposal-id>            # Approve a tool proposal
ash tools deny <proposal-id>               # Deny a tool proposal

Audit & Observations

ash audit                          # Show last 20 audit entries
ash audit --agent <id>             # Filter by agent
ash audit --limit 100              # Show more entries
ash obs query <agent-id>           # Query observation log
ash obs query <agent-id> --keyword "error" --limit 10

Secrets

ash secrets add <name>             # Register secret (echo-off prompt)
ash secrets list                   # List secret names (no values)
ash secrets remove <name>          # Delete a secret
ash secrets policy add --label "..." --secret "name" --tool "web.fetch"
ash secrets policy list            # List policies
ash secrets policy remove <id>     # Remove a policy

Memory & Blackboard

ash memory read <agent-id> <key>           # Read persistent memory
ash memory write <agent-id> <key> <json>   # Write persistent memory
ash memory list <agent-id>                 # List memory keys
ash bb read <agent-id> <key>               # Read blackboard
ash bb write <agent-id> <key> <json>       # Write blackboard
ash bb list <agent-id>                     # List blackboard keys

Message Bus

ash bus publish <agent-id> <topic> <json>  # Publish to topic
ash bus subscribe <agent-id> <pattern>     # Subscribe to topic pattern
ash bus poll <agent-id>                    # Drain mailbox

Workspace

ash workspace snapshot <agent-id>          # Take snapshot
ash workspace history <agent-id>           # List snapshots
ash workspace diff <agent-id>              # Show changes vs last snapshot
ash workspace rollback <agent-id> <index>  # Roll back
ash workspace commit <agent-id>            # Commit overlay

Scheduler

ash scheduler stats                             # Global scheduler stats
ash scheduler info <agent-id>                   # Per-agent stats
ash scheduler set-deadline <agent-id> <rfc3339> # Set deadline
ash scheduler clear-deadline <agent-id>         # Clear deadline
ash scheduler set-priority <agent-id> <1-100>   # Set priority

Hierarchy & Escalations

ash hierarchy show        # Render agent tree
ash hierarchy escalations # List pending escalations
ash pending               # List pending HITL approval requests
ash approve <request-id>  # Approve a pending request
ash deny <request-id>     # Deny a pending request

Grants

ash grants list <agent-id>              # List capability grants
ash grants revoke <agent-id> <grant-id> # Revoke a grant

Anomaly Detection

ash anomaly list                       # List recent anomaly events
ash anomaly list --agent <id>          # Filter by agent

Replay

ash replay timeline <agent-id>              # Show full execution timeline
ash replay timeline <agent-id> --since <t>  # Since timestamp (RFC3339)
ash replay rollback <agent-id> <index>      # Roll back workspace

MCP

ash mcp add <name> stdio --command <cmd>  # Register stdio MCP server
ash mcp add <name> http --url <url>       # Register HTTP MCP server
ash mcp list                              # List registered servers
ash mcp remove <name>                     # Remove a server
ash mcp attach <agent-id> <server-name>   # Attach server to agent
ash mcp detach <agent-id> <server-name>   # Detach server from agent

Agent Store

ash agent install <manifest.yaml>      # Install agent
ash agent list                         # List installed agents
ash agent run <name>                   # Run installed agent by name
ash agent remove <name>                # Remove installed agent
ash agent capability-sheet <manifest>  # Print capability sheet

Key Environment Variables

VariableDescription
SCARAB_AGENT_IDUUID assigned to this agent by agentd
SCARAB_SOCKETPath to agentd Unix socket
SCARAB_TASKTask string from spec.task in manifest
SCARAB_MODELModel ID from spec.model in manifest
OPENROUTER_API_KEYAPI key for LLM tools
RUST_LOGLog verbosity (error/warn/info/debug/trace)

Capability Quick Reference

CapabilityGrants
tool.invoke:echoUse the echo tool
tool.invoke:lm.completeUse LLM completion
tool.invoke:fs.readRead files (scoped by fs.read:<path>)
tool.invoke:fs.writeWrite files (scoped by fs.write:<path>)
tool.invoke:web.fetchFetch URLs
tool.invoke:web.searchWeb search
tool.invoke:sandbox.execExecute code in sandbox
memory.read:*Read persistent memory
memory.write:*Write persistent memory
obs.appendAppend to observation log
obs.queryQuery observation log
secret.use:<name>Reference a named secret
sandbox.execAlias for sandbox.exec tool