Skip to content

SDD CLI Reference (v3.0)

The sdd command is the main entry point for framework operations.

Profile Detection

The SDD CLI operates in one of two profiles: master (framework development) or client (project instance). The profile is auto-detected using the following priority:

  1. --profile flag (highest priority)
  2. SDD_PROFILE environment variable
  3. .spec.config → [sdd] profile = master|client
  4. Workspace filesystem markers (packages/core/sdd_core/ → master)
  5. Fallback: client
# Use explicit profile override
sdd --profile master governance compile
sdd --profile client wizard run

# Or set via environment
SDD_PROFILE=master sdd governance compile

The current profile is inferred automatically in most cases. Profile affects which operations are permitted:

Command master client
governance compile ✅ ✅
governance load/validate ✅ ✅
wizard run ⚠️ warn ✅
release build ✅ ❌ blocked
doctor run ✅ ✅
docs update/deploy ✅ ✅

Essential Commands

Project Setup

  • sdd setup run: Initializes workspace dependencies and local tooling.

Testing and Validation

  • sdd test run: Runs the full test pipeline and shows project coverage summary by default.
  • sdd test ci-validate: Runs CI-oriented validations.
  • sdd lint run: Runs static quality checks.

Coverage options for sdd test run:

# Default coverage output
sdd test run

# Disable coverage
sdd test run --no-coverage

# Customize report style
sdd test run --cov-report term

# Enforce minimum percentage
sdd test run --cov-fail-under 80

Governance Management

  • sdd governance load: Shows loaded governance summary.
  • sdd governance validate: Validates structure, file access, and fingerprints.
  • sdd governance generate: Generates agent seeds from governance rules.
  • sdd governance compile: Compiles governance artifacts (mandates + guidelines → msgpack binaries).

Wizard

  • sdd wizard run: Runs interactive setup wizard phases. (client primary; warns in master)

Documentation Artifacts

  • sdd docs update: Discovers all markdown in /docs, synthesizes mandate.spec, guidelines.dsl, and discovery-index.json under generated/client/build/docs-meta/.
  • sdd docs deploy: Deploys MkDocs static site (requires mkdocs installed). Aliases: sdd docs, sdd documentation.

Options for sdd docs update:

# Dry run — shows what would be generated without writing files
sdd docs update --dry-run

Options for sdd docs deploy:

# Default — force rebuild and deploy
sdd docs deploy

# Skip force flag
sdd docs deploy --no-force

Release

  • sdd release build: Builds release artifacts into dist/. (master only — blocked in client)

Version

  • sdd version: Shows the installed SDD CLI version.

Diagnostics

  • sdd doctor run: Executes protocol-based diagnostics using integration flow steps.

Doctor Modes

The doctor command supports two execution modes:

  • isolated (default): runs in a temporary isolated workspace.
  • real: runs against the current repository workspace.

Examples:

# Default (isolated)
sdd doctor run

# Real workspace diagnostics
sdd doctor run --mode real

# Custom protocol file
sdd doctor run --spec packages/features/sdd_integration/src/sdd_integration/protocol/integration_flow.yaml

Notes on Diagnostic Semantics

  • Diagnostic status is protocol-step based and returns a score.
  • A run only exits successfully when all protocol steps pass.
  • The protocol now guards against false-green runs where pytest reports only skipped tests.

Command Help

Use help per command for authoritative flags:

sdd --help
sdd doctor --help
sdd governance validate --help

See the project README and CHANGELOG for additional context.