CLI Reference

Complete reference for all SidStack CLI commands and options.

Installation

# Quick start with npx (no install needed)
npx @sidstack/cli init

# npm global install and Homebrew coming after first release

All commands support --help for detailed usage information.

Project Setup

sidstack init

Initialize a new SidStack project in the current directory. Creates .sidstack/ folder with governance, skills, principles, and workflows. Also sets up .claude/commands/ slash commands and .mcp.json configuration.

Options:

--governanceInclude governance structure (principles, skills, workflows)
--openspecInclude OpenSpec workflow for spec-driven development
--no-frameworksMinimal setup without governance or OpenSpec
--preset <name>Use a preset (minimal, fullstack-typescript, etc.)
--forceOverwrite existing .sidstack folder

$ sidstack init --governance

sidstack update

Update SidStack configuration and governance files to the latest version. Checks for new principles, skills, and workflows.

Options:

--governance-onlyOnly update governance files
--forceForce overwrite existing files

$ sidstack update --governance-only

sidstack doctor

Check project health and configuration. Validates .sidstack/ structure, MCP configuration, governance files, and service connectivity.

Options:

--jsonOutput as JSON for programmatic consumption

$ sidstack doctor --json

Knowledge Management

sidstack knowledge init

Initialize the knowledge folder structure under .sidstack/knowledge/. Creates directories for business-logic, api-endpoints, design-patterns, and database-tables.

$ sidstack knowledge init

sidstack knowledge create

Create a new knowledge document from a template. Generates a markdown file with frontmatter including type, module, status, and tags.

Options:

--type <type>Document type (business-logic, api-endpoint, design-pattern, database-table, module, index)
--title <title>Document title
--module <id>Link to a module

$ sidstack knowledge create --type api-endpoint --title "GET /users" --module api

sidstack knowledge list

List all knowledge documents in the project. Shows document type, title, module, and status.

Options:

--jsonOutput as JSON

$ sidstack knowledge list --json

sidstack knowledge templates

List available knowledge document templates. Shows each template type with its required fields and structure.

$ sidstack knowledge templates

sidstack knowledge validate

Validate knowledge documents for completeness. Checks frontmatter fields, required sections, and cross-references between documents.

$ sidstack knowledge validate

Governance

sidstack governance show

Show governance overview including active principles, skills, workflows, and agent roles. Provides a summary of the entire governance structure.

Options:

--section <name>Show specific section (principles, skills, workflows)
--jsonOutput as JSON

$ sidstack governance show --section principles

sidstack governance check

Check governance compliance for the current project. Validates that required principles are present, skills are properly structured, and quality gates are defined.

Options:

--strictFail on warnings (not just errors)
--jsonOutput as JSON

$ sidstack governance check --strict

Task Management

sidstack task create

Create a new task with governance auto-linked based on task type. Requires a detailed description with problem statement and solution approach.

Options:

--title <title>Task title in format: [TYPE] description (e.g., [feature] Add login)
--type <type>Task type: feature, bugfix, refactor, test, docs, infra, security, perf, debt, spike
--priority <level>Priority: low, medium, high
--jsonOutput as JSON

$ sidstack task create --title "[bugfix] Fix auth timeout" --type bugfix

sidstack task list

List all tasks in the project with smart filtering. Defaults to showing actionable tasks (pending + in_progress).

Options:

--status <status>Filter by status: pending, in_progress, completed, blocked, failed, cancelled
--preset <name>Smart filter: actionable, blocked, recent, epics, all
--jsonOutput as JSON

$ sidstack task list --preset blocked --json

sidstack task update

Update task status, progress, or add notes. Use to track work progress and transition task states.

Options:

--status <status>New status
--progress <0-100>Progress percentage
--notes <text>Status update notes

$ sidstack task update task-123 --status completed --progress 100

Impact Analysis

sidstack impact analyze

Run impact analysis on a planned change. Analyzes scope (affected modules, files), risks (severity, blocking status), data flows, and generates a validation checklist with gate status.

Options:

--task <id>Task ID to analyze
--description <text>Change description to analyze
--change-type <type>Type: feature, refactor, bugfix, migration, deletion

$ sidstack impact analyze --description "Add OAuth2 authentication" --change-type feature

sidstack impact check

Check gate status for an impact analysis. Returns blocked, warning, or clear status with details about any blockers that need resolution.

Options:

--analysis <id>Analysis ID to check
--task <id>Task ID to find analysis for

$ sidstack impact check --task task-123

Skills & Presets

sidstack skill list

List available governance skills. Shows capability-based skills organized by category (implement, design, test, review, deploy).

$ sidstack skill list

sidstack skill show <name>

Show details of a specific skill including its content, applicability, and trigger conditions.

$ sidstack skill show implement/feature

sidstack skill create

Create a new custom skill from a template. Skills can be procedures, checklists, templates, or rules.

Options:

--name <name>Skill name (kebab-case)
--type <type>Type: procedure, checklist, template, rule

$ sidstack skill create --name "api-review" --type checklist

sidstack preset list

List available project presets. Presets provide pre-configured governance structures for common project types.

$ sidstack preset list

sidstack preset show <name>

Show details of a specific preset including its principles, skills, and workflows.

$ sidstack preset show fullstack-typescript

Slash Commands

sidstack command list

List all installed Claude Code slash commands. Shows commands available in .claude/commands/sidstack/.

$ sidstack command list

sidstack command add <name>

Add a new slash command to the project. Creates a markdown file in .claude/commands/sidstack/.

$ sidstack command add "deploy"

sidstack command show <name>

Show the content of a specific slash command.

$ sidstack command show agent

MCP Server

sidstack mcp start

Start the MCP server for Claude Code integration. Exposes project knowledge, task management, impact analysis, and training tools to AI agents via the Model Context Protocol.

$ sidstack mcp start

Common Workflows

1. Initialize a New Project

$ cd /path/to/your/project

$ sidstack init --governance

$ sidstack knowledge init

$ sidstack doctor

2. Create and Track a Feature

$ sidstack task create --title "[feature] Add user auth" --type feature

$ sidstack task update task-xxx --status in_progress

$ sidstack impact analyze --task task-xxx

$ sidstack impact check --task task-xxx

$ sidstack task update task-xxx --status completed --progress 100

3. Build Project Knowledge

$ sidstack knowledge templates

$ sidstack knowledge create --type business-logic --title "Auth Flow" --module auth

$ sidstack knowledge create --type api-endpoint --title "POST /login" --module auth

$ sidstack knowledge list

$ sidstack knowledge validate

4. Check Governance Compliance

$ sidstack governance show

$ sidstack governance check --strict

$ sidstack skill list

Project Structure After Init

your-project/
├── .sidstack/
│   ├── config.json            # Project configuration
│   ├── governance.md          # Governance overview
│   ├── principles/            # Quality standards
│   │   ├── code-standards.md
│   │   ├── testing-qa.md
│   │   ├── security.md
│   │   └── ...
│   ├── skills/capabilities/   # Role-specific skills
│   │   ├── implement/         # feature, bugfix, refactor
│   │   ├── design/            # architecture, database, api
│   │   ├── test/              # unit, integration, e2e
│   │   ├── review/            # code, security, performance
│   │   └── deploy/            # ci-cd, release
│   ├── workflows/             # End-to-end processes
│   └── knowledge/             # Project knowledge docs
├── .claude/
│   ├── settings.local.json    # MCP auto-approval
│   └── commands/sidstack/     # Slash commands
│       ├── agent.md
│       ├── analyze.md
│       ├── governance.md
│       └── ...
└── .mcp.json                  # Claude Code MCP config

Claude Code Slash Commands

After running sidstack init, these slash commands are available in Claude Code:

/sidstack:agent [role] [task]Spawn a governed agent (worker, reviewer)

/sidstack:governanceView governance overview and compliance

/sidstack:analyzeRun implementation analysis on a change

/sidstack:knowledge-builderBuild knowledge documents from codebase

/sidstack:assistantRead-only Q&A about project knowledge

/sidstack:learnLearn about governance concepts

/sidstack:focusFocus mode for current task context

/sidstack:taskTask management operations

Exit Codes

0Success

1Error (fatal)

2Warning (non-fatal)

3Validation failed

4Not initialized