Skip to main content

statehousectl — CLI Reference

Command-line tool for interacting with the Statehouse daemon. Installed with the Python SDK (pip install statehouse).

Usage​

statehousectl [--address ADDRESS] COMMAND [OPTIONS]

Global option: --address ADDRESS — Daemon address (default: localhost:50051)

Commands​

health​

Check daemon health.

statehousectl health

version​

Show daemon version and Git SHA.

statehousectl version

get​

Get state for an agent and key.

statehousectl get AGENT_ID KEY [--namespace NAMESPACE] [--pretty]

keys​

List keys for an agent.

statehousectl keys AGENT_ID [--namespace NAMESPACE] [--prefix PREFIX]

replay​

Replay all events for an agent (pretty format by default).

statehousectl replay AGENT_ID [--namespace NAMESPACE] [--start-ts TS] [--end-ts TS] [--limit N] [--verbose] [--json]
  • --verbose — Full details (txn_id, payload)
  • --json — JSON lines (machine-readable)

tail​

Show last N events (pretty format).

statehousectl tail AGENT_ID [-n N] [--namespace NAMESPACE]

dump​

Dump all state for an agent to JSON.

statehousectl dump AGENT_ID [--namespace NAMESPACE] [-o FILE] [--format json|text]

Output format​

Replay and tail use a human-readable pretty format by default:

  • One operation per line
  • Timestamp (UTC), agent, operation type (WRITE, DEL, TOOL, NOTE, FINAL), key, version, value summary
  • Use --json for machine-readable JSONL

See also​