CLI Reference

CLI Reference

All commands are invoked via cargo run --quiet -- <command> during development, or sparks <command> if installed.

---

Global Flags

Flag	Description
--config <path>	Path to config file (default: ./config.toml)
--quiet	Suppress cargo build output (use with cargo run)

---

chat

Start an interactive REPL session.

cargo run --quiet -- chat

Type a goal at the prompt. Sparks classifies the task, selects a ghost, executes it inside Docker, and returns the result. Type exit or quit to end the session.

---

dispatch

Dispatch a single task and optionally wait for completion.

cargo run --quiet -- dispatch \
  --goal "Add input validation to the login endpoint" \
  --repo Enreign/myapp \
  --wait-secs 120

Flag	Description
--goal <text>	Task goal (required)
--repo <owner/name>	Target repository
--wait-secs <n>	Wait up to N seconds for completion (default: don't wait)
--ghost <name>	Override ghost selection (bypass classifier)
--risk-tier <low|medium|high>	Set risk tier (default: medium)

---

ghosts

List all configured ghost agents.

cargo run --quiet -- ghosts

# Disable ~/.sparks profile overrides (deterministic output for CI)
SPARKS_DISABLE_HOME_PROFILES=1 cargo run --quiet -- ghosts

Output includes each ghost's name, description, strategy, and tool allowlist.

---

doctor

Run diagnostic checks.

# Full check (requires LLM connectivity)
cargo run --quiet -- doctor

# Skip LLM check
cargo run --quiet -- doctor --skip-llm

# Print security attestation
cargo run --quiet -- doctor --security

# CI mode (non-interactive, exit 1 on any failure)
cargo run --quiet -- doctor --ci

Flag	Description
--skip-llm	Skip LLM provider connectivity check
--security	Print security attestation instead of running funnels
--ci	Non-interactive mode; exits 1 on failure

---

kpi

Work with KPI snapshots.

# Print snapshot for a lane
cargo run --quiet -- kpi snapshot --lane delivery
cargo run --quiet -- kpi snapshot --lane self-improvement

# Print snapshot for a specific repo
cargo run --quiet -- kpi snapshot --repo emberloom/sparks

# Reset KPI data (use with caution)
cargo run --quiet -- kpi reset --lane delivery

---

dashboard

Generate an observability dashboard.

cargo run --quiet -- dashboard --output-format html
cargo run --quiet -- dashboard --output-format html --output-path ./dash.html

Flag	Description
--output-format	html (only format currently supported)
--output-path	Output file path (default: stdout)

---

feature

Feature contract workflow.

cargo run --quiet -- feature --help
cargo run --quiet -- feature run --contract feature.toml
cargo run --quiet -- feature status --contract feature.toml

See docs/feature-contract-workflow.md for contract format.

---

self-build

Supervised self-build workflow (self-improvement via autonomous task execution).

cargo run --quiet -- self-build --help
cargo run --quiet -- self-build run --batch backlog.toml

---

observe

Stream observer events to stdout in real time.

cargo run --quiet -- observe
cargo run --quiet -- observe --filter AutonomousTask,ToolUsage

Flag	Description
--filter <types>	Comma-separated event types to display (default: all)

---

secrets

Manage credentials in the OS keyring.

sparks secrets set openrouter.api_key
sparks secrets get openrouter.api_key
sparks secrets list
sparks secrets delete openrouter.api_key

---

openai

OpenAI provider management.

# OAuth login (stores tokens at ~/.sparks/openai.json)
cargo run --quiet -- openai login

# Check token status
cargo run --quiet -- openai status

---

Makefile Shortcuts

The Makefile wraps common development workflows:

make user-flow          # Linear ticket intake + writeback harness
make check              # cargo check + cargo test
make ci                 # Full CI gate (check, test, dead_code, wiring, hygiene, maintainability)

---

Environment Variables

Variable	Effect
SPARKS_DISABLE_HOME_PROFILES=1	Ignore ~/.sparks/ghosts/*.toml for deterministic output
SPARKS_ALLOW_INLINE_SECRETS=1	Allow secrets in config.toml (dev only)
SPARKS_OPENAI_API_KEY	Bearer key for the OpenAI-compatible API server
OPENROUTER_API_KEY	OpenRouter provider key
OPENCODE_API_KEY	Zen provider key
LINEAR_API_KEY	Linear ticket intake key
LANGFUSE_PUBLIC_KEY	Langfuse tracing public key
LANGFUSE_SECRET_KEY	Langfuse tracing secret key
LANGFUSE_BASE_URL	Langfuse instance URL