# GSD CLI Tools Reference > Reference for the `gsd-tools` CLI (`gsd-core/bin/gsd-tools.cjs`). For slash commands and user flows, see [Command Reference](COMMANDS.md). Return to [docs index](README.md). --- ## Overview `gsd-tools.cjs` centralizes config parsing, model resolution, phase lookup, git commits, summary verification, state management, and template operations across GSD commands, workflows, and agents. | | | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Shipped path** | `gsd-core/bin/gsd-tools.cjs` | | **Implementation** | 20 domain modules under `gsd-core/bin/lib/` (the directory is authoritative) | | **Status** | Primary runtime command surface for orchestration, workflows, and automation. | **Usage (CJS):** ```bash node gsd-tools.cjs [args] [--raw] [--cwd ] ``` **Global flags (CJS):** | Flag | Description | | -------------- | ---------------------------------------------------------------------------- | | `--raw` | Machine-readable output (JSON or plain text, no formatting) | | `--cwd ` | Override working directory (for sandboxed subagents) | | `--ws ` | Workstream context for `.planning/workstreams/` paths | --- ## State Commands Manage `.planning/STATE.md` — the project's living memory. ```bash # Load full project config + state as JSON node gsd-tools.cjs state load # Output STATE.md frontmatter as JSON node gsd-tools.cjs state json # Update a single field node gsd-tools.cjs state update # Get STATE.md content or a specific section node gsd-tools.cjs state get [section] # Batch update multiple fields node gsd-tools.cjs state patch --field1 val1 --field2 val2 # Increment plan counter node gsd-tools.cjs state advance-plan # Record execution metrics node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N] # Recalculate progress bar node gsd-tools.cjs state update-progress # Add a decision node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."] # Or from files: node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path] # Add/resolve blockers node gsd-tools.cjs state add-blocker --text "..." node gsd-tools.cjs state resolve-blocker --text "..." # Record session continuity node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path] # Phase start — update STATE.md Status/Last activity for a new phase node gsd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT # Agent-discoverable blocker signalling (used by discuss-phase / UI flows) node gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P node gsd-tools.cjs state signal-resume ``` ### State Snapshot Structured parse of the full STATE.md: ```bash node gsd-tools.cjs state-snapshot ``` Returns JSON with: current position, phase, plan, status, decisions, blockers, metrics, last activity. --- ## Phase Commands Manage phases — directories, numbering, and roadmap sync. ```bash # Find phase directory by number node gsd-tools.cjs find-phase # Calculate next decimal phase number for insertions node gsd-tools.cjs phase next-decimal # Append new phase to roadmap + create directory node gsd-tools.cjs phase add # Insert decimal phase after existing node gsd-tools.cjs phase insert # Remove phase, renumber subsequent node gsd-tools.cjs phase remove [--force] # Mark phase complete, update state + roadmap node gsd-tools.cjs phase complete # Evaluate HUMAN-UAT results for a phase (markdown-aware; ignores false-positive contexts) # Returns JSON: { passed, uat_files[], verification_files[], checks[], blockers[], policy } node gsd-tools.cjs phase uat-passed [--require-verification] # Index plans with waves and status node gsd-tools.cjs phase-plan-index # List phases with filtering node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived] ``` --- ## Roadmap Commands Parse and update `ROADMAP.md`. ```bash # Extract phase section from ROADMAP.md node gsd-tools.cjs roadmap get-phase # Full roadmap parse with disk status node gsd-tools.cjs roadmap analyze # Update progress table row from disk node gsd-tools.cjs roadmap update-plan-progress ``` --- ## Config Commands Read and write `.planning/config.json`. ```bash # Initialize config.json with defaults node gsd-tools.cjs config-ensure-section # Set a config value (dot notation) node gsd-tools.cjs config-set # Get a config value node gsd-tools.cjs config-get # Set model profile node gsd-tools.cjs config-set-model-profile ``` --- ## Capability Commands The capability command family resolves and mutates capability state (ADR-857). One resolved state composes three substrates: the install profile (`.gsd-profile`), the runtime surface (`.gsd-surface.json`), and config gates (`.planning/config.json` `workflow.*`). `enabled = installed && surfaced`; a hook is `active` only when its capability is enabled and its config gate is on. ### `capability state` ```bash node gsd-tools.cjs capability state [--config-dir ] [--raw] ``` Resolves and prints every capability's `installed`, `surfaced`, `enabled`, and per-hook `active` state. Read-only. `--config-dir` selects the runtime config directory (defaults to the resolved Claude home). `--raw` emits JSON. ### `capability set` ```bash node gsd-tools.cjs capability set [--on | --off] [--gate =]... [--config-dir ] [--runtime ] [--scope ] [--raw] ``` Mutates one capability, re-resolves, and reports the result. Two axes: - `--on` / `--off` (aliases `--enable` / `--disable`): the capability on/off switch, applied through the runtime surface. `--off` unsurfaces the capability; the change is reversible and reclaims the surface budget. A capability that owns no skills has no surface footprint — use `--gate` for those. - `--gate =` (repeatable): toggles one of the capability's own config keys (a hook gate) within an enabled capability. - `--runtime` / `--scope`: materialise the surface change for that runtime's artifact layout. After writing, the command re-resolves and prints two message classes to stderr: errors (non-zero exit) — unknown capability id, a `--gate` key the capability does not own, a non-boolean gate value, or `--on` for a capability whose skills are not in the install profile; warnings (exit 0) — `--on`/`--off` on a skill-less capability, or a capability left surfaced while every hook is gated off ("present but dead"). Exit status is non-zero only when a requested change could not be applied. **Examples:** ```bash # Turn the UI capability off node gsd-tools.cjs capability set ui --off --config-dir ~/.claude # Keep the capability on, gate one hook off node gsd-tools.cjs capability set code-review --gate workflow.code_review=false ``` --- ## Teams Status ### `query teams-status` ```bash node gsd-tools.cjs query teams-status [--active] ``` Read-only detector for claude-code's experimental agent-teams feature (issue #1355). Resolves the runtime via the canonical `GSD_RUNTIME` → `config.runtime` → `'claude'` precedence, then checks `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`. **Default (no flags):** prints a JSON object and exits 0: ```json { "active": false, "runtime": "claude", "env_present": false, "source": "off: flag absent" } ``` Fields: | Field | Type | Description | |---|---|---| | `active` | boolean | `true` only when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is strictly truthy (`"1"` or `"true"`, case-insensitive) **and** the resolved runtime is `"claude"` | | `runtime` | string | The resolved runtime name (e.g. `"claude"`, `"codex"`) | | `env_present` | boolean | `true` when the env flag is set to a strictly-truthy value | | `source` | string | One of: `"on: env"`, `"off: flag absent"`, `"off: non-claude"` | **`--active` flag:** exits 0 if `active` is true, exits 1 otherwise. Prints nothing. Useful in bash conditionals: ```bash if gsd_run query teams-status --active >/dev/null 2>&1; then echo "agent-teams is on" fi ``` This command is strictly read-only — no config writes, no disk mutation. --- ## Model Resolution ```bash # Get model for agent based on current profile node gsd-tools.cjs resolve-model # Raw output returns the selected model ID/tier. # JSON output also includes profile and, when the active runtime supports it, # reasoning_effort. ``` Agent names: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor` --- ## Verification Commands Validate plans, phases, references, and commits. ```bash # Verify SUMMARY.md file node gsd-tools.cjs verify-summary [--check-count N] # Check PLAN.md structure + tasks node gsd-tools.cjs verify plan-structure # Check all plans have summaries node gsd-tools.cjs verify phase-completeness # Check @-refs + paths resolve node gsd-tools.cjs verify references # Batch verify commit hashes node gsd-tools.cjs verify commits [hash2] ... # Check must_haves.artifacts node gsd-tools.cjs verify artifacts # Check must_haves.key_links node gsd-tools.cjs verify key-links ``` --- ## Validation Commands Check project integrity. ```bash # Check phase numbering, disk/roadmap sync node gsd-tools.cjs validate consistency # Check .planning/ integrity, optionally repair node gsd-tools.cjs validate health [--repair] # Probe context-window utilization for status-line / hook callers (v1.40.0) node gsd-tools.cjs validate context # Context utilization as typed JSON surface (#455) node gsd-tools.cjs validate context --json ``` `validate context` emits a structured envelope with `utilization`, `status` (`ok` / `warn` / `critical` at the 60 % / 70 % thresholds), and a `suggestion` string. The same data backs `/gsd-health --context`. Pass `--json` to receive the typed IR directly (useful in scripts and test assertions). --- ## Template Commands Template selection and filling. ```bash # Select summary template based on granularity node gsd-tools.cjs template select # Fill template with variables node gsd-tools.cjs template fill --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}'] ``` Template types for `fill`: `summary`, `plan`, `verification` --- ## Frontmatter Commands YAML frontmatter CRUD operations on any Markdown file. ```bash # Extract frontmatter as JSON node gsd-tools.cjs frontmatter get [--field key] # Update single field node gsd-tools.cjs frontmatter set --field key --value jsonVal # Merge JSON into frontmatter node gsd-tools.cjs frontmatter merge --data '{json}' # Validate required fields node gsd-tools.cjs frontmatter validate --schema plan|summary|verification ``` --- ## Scaffold Commands Create pre-structured files and directories. ```bash # Create CONTEXT.md template node gsd-tools.cjs scaffold context --phase N # Create UAT.md template node gsd-tools.cjs scaffold uat --phase N # Create VERIFICATION.md template node gsd-tools.cjs scaffold verification --phase N # Create phase directory node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name" ``` --- ## Init Commands (Compound Context Loading) Load all context needed for a specific workflow in one call. Returns JSON with project info, config, state, and workflow-specific data. ```bash node gsd-tools.cjs init execute-phase node gsd-tools.cjs init plan-phase node gsd-tools.cjs init new-project node gsd-tools.cjs init new-milestone node gsd-tools.cjs init quick node gsd-tools.cjs init resume node gsd-tools.cjs init verify-work node gsd-tools.cjs init phase-op node gsd-tools.cjs init todos [area] node gsd-tools.cjs init milestone-op node gsd-tools.cjs init map-codebase node gsd-tools.cjs init progress # Workstream-scoped init (`--ws` flag) node gsd-tools.cjs init execute-phase --ws node gsd-tools.cjs init plan-phase --ws ``` **Large payload handling:** When output exceeds ~50KB, the CLI writes to a temp file and returns `@file:/tmp/gsd-init-XXXXX.json`. Workflows check for the `@file:` prefix and read from disk: ```bash INIT=$(node gsd-tools.cjs init execute-phase "1") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi ``` --- ## Milestone Commands ```bash # Archive milestone node gsd-tools.cjs milestone complete [--name ] [--archive-phases] # Mark requirements as complete node gsd-tools.cjs requirements mark-complete # Accepts: REQ-01,REQ-02 or REQ-01 REQ-02 or [REQ-01, REQ-02] ``` --- ## Agent Skills Emit the skill block for a given agent type. ```bash # Emit raw XML skill block (default — safe for shell expansion) node gsd-tools.cjs agent-skills # Emit typed JSON surface (#455) — { agent_type, block, skills_count, warnings } node gsd-tools.cjs agent-skills --json ``` The `--json` flag returns a typed IR object suitable for structured consumption and test assertions, while the default (no flag) preserves the raw XML output that workflow shell expansions rely on. The IR also includes a `warnings` array naming any configured skill paths that were skipped (for example a missing `SKILL.md`); it is empty when every configured skill resolved. --- ## Skill Manifest Pre-compute and cache skill discovery for faster command loading. ```bash # Generate skill manifest (writes to .claude/skill-manifest.json) node gsd-tools.cjs skill-manifest # Generate with custom output path node gsd-tools.cjs skill-manifest --output ``` Returns JSON mapping of all available GSD skills with their metadata (name, description, file path, argument hints). Used by the installer and session-start hooks to avoid repeated filesystem scans. --- ## Utility Commands ```bash # Convert text to URL-safe slug node gsd-tools.cjs generate-slug "Some Text Here" # → some-text-here # Get timestamp node gsd-tools.cjs current-timestamp [full|date|filename] # Count and list pending todos node gsd-tools.cjs list-todos [area] # Check file/directory existence node gsd-tools.cjs verify-path-exists # Aggregate all SUMMARY.md data node gsd-tools.cjs history-digest # Extract structured data from SUMMARY.md node gsd-tools.cjs summary-extract [--fields field1,field2] # Project statistics node gsd-tools.cjs stats [json|table] # Progress rendering (human-readable) node gsd-tools.cjs progress [json|table|bar] # Progress as typed JSON surface (#455) node gsd-tools.cjs progress --json # Complete a todo node gsd-tools.cjs todo complete # UAT audit — scan all phases for unresolved items node gsd-tools.cjs audit-uat # Cross-artifact audit queue — scan `.planning/` for unresolved audit items node gsd-tools.cjs audit-open [--json] # Reverse-migrate a GSD-2 project into the current structure (backs `/gsd-import --from-gsd2`) node gsd-tools.cjs from-gsd2 [--path ] [--force] [--dry-run] # Git commit with config checks node gsd-tools.cjs commit [--files f1 f2] [--amend] [--no-verify] [--respect-staged] ``` > `--no-verify`: Skips pre-commit hooks. Used by parallel executor agents during wave-based execution to avoid build lock contention (e.g., cargo lock fights in Rust projects). The orchestrator runs hooks once after each wave completes. Do not use `--no-verify` during sequential execution — let hooks run normally. > `--files ` **staging behaviour**: by default, `--files` runs `git add -- ` for each named file before committing. This overwrites any per-hunk staging set up via `git add -p`. Pass `--respect-staged` to skip the `git add` step and commit only what is already in the index within the requested pathspec. If nothing is staged within that scope, the command returns `{ committed: false, reason: 'nothing staged' }` without error. The trailing `-- ` pathspec on the commit is applied under both modes, so files staged outside the `--files` scope are never included (#3061 invariant). # Web search (requires Brave API key) node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month] ``` --- ## Worktree Commands Diagnose and configure the worktree fork base used by Claude Code's `isolation="worktree"` executor dispatch. These commands address the branch-divergence condition described in [Fix the worktree base-mismatch (exit 42) error](how-to/fix-worktree-base-mismatch.md). ```bash # Check whether the current HEAD has diverged from the worktree fork base. # Returns JSON: { shouldDegrade, reason, message, headSha, forkRef, forkSha } node gsd-tools.cjs worktree base-check # Write worktree.baseRef:"head" into .claude/settings.local.json (no-clobber). # Returns JSON: { changed, skipped, previous, baseRef, file } node gsd-tools.cjs worktree set-baseref ``` **`worktree base-check`** reads `worktree.baseRef` from a three-layer cascade — `.claude/settings.local.json`, then `.claude/settings.json`, then the user/global `settings.json` under `CLAUDE_CONFIG_DIR` (or `~/.claude`) — and compares the current `HEAD` SHA against `origin/HEAD`. Project-level settings take precedence over the user/global layer, so a machine-wide `worktree.baseRef:"head"` set via `/config` is honored when no project override exists. The `shouldDegrade` field is `true` when the execute-phase orchestrator will fall back to sequential execution. Possible `reason` values: | `reason` | `shouldDegrade` | Meaning | |---|---|---| | `baseref-head` | `false` | `worktree.baseRef:"head"` is set; no mismatch possible | | `head-matches-fork` | `false` | HEAD and `origin/HEAD` are the same commit | | `head-diverged-from-fork` | `true` | Branch is ahead of or diverged from `origin/HEAD` | | `fork-ref-unknown` | `true` | `origin/HEAD` could not be resolved | | `no-head` | `false` | Not in a git repo (no `HEAD`) | **`worktree set-baseref`** applies a no-clobber write of `worktree.baseRef:"head"` to `.claude/settings.local.json`. If the file already contains an explicit `baseRef` value other than `"head"`, the existing value is preserved and `skipped:"explicit-other"` is returned. Malformed JSON causes an error rather than a silent overwrite. Both fresh installs and upgrades of GSD Core run this automatically when `workflow.use_worktrees` is enabled (the default); the command is also available for manual use — for example, to apply the setting when worktrees were toggled on after installation, or to re-apply it after a settings change. --- ## Graphify Build, query, and inspect the project knowledge graph in `.planning/graphs/`. Requires `graphify.enabled: true` in `config.json` (see [Configuration Reference](CONFIGURATION.md#graphify-settings)). ```bash # Build or rebuild the knowledge graph node gsd-tools.cjs graphify build # Search the graph for a term node gsd-tools.cjs graphify query # Show graph freshness and statistics node gsd-tools.cjs graphify status # Show changes since the last build node gsd-tools.cjs graphify diff # Write a named snapshot of the current graph node gsd-tools.cjs graphify snapshot [name] ``` User-facing entry point: `/gsd-graphify` (see [Command Reference](COMMANDS.md#gsd-graphify)). --- ## Module Architecture | Module | File | Exports | |--------|------|---------| | Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, shared utilities, compatibility re-exports | | State | `lib/state.cjs` | All `state` subcommands, `state-snapshot` | | Phase | `lib/phase.cjs` | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` | | Planning Workspace | `lib/planning-workspace.cjs` | Planning seam: `planningDir`, `planningPaths`, active workstream routing, `.planning/.lock` | | Roadmap | `lib/roadmap.cjs` | Roadmap parsing, phase extraction, progress updates | | Config | `lib/config.cjs` | Config read/write, section initialization | | Verify | `lib/verify.cjs` | All verification and validation commands | | Template | `lib/template.cjs` | Template selection and variable filling | | Frontmatter | `lib/frontmatter.cjs` | YAML frontmatter CRUD | | Init | `lib/init.cjs` | Compound context loading for all workflows | | Milestone | `lib/milestone.cjs` | Milestone archival, requirements marking | | Commands | `lib/commands.cjs` | Misc: slug, timestamp, todos, scaffold, stats, websearch | | Model Profiles | `lib/model-profiles.cjs` | Profile resolution table | | UAT | `lib/uat.cjs` | Cross-phase UAT/verification audit | | Profile Output | `lib/profile-output.cjs` | Developer profile formatting | | Profile Pipeline | `lib/profile-pipeline.cjs` | Session analysis pipeline | | Graphify | `lib/graphify.cjs` | Knowledge graph build/query/status/diff/snapshot (backs `/gsd-graphify`) | | Learnings | `lib/learnings.cjs` | Extract learnings from phases/SUMMARY artifacts (backs `/gsd-extract-learnings`) | | Audit | `lib/audit.cjs` | Phase/milestone audit queue handlers; `audit-open` helper | | GSD2 Import | `lib/gsd2-import.cjs` | Reverse-migration importer from GSD-2 projects (backs `/gsd-import --from-gsd2`) | | Intel | `lib/intel.cjs` | Queryable codebase intelligence index (backs `/gsd-map-codebase --query`) | | Capability State | `lib/capability-state.cjs` | Capability-state resolver — composes install profile, surface, and config into per-capability `enabled`/`active` view | | Capability Writer | `lib/capability-writer.cjs` | Capability-state writer (ADR-1213) — write-side inverse; projects `--on`/`--off`/`--gate` onto surface + config substrates then re-resolves | | Worktree Base Ref | `lib/worktree-base-ref.cjs` | Worktree fork-base detection and `worktree base-check` / `set-baseref` commands (#683) | --- ## Reviewer CLI Routing `review.models.` maps a reviewer flavor to a bare model id injected into the CLI's `--model` (or `-m`) flag by the code-review workflow. Set via [`/gsd-config --integrations`](COMMANDS.md#gsd-config) or directly: ```bash node gsd-tools.cjs config-set review.models.codex "gpt-5" node gsd-tools.cjs config-set review.models.gemini "gemini-2.5-pro" node gsd-tools.cjs config-set review.models.opencode "claude-sonnet-4" node gsd-tools.cjs config-set review.models.claude "" # clear — fall back to session model ``` Slugs are validated against `[a-zA-Z0-9_-]+`; empty or path-containing slugs are rejected. See [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing) for the full field reference. ## Secret Handling API keys configured via `/gsd-settings` (`brave_search`, `firecrawl`, `exa_search`) are written plaintext to `.planning/config.json` but are masked (`****`) in every `config-set` / `config-get` output, confirmation table, and interactive prompt. See `gsd-core/bin/lib/secrets.cjs` for the masking implementation. The `config.json` file itself is the security boundary — protect it with filesystem permissions and keep it out of git (`.planning/` is gitignored by default). --- ## Related - [Commands](COMMANDS.md) - [Configuration](CONFIGURATION.md) - [Architecture](ARCHITECTURE.md) - [Fix the worktree base-mismatch (exit 42) error](how-to/fix-worktree-base-mismatch.md) - [docs index](README.md)