CLI Reference

Synopsis

heartbit [run|chat|serve|daemon|submit|status|approve|result] <args>
heartbit <task>                  # shorthand for 'run'

When invoked without a subcommand, heartbit <task> is treated as heartbit run <task>.

Commands

run <task>

Execute a task in standalone mode and exit.

heartbit run "Analyze the Rust ecosystem"
heartbit "Analyze the Rust ecosystem"   # equivalent shorthand

Without --config, the CLI builds a single AgentRunner with all 14 built-in tools and reads configuration from environment variables. With --config, it loads the TOML file and builds an Orchestrator (or a direct AgentRunner when only one agent is defined).

chat

Interactive multi-turn REPL. Default max turns: 200.

heartbit chat
heartbit chat --config heartbit.toml

serve

Start a Restate HTTP worker for durable execution. Requires the restate feature flag.

heartbit serve --config heartbit.toml

daemon

Run the Kafka-backed daemon with HTTP API, cron scheduling, WebSocket, SSE, and optional Telegram bot. Requires the daemon feature flag.

heartbit daemon --config daemon.toml

submit <task>

Submit a task for durable execution via Restate. Returns a workflow ID.

heartbit submit "Write a report" --config heartbit.toml

status <id>

Query the status of a durable workflow by its ID.

heartbit status wf_abc123 --config heartbit.toml

approve <id>

Send an approval signal to a durable workflow waiting for human-in-the-loop confirmation.

heartbit approve wf_abc123 --config heartbit.toml

result <id>

Get the completed result of a durable workflow.

heartbit result wf_abc123 --config heartbit.toml

Global Flags

Flag	Description
--config <path>	Path to a heartbit.toml configuration file. When omitted, the CLI uses environment variables for configuration.
--observability <level>	Observability verbosity: production, analysis, or debug.

Per-Command Flags

Flag	Available on	Description
--approve	run, chat, submit	Enable human-in-the-loop approval. The CLI prompts before each tool execution round. Denied tools receive error results so the LLM can adjust and retry.
-v, --verbose	run, chat, daemon	Emit structured AgentEvent payloads as JSON to stderr. Useful for debugging and observability.
--bind <addr>	serve, daemon	Address to bind the HTTP server (serve default: 0.0.0.0:9080).
--restate-url <url>	submit, status, approve, result	Restate ingress URL (overrides config; defaults to http://localhost:8080).

Examples

# Standalone with env vars only
export ANTHROPIC_API_KEY=sk-...
heartbit "Summarize this project"

# With config file and approval
heartbit run "Deploy to staging" --config heartbit.toml --approve

# Interactive chat with verbose events
heartbit chat --config heartbit.toml -v

# Durable execution workflow
heartbit serve --config heartbit.toml &
heartbit submit "Generate quarterly report" --config heartbit.toml
# => wf_abc123
heartbit status wf_abc123 --config heartbit.toml
heartbit result wf_abc123 --config heartbit.toml