Core & System Commands

Setup & system

`sf init`

Initialize a new Stoneforge workspace in the current directory.

sf init [--name <name>] [--actor <actor>]

Creates a .stoneforge/ directory containing config.yaml, stoneforge.db, .gitignore, and a playbooks/ directory. If .stoneforge/ already exists (e.g. after cloning) but no database is present, it creates the database and auto-imports from existing JSONL sync files.

Option	Description
`--name <name>`	Workspace name (stored in config.yaml)
`--actor <actor>`	Default actor for operations

`sf serve`

Start the Stoneforge server and web dashboard.

Orchestrator (default)
Data platform only

# Start the orchestrator server + dashboard
sf serve
# or explicitly:
sf serve smithy --port 3457

# Start just the Quarry data server
sf serve quarry --port 3456

Option	Description
`-p, --port <port>`	Port to listen on
`-H, --host <host>`	Host to bind to

`sf doctor`

Check system health and diagnose issues. Runs diagnostic checks including: workspace, database, connection, schema version, schema tables, integrity, foreign keys, blocked cache consistency, and storage size. When the orchestrator server is running, additional runtime health checks are performed (rate limit status, stuck tasks, merge queue health, error rate, agent pool utilization).

sf doctor [--fix] [--verbose] [--json]

Option	Description
`--fix`	Automatically repair detected issues (foreign key violations, blocked cache inconsistencies)
`--verbose`	Show detailed diagnostic information
`--json`	Output as JSON

sf doctor

System Health Check

[OK] workspace: Workspace found at /Users/you/my-project/.stoneforge

[OK] database: Database connection successful

[OK] schema_version: Schema is at version 9 (up to date)

[OK] blocked_cache: Blocked cache is consistent

Summary: 9 ok, 0 warnings, 0 errors

`sf stats`

Show workspace statistics — element counts by type, ready/blocked tasks, dependency and event counts, database size.

sf stats [--json]

`sf whoami`

Show the current actor identity. Also available as sf identity whoami.

`sf completion`

Generate shell completion scripts.

source <(sf completion bash)
# or persist:
sf completion bash > ~/.local/share/bash-completion/completions/sf

source <(sf completion zsh)
# or persist:
sf completion zsh > ~/.zsh/completions/_sf

sf completion fish > ~/.config/fish/completions/sf.fish

`sf migrate`

Run database migrations. Migrations run automatically when needed, but this lets you check status or trigger manually.

sf migrate [--dry-run]

`sf reset`

Reset a Stoneforge workspace.

sf reset [--force] [--full] [-s, --server <url>]

Default reset removes the database, sync files, uploads, and worktrees but preserves config.yaml. Full reset deletes the entire .stoneforge/ folder and reinitializes.

CRUD commands

Generic element operations that work across all types.

`sf create`

sf create <type> [options]

Option	Description
`-t, --title <text>`	Title (required for tasks)
`-n, --name <text>`	Alias for `--title`
`-d, --description <text>`	Description (creates a linked document)
`-p, --priority <1-5>`	Priority: 1 = critical, 5 = minimal
`-c, --complexity <1-5>`	Complexity: 1 = trivial, 5 = very complex
`--type <type>`	Task type: `bug`, `feature`, `task`, `chore`
`-a, --assignee <id>`	Assignee entity ID
`--tag <tag>`	Add tag (repeatable)
`--plan <id\|name>`	Attach to a plan

sf create task --title "Fix login bug" --priority 1 --type bug
sf create task -t "Add dark mode" -d "Implement theme switching" --tag ui
sf create task -t "Implement feature" --plan "Sprint 3"

`sf list`

sf list [type] [--status <s>] [--priority <1-5>] [--assignee <id>] [--tag <tag>] [--limit <n>] [--offset <n>]

Filter values accept exact matches. Arrays use OR matching for status and priority.

`sf show`

sf show <id> [--events] [--events-limit <n>]

Displays detailed information about any element. Supports short IDs (prefix matching).

`sf update`

sf update <id> [--title <text>] [--status <s>] [--priority <1-5>] [--complexity <1-5>] [--tag <tag>] [--add-tag <tag>] [--remove-tag <tag>] [--assignee <id>]

Pass --assignee "" to unassign. Use --tag to replace all tags, or --add-tag/--remove-tag for incremental changes.

`sf delete`

Soft-delete an element (tombstone). Messages cannot be deleted — they are immutable.

sf delete <id> [--reason <text>] [--force]

Embeddings commands

sf embeddings install                          # Install local model
sf embeddings status                           # Model status
sf embeddings reindex                          # Rebuild index
sf embeddings search "authentication flow"     # Semantic search

Sync commands

Also available under sf sync export, sf sync import, sf sync status.

`sf export`

sf export [--output <dir>] [--full] [--include-ephemeral]

`sf import`

sf import [--input <dir>] [--dry-run] [--force]

`sf status`

Show sync status — dirty elements, last export time.

Config commands

sf config show [key]
sf config set <path> <value>
sf config unset <path>
sf config edit

See the Configuration reference for all available config paths.

Identity commands

sf identity whoami
sf identity keygen [--json] [--quiet]
sf identity mode [soft|cryptographic|hybrid]
sf identity sign --data "text" --sign-key <key> --actor <name>
sf identity verify --signature <sig> --public-key <key> --signed-at <time> --data "text"
sf identity hash --data "text"

See the Identity reference for full details on modes, key management, and signature verification.

Garbage collection

sf gc workflows [--age <days>] [--limit <n>] [--dry-run]

	`sf gc workflows`	`sf workflow gc`
Default age	1 day	7 days
`--limit` flag	Yes	No
Best for	Automated cleanup (cron)	Manual cleanup

History command

View the event timeline for any element.

sf history <id> [--type <event-type>] [--actor <name>] [--after <date>] [--before <date>] [--format timeline|table] [--limit <n>]

Install command

sf install skills [--force]

Installs Claude skills files to .claude/skills/. Use --force to overwrite existing files.

Docs commands

`sf docs init`

Bootstrap the Documentation library and Documentation Directory for the workspace. Idempotent — running multiple times produces the same result without duplicates.

sf docs init [--json] [--quiet]

Creates:

A Documentation library (if it doesn’t exist)
A Documentation Directory document (reference category, with a starter template)
A parent-child link between the directory and the library

`sf docs add`

Add one or more documents to the Documentation library.

sf docs add <doc-id> [doc-id2 ...]

The Documentation library must exist — run sf docs init first. Already-added documents are skipped.

sf docs add el-doc123
sf docs add el-doc123 el-doc456 el-doc789

`sf docs dir`

Show the Documentation Directory document.

sf docs dir [--content] [--json] [--quiet]

Option	Description
`--content`	Include the full document content in output

Log command

View operation log entries — dispatches, merges, sessions, rate-limits, steward actions, and recovery events.

sf log [--level <level>] [--category <cat>] [--since <time>] [--task <id>] [--agent <id>] [--limit <n>]

Option	Description
`--level <level>`	Filter by log level: `info`, `warn`, `error`
`-c, --category <cat>`	Filter by category: `dispatch`, `merge`, `session`, `rate-limit`, `steward`, `recovery`
`-s, --since <time>`	Show entries since time — accepts relative time (`2h`, `30m`, `1d`, `1w`) or ISO 8601 timestamp
`-t, --task <id>`	Filter by task ID
`-a, --agent <id>`	Filter by agent ID
`-l, --limit <n>`	Maximum entries to show (default: 20)

Metrics command

Show provider metrics and usage statistics — token counts, estimated costs, session counts, and error rates.

sf metrics [--range <days>] [--provider <name>] [--group-by <mode>]

Option	Description
`-r, --range <days>`	Time range (e.g., `7d`, `14d`, `30d`). Default: `7d`
`-p, --provider <name>`	Filter by provider name (e.g., `claude-code`)
`-g, --group-by <mode>`	Group by: `provider` (default) or `model`