singularity-forge/docs/user-docs/commands.md

Commands Reference

Session Commands

Command	Description
/next	Assisted mode — execute one unit at a time, pause between each
/next	Explicit assisted mode (same as /next)
/autonomous	Autonomous product loop — research, plan, execute, commit, repeat
/quick	Execute a quick task with SF guarantees (atomic commits, state tracking) without full planning overhead
/stop	Stop autonomous mode gracefully
/pause	Pause autonomous mode (preserves state, /autonomous to resume)
/steer	Hard-steer plan documents during execution
/discuss	Discuss architecture and decisions (works alongside autonomous mode)
/status	Progress dashboard
/widget	Cycle dashboard widget: full / small / min / off
/queue	Queue and reorder future milestones (safe during autonomous mode)
/capture	Fire-and-forget thought capture (works during autonomous mode)
/triage	Manually trigger triage of pending captures
/dispatch	Dispatch a specific phase directly (research, plan, execute, complete, reassess, uat, replan)
/history	View execution history (supports --cost, --phase, --model filters)
/forensics	Full-access SF debugger — structured anomaly detection, unit traces, and LLM-guided root-cause analysis for autonomous mode failures
/cleanup	Clean up SF state files and stale worktrees
/visualize	Open workflow visualizer (progress, deps, metrics, timeline)
/export --html	Generate self-contained HTML report for current or completed milestone
/export --html --all	Generate retrospective reports for all milestones at once
/update	Update SF to the latest version in-session
/knowledge	Add persistent project knowledge (rule, pattern, or lesson)
/fast	Toggle service tier for supported models (prioritized API routing)
/rate	Rate last unit's model tier (over/ok/under) — improves adaptive routing
/changelog	Show categorized release notes
/logs	Browse activity logs, debug logs, and metrics
/remote	Configure remote question delivery
/help	Categorized command reference with descriptions for all SF subcommands

Configuration & Diagnostics

Command	Description
/prefs	Model selection, timeouts, budget ceiling
/mode	Switch workflow mode (solo/team) with coordinated defaults for milestone IDs, git commit behavior, and documentation
/config	Re-run the provider setup wizard (LLM provider + tool keys)
/keys	API key manager — list, add, remove, test, rotate, doctor
/doctor	Runtime health checks with auto-fix — issues surface in real time across widget, visualizer, and HTML reports (v2.40)
/inspect	Show SQLite DB diagnostics
/init	Project init wizard — detect, configure, bootstrap .sf/
/setup	Global setup status and configuration
/skill-health	Skill lifecycle dashboard — usage stats, success rates, token trends, staleness warnings
/skill-health <name>	Detailed view for a single skill
/skill-health --declining	Show only skills flagged for declining performance
/skill-health --stale N	Show skills unused for N+ days
/hooks	Show configured post-unit and pre-dispatch hooks
/run-hook	Manually trigger a specific hook
/migrate	Migrate a v1 .planning directory to .sf format

Milestone Management

Command	Description
/new-milestone	Create a new milestone
/skip	Prevent a unit from autonomous mode dispatch
/undo	Revert last completed unit
/undo-task	Reset a specific task's completion state (DB + markdown)
/reset-slice	Reset a slice and all its tasks (DB + markdown)
/park	Park a milestone — skip without deleting
/unpark	Reactivate a parked milestone
Discard milestone	Available via /next wizard → "Milestone actions" → "Discard"

Parallel Orchestration

Command	Description
/parallel start	Analyze eligibility, confirm, and start workers
/parallel status	Show all workers with state, progress, and cost
/parallel stop [MID]	Stop all workers or a specific milestone's worker
/parallel pause [MID]	Pause all workers or a specific one
/parallel resume [MID]	Resume paused workers
/parallel merge [MID]	Merge completed milestones back to main

See Parallel Orchestration for full documentation.

Workflow Templates (v2.42)

Command	Description
/start	Start a workflow template (bugfix, spike, feature, hotfix, refactor, security-audit, dep-upgrade, full-project)
/start resume	Resume an in-progress workflow
/templates	List available workflow templates
/templates info <name>	Show detailed template info

Custom Workflows (v2.42)

Command	Description
/workflow new	Create a new workflow definition (via skill)
/workflow run <name>	Create a run and start autonomous mode
/workflow list	List workflow runs
/workflow validate <name>	Validate a workflow definition YAML
/workflow pause	Pause custom workflow autonomous mode
/workflow resume	Resume paused custom workflow autonomous mode

/autonomous is the product-development loop that chooses the next useful unit from project state. /start is guided workflow kickoff and may ask clarifying questions. /workflow run executes an explicit YAML workflow definition. There is no separate /auto mode.

Extensions

Command	Description
/extensions list	List all extensions and their status
/extensions enable <id>	Enable a disabled extension
/extensions disable <id>	Disable an extension
/extensions info <id>	Show extension details

cmux Integration

Command	Description
/cmux status	Show cmux detection, prefs, and capabilities
/cmux on	Enable cmux integration
/cmux off	Disable cmux integration
/cmux notifications on/off	Toggle cmux desktop notifications
/cmux sidebar on/off	Toggle cmux sidebar metadata
/cmux splits on/off	Toggle cmux visual subagent splits

GitHub Sync (v2.39)

Command	Description
/github-sync bootstrap	Initial setup — creates GitHub Milestones, Issues, and draft PRs from current .sf/ state
/github-sync status	Show sync mapping counts (milestones, slices, tasks)

Enable with github.enabled: true in preferences. Requires gh CLI installed and authenticated. Sync mapping is persisted in .sf/.github-sync.json.

Git Commands

Command	Description
/worktree (/wt)	Git worktree lifecycle — create, switch, merge, remove

Session Management

Command	Description
/clear	Start a new session (alias for /new)
/exit	Graceful shutdown — saves session state before exiting
/kill	Kill SF process immediately
/model	Switch the active model
/login	Log in to an LLM provider
/thinking	Toggle thinking level during sessions
/voice	Toggle real-time speech-to-text on Linux

Keyboard Shortcuts

Shortcut	Action
Ctrl+Alt+G	Toggle dashboard overlay
Ctrl+Alt+V	Toggle voice transcription
Ctrl+Alt+B	Show background shell processes
Ctrl+V / Alt+V	Paste image from clipboard (screenshot → vision input)
Escape	Pause autonomous mode (preserves conversation)

Tip: If Ctrl+V is intercepted by your terminal (e.g. Warp), use Alt+V instead for clipboard image paste.

CLI Flags

Flag	Description
sf	Start a new interactive session
sf --continue (-c)	Resume the most recent session for the current directory
sf --model <id>	Override the default model for this session
sf --print "msg" (-p)	Single-shot prompt mode (no TUI)
sf --mode <text|json|rpc>	Session I/O mode: text/json print format or RPC protocol
sf --list-models [search]	List available models and exit
sf --web [path]	Start browser-based web interface (optional project path)
sf --worktree (-w) [name]	Start session in a git worktree (auto-generates name if omitted)
sf --no-session	Disable session persistence
sf --extension <path>	Load an additional extension (can be repeated)
sf --append-system-prompt <text>	Append text to the system prompt
sf --tools <list>	Comma-separated list of tools to enable
sf --version (-v)	Print version and exit
sf --help (-h)	Print help and exit
sf sessions	Interactive session picker — list all saved sessions for the current directory and choose one to resume
sf --debug	Enable structured JSONL diagnostic logging for troubleshooting dispatch and state issues
sf config	Set up global API keys for search and docs tools (saved to ~/.sf/agent/auth.json, applies to all projects). See Global API Keys.
sf update	Update SF to the latest version
sf headless new-milestone	Create a new milestone from a context file through the machine surface

Machine Surface (sf headless)

sf headless is SF's current machine surface. It runs the same SF flow as the TUI, but without rendering the TUI, so CI jobs, cron jobs, parent processes, and scripts can drive it. Headless is not JSON, run control, or a permission profile; it is a non-interactive surface. RPC/ACP/stdio/HTTP are protocols around the flow. text, json, and stream-json are output formats. Manual, assisted, and autonomous are run-control modes. Restricted, normal, trusted, and unrestricted are permission profiles.

# Show headless command help
sf headless

# Run autonomous mode through the machine surface
sf headless autonomous

# Run a single unit
sf headless next

# Instant JSON snapshot — no LLM, ~50ms
sf headless query

# With timeout for CI
sf headless --timeout 600000 autonomous

# Force a specific phase
sf headless dispatch plan

# Create a new milestone from a context file and start autonomous mode
sf headless new-milestone --context brief.md --autonomous

# Create a milestone from inline text
sf headless new-milestone --context-text "Build a REST API with auth"

# Pipe context from stdin
echo "Build a CLI tool" | sf headless new-milestone --context -

Flag	Description
--timeout N	Overall timeout in milliseconds (default: 300000 / 5 min)
--max-restarts N	Auto-restart on crash with exponential backoff (default: 3). Set 0 to disable
--json	Alias for streaming events as JSONL to stdout
--output-format text|json|stream-json	Select human text, one batch JSON result, or streaming JSONL events
--model ID	Override the model for the headless session
--context <file>	Context file for new-milestone (use - for stdin)
--context-text <text>	Inline context text for new-milestone
--autonomous	Chain into autonomous mode after milestone creation

Exit codes: 0 = complete, 1 = error or timeout, 2 = blocked.

Any /next subcommand works as a positional argument — sf headless status, sf headless doctor, sf headless dispatch execute, etc.

sf headless query

Returns a single JSON object with the full project snapshot — no LLM session, no RPC child, instant response (~50ms). This is the recommended machine-readable projection for orchestrators and scripts to inspect SF state.

sf headless query | jq '.state.phase'
# "executing"

sf headless query | jq '.next'
# {"action":"dispatch","unitType":"execute-task","unitId":"M001/S01/T03"}

sf headless query | jq '.cost.total'
# 4.25

Output schema:

{
  "state": {
    "phase": "executing",
    "activeMilestone": { "id": "M001", "title": "..." },
    "activeSlice": { "id": "S01", "title": "..." },
    "activeTask": { "id": "T01", "title": "..." },
    "registry": [{ "id": "M001", "status": "active" }, ...],
    "progress": { "milestones": { "done": 0, "total": 2 }, "slices": { "done": 1, "total": 3 } },
    "blockers": []
  },
  "next": {
    "action": "dispatch",
    "unitType": "execute-task",
    "unitId": "M001/S01/T01"
  },
  "cost": {
    "workers": [{ "milestoneId": "M001", "cost": 1.50, "state": "running", ... }],
    "total": 1.50
  }
}

MCP Integrations

/mcp shows configured external MCP tool servers. SF does not expose its own workflow as an MCP server; run SF directly with sf or /autonomous.

In-Session Update

/update checks npm for a newer version of SF and installs it without leaving the session.

/update
# Current version: v2.36.0
# Checking npm registry...
# Updated to v2.37.0. Restart SF to use the new version.

If already up to date, it reports so and takes no action.

Export

/export generates reports of milestone work.

# Generate HTML report for the active milestone
/export --html

# Generate retrospective reports for ALL milestones at once
/export --html --all

Reports are saved to .sf/reports/ with a browseable index.html that links to all generated snapshots.