Skip to content
ContractSpec
Start here
AI index

ContractSpec CLI

Command-line interface for creating, building, and validating contract specifications with AI-powered code generation.

Installation

bun add contractspec -D

The default CLI is a slim host. Install specialist command packs as direct dependencies so the host can discover them from package metadata.

bash
bun add @lssm-tech/integration.cli-contractspec-ai
bun add @lssm-tech/integration.cli-contractspec-builder
bun add @lssm-tech/integration.cli-contractspec-design
bun add @lssm-tech/integration.cli-contractspec-examples

Quick Start

bash
# Initialize project with the slim core
bunx contractspec init

# Create a spec
contractspec create --type operation

# Generate code
contractspec generate

# Validate
contractspec validate

# Mirror the complete catalog and inspect lifecycle health
contractspec can-help catalog sync --json
contractspec update --check
contractspec doctor --format json

Commands

onboard

Optional examples-pack flow that recommends tracks, examples, and repo-local guides

bash
contractspec onboard [track...] [--example <key>] [--dry-run] [--json]

create

Interactive wizard to create contract specifications

bash
contractspec create [--type operation] [--ai]

build

Generate implementation code from contract specs using AI agents

bash
contractspec build <spec-file> [--agent-mode claude-code]

validate

Validate contract specifications and implementations

bash
contractspec validate <spec-file> [--check-implementation]

list

List all contract specifications in the project

bash
contractspec list [--type operation] [--json]

watch

Watch specs and auto-regenerate on changes

bash
contractspec watch [--build] [--validate]

sync

Sync contracts by building all discovered specs

bash
contractspec sync [--dry-run]

ci

Run all validation checks for CI/CD pipelines

bash
contractspec ci [--format sarif] [--output results.sarif]

can-help

Discover reusable packages and Python-to-TypeScript equivalents from the complete capability catalog

bash
contractspec can-help "replace FastAPI" [--scope installed] [--runtime node] [--json]

update

Plan latest-stable workspace updates by default, or apply a rollback-safe transaction

bash
contractspec update [--check] [--apply] [--scope package] [--contractspec-only]

doctor

Inspect catalog, dependency, managed guidance, MCP, and workspace health with stable check IDs

bash
contractspec doctor [--format json] [--fix]

mcp

Serve offline docs, contract tools and spec scaffolding to any MCP-capable editor or agent over stdio

bash
contractspec mcp [--runtime] [--cwd <path>]

deps

Analyze contract dependencies and relationships

bash
contractspec deps [--circular] [--format dot]

diff

Compare contract specifications and show differences

bash
contractspec diff <spec1> <spec2> [--breaking]

AI Agent Modes

After installing the AI command pack, the CLI supports multiple AI agent modes for different use cases:

simple

Direct LLM API calls, fast and straightforward. Best for rapid prototyping.

claude-code

Extended thinking with Claude. Best for production-quality code.

openai-codex

GPT-4o/o1 models. Excellent for algorithms and optimization.

cursor

Leverages Cursor agentic capabilities. Requires Cursor environment.

CI/CD Integration

Run all validation checks in CI/CD with machine-readable output:

yaml
- name: Validate Contracts
  run: contractspec ci --format sarif --output results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Configuration

Create a .contractsrc.json file in your project root:

json
{
  "aiProvider": "claude",
  "agentMode": "claude-code",
  "outputDir": "./src",
  "conventions": {
    "operations": "interactions/commands|queries",
    "events": "events"
  }
}