# GSD CLI Tools Reference > Surface-area reference for `get-shit-done/bin/gsd-tools.cjs` (legacy Node CLI). Workflows and agents should prefer `gsd-sdk query` or `@gsd-build/sdk` where a handler exists — see [SDK and programmatic access](#sdk-and-programmatic-access). For slash commands and user flows, see [Command Reference](COMMANDS.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** | `get-shit-done/bin/gsd-tools.cjs` | | **Implementation** | 20 domain modules under `get-shit-done/bin/lib/` (the directory is authoritative) | | **Status** | Maintained for parity tests and CJS-only entrypoints; `gsd-sdk query` / SDK registry are the supported path for new orchestration (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). | **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 (also honored when the SDK spawns this binary; see below) | --- ## SDK and programmatic access Use this when authoring workflows, not when you only need the command list below. **1. CLI — `gsd-sdk query `** - Resolves argv with the same **longest-prefix** rules as the typed registry (`resolveQueryArgv` in `sdk/src/query/registry.ts`). Unregistered commands **fail fast** — use `node …/gsd-tools.cjs` only for handlers not in the registry. - Full matrix (CJS command → registry key, CLI-only tools, aliases, golden tiers): [sdk/src/query/QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md). **2. TypeScript — `@gsd-build/sdk` (`GSDTools`, `createRegistry`)** - `GSDTools` (used by `PhaseRunner`, `InitRunner`, and `GSD.createTools()`) always shells out to `gsd-tools.cjs` via `execFile` — there is no in-process registry path on this class. For typed, in-process dispatch use `createRegistry()` from `sdk/src/query/index.ts`, or invoke `gsd-sdk query` (see [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md)). - Conventions: mutation event wiring, `GSDError` vs `{ data: { error } }`, locks, and stubs — [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md). **CJS → SDK examples (same project directory):** | Legacy CJS | Preferred `gsd-sdk query` (examples) | | ---------------------------------------- | ------------------------------------ | | `node gsd-tools.cjs init phase-op 12` | `gsd-sdk query init phase-op 12` | | `node gsd-tools.cjs phase-plan-index 12` | `gsd-sdk query phase-plan-index 12` | | `node gsd-tools.cjs state json` | `gsd-sdk query state json` | | `node gsd-tools.cjs roadmap analyze` | `gsd-sdk query roadmap analyze` | **SDK state reads:** `gsd-sdk query state json` / `state.json` and `gsd-sdk query state load` / `state.load` currently share one native handler (rebuilt STATE.md frontmatter — CJS `cmdStateJson`). The legacy CJS `state load` payload (`config`, `state_raw`, existence flags) is still **CLI-only** via `node …/gsd-tools.cjs state load` until a separate registry handler exists. Full routing and golden rules: [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md). **CLI-only (not in registry):** e.g. **graphify**, **from-gsd2** / **gsd2-import** — call `gsd-tools.cjs` until registered. **Mutation events (SDK):** `QUERY_MUTATION_COMMANDS` in `sdk/src/query/index.ts` lists commands that may emit structured events after a successful dispatch. Exceptions called out in QUERY-HANDLERS: `state validate` (read-only), `skill-manifest` (writes only with `--write`), `intel update` (stub). **Golden parity:** Policy and CJS↔SDK test categories are documented under **Golden parity** in [QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md). --- ## 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 # 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 ``` --- ## Model Resolution ```bash # Get model for agent based on current profile node gsd-tools.cjs resolve-model # Returns: opus | sonnet | haiku | inherit ``` 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] ``` --- ## 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 (SDK --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] ``` --- ## 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 node gsd-tools.cjs progress [json|table|bar] # 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-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] ``` > `--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. # Web search (requires Brave API key) node gsd-tools.cjs websearch [--limit N] [--freshness day|week|month] ``` --- ## 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)). Graphify is **CJS-only**: `gsd-sdk query` does not yet register graphify handlers — always use `node gsd-tools.cjs graphify …`. ```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 | | State | `lib/state.cjs` | All `state` subcommands, `state-snapshot` | | Phase | `lib/phase.cjs` | Phase CRUD, `find-phase`, `phase-plan-index`, `phases list` | | 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-from-gsd2`) | | Intel | `lib/intel.cjs` | Queryable codebase intelligence index (backs `/gsd-intel`) | --- ## Reviewer CLI Routing `review.models.` maps a reviewer flavor to a shell command invoked by the code-review workflow. Set via [`/gsd-settings-integrations`](COMMANDS.md#gsd-settings-integrations) or directly: ```bash gsd-sdk query config-set review.models.codex "codex exec --model gpt-5" gsd-sdk query config-set review.models.gemini "gemini -m gemini-2.5-pro" gsd-sdk query config-set review.models.opencode "opencode run --model claude-sonnet-4" gsd-sdk query 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-integrations` (`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 `get-shit-done/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). --- ## See also - [sdk/src/query/QUERY-HANDLERS.md](../sdk/src/query/QUERY-HANDLERS.md) — registry matrix, routing, golden parity, intentional CJS differences - [Architecture](ARCHITECTURE.md) — where `gsd-sdk query` fits in orchestration - [Command Reference](COMMANDS.md) — user-facing `/gsd:` commands