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](./parallel-orchestration.md) 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](./configuration.md#global-api-keys-sf-config). |
| `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.

```bash
# 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.

```bash
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:**

```json
{
  "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.

```bash
/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.

```bash
# 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.