Getting Started with SpecFact CLI

This guide will help you get started with SpecFact CLI in under 60 seconds — first with no install (uvx), then with a persistent install (pip) when you want IDE workflows and a stable specfact command.

Primary use case: brownfield code modernization — reverse-engineering existing codebases into documented specs with runtime contract enforcement. See the 5-Minute Quickstart for a full walkthrough.

Try it now — no install required

Run SpecFact from PyPI without installing into your environment:

cd /path/to/your/git/repo
uvx specfact-cli init --profile solo-developer
uvx specfact-cli code review run --path . --scope full

You should see a Verdict, a Score, and a list of findings. That is the fastest way to validate SpecFact on real code. Read the full quickstart →

Install for persistent use

Use pip when you want a local specfact command, IDE integration, and slash-command workflows.

# System-wide
pip install specfact-cli

# User install
pip install --user specfact-cli

# Virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
pip install specfact-cli

Optional: For enhanced graph-based dependency analysis, see Enhanced Analysis Dependencies.

After installation (required): select workflow bundles on first run:

# Navigate to your project
cd /path/to/your/project

# Required on first run
specfact init --profile solo-developer

# Other valid profile presets
specfact init --profile backlog-team
specfact init --profile api-first-team
specfact init --profile enterprise-full-stack

# Or explicit bundle selection
specfact init --install backlog,codebase
specfact init --install all

Then set up IDE integration:

specfact init ide
specfact init ide --ide cursor
specfact init ide --ide vscode
specfact init ide --install-deps
specfact init ide --ide cursor --install-deps

Important: SpecFact CLI does not ship with built-in AI. specfact init ide installs prompt templates for supported IDEs so your chosen AI copilot can call SpecFact commands in a guided workflow.

More options ↓

More options

Container

# Docker
docker run --rm -v $(pwd):/workspace ghcr.io/nold-ai/specfact-cli:latest --help

# Podman
podman run --rm -v $(pwd):/workspace ghcr.io/nold-ai/specfact-cli:latest --help

GitHub Action

Create .github/workflows/specfact.yml:

name: SpecFact CLI Validation

on:
  pull_request:
    branches: [main, dev]
  push:
    branches: [main, dev]
  workflow_dispatch:
    inputs:
      budget:
        description: "Time budget in seconds"
        required: false
        default: "90"
        type: string
      mode:
        description: "Enforcement mode (block, warn, log)"
        required: false
        default: "block"
        type: choice
        options:
          - block
          - warn
          - log

jobs:
  specfact-validation:
    name: Contract Validation
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      checks: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: "pip"

      - name: Install SpecFact CLI
        run: pip install specfact-cli

      - name: Set up CrossHair Configuration
        run: specfact code repro setup

      - name: Run Contract Validation
        run: specfact code repro --verbose --budget 90

      - name: Generate PR Comment
        if: github.event_name == 'pull_request'
        run: python -m specfact_cli.utils.github_annotations
        env:
          SPECFACT_REPORT_PATH: .specfact/projects/<bundle-name>/reports/enforcement/report-*.yaml

First Steps

Operational Modes

SpecFact CLI supports two practical ways of working:

CLI-only Mode (uvx): Fast, deterministic CLI usage for automation
- Works immediately with uvx specfact-cli@latest
- No installation required
- Uses local CLI analysis only
- Best for: CI/CD, quick testing, one-off commands
Installed CLI + IDE Prompt Mode (pip + specfact init --profile ... + optional specfact init ide)
- Requires pip install specfact-cli and first-run bundle selection (--profile or --install)
- Gives you a stable local specfact command plus mounted workflow groups
- Adds IDE prompt templates and slash commands when you run specfact init ide
- Lets your chosen AI copilot orchestrate SpecFact commands; the CLI itself remains deterministic
- Best for: development teams, brownfield analysis, guided IDE workflows

Mode Selection:

# CLI-only mode (uvx - no installation)
uvx specfact-cli@latest --help

# Installed CLI + IDE prompt mode
# After: pip install specfact-cli && specfact init
# Then use slash commands in IDE: /specfact.01-import legacy-api --repo .

Note: Slash commands live in your IDE, not in the CLI runtime. They are prompt templates that guide your AI copilot to call SpecFact commands in the right order.

Installed Command Topology

Fresh install exposes only core commands:

specfact init
specfact module
specfact upgrade

Category groups appear after bundle installation:

specfact project ...
specfact backlog ...
specfact code ...
specfact spec ...
specfact govern ...

Backlog authentication commands such as specfact backlog auth ... are provided by the installed backlog bundle, not by the permanent core command surface.

Profile outcomes:

Profile	Installed bundles	Available groups
`solo-developer`	`specfact-codebase`, `specfact-code-review`	`code`
`backlog-team`	`specfact-project`, `specfact-backlog`, `specfact-codebase`	`project`, `backlog`, `code`
`api-first-team`	`specfact-spec`, `specfact-codebase` (+`specfact-project` dependency)	`project`, `code`, `spec`
`enterprise-full-stack`	all five bundles	`project`, `backlog`, `code`, `spec`, `govern`

Upgrading from Pre-Slimming Versions

If you upgraded from a version where workflow modules were bundled in core, reinstall/refresh bundled modules:

specfact module init --scope project
specfact module init

If CI/CD is non-interactive, ensure your bootstrap includes profile/install selection:

specfact init --profile enterprise-full-stack
# or
specfact init --install all

For Greenfield Projects

Start a new contract-driven project:

specfact project snapshot

This will guide you through creating:

Initial project idea and narrative
Product themes and releases
First features and stories
Protocol state machine

With IDE Integration (Prompt Templates + Your AI Copilot):

# Step 1: Install SpecFact CLI
pip install specfact-cli

# Step 2: Navigate to your project
cd /path/to/your/project

# Step 3: Bootstrap runtime + module profile
specfact init --profile solo-developer

# Step 4: Initialize IDE integration (one-time per project)
specfact init ide --ide cursor

# Step 5: Use slash command in IDE chat
/specfact.02-plan init legacy-api
# Or use other plan operations: /specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth"

Important:

Interactive mode automatically uses your IDE workspace
Slash commands use numbered format: /specfact.01-import, /specfact.02-plan, etc.
Commands are numbered for natural workflow progression (01-import → 02-plan → 03-review → 04-sdd → 05-enforce → 06-sync)
No --repo . parameter needed in interactive mode (uses workspace automatically)
The AI assistant will prompt you for bundle names and other inputs if not provided

Use specfact init for runtime/bootstrap state and specfact init ide for IDE slash commands, prompt templates, and settings export.

See IDE Integration Guide for detailed setup instructions.

For Spec-Kit Migration

Convert an existing GitHub Spec-Kit project:

# Preview what will be migrated
specfact code import from-bridge --adapter speckit --repo ./my-speckit-project --dry-run

# Execute migration (one-time import)
specfact code import from-bridge \
  --adapter speckit \
  --repo ./my-speckit-project \
  --write

# Ongoing bidirectional sync (after migration)
specfact project sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch

Bidirectional Sync:

Keep Spec-Kit and SpecFact artifacts synchronized:

# One-time sync
specfact project sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional

# Continuous watch mode
specfact project sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional --watch

Note: SpecFact CLI uses a plugin-based adapter registry pattern. All adapters (Spec-Kit, OpenSpec, GitHub, etc.) are registered in AdapterRegistry and accessed via specfact project sync bridge --adapter <adapter-name>, making the architecture extensible for future tool integrations.

For Brownfield Projects

Analyze existing code to generate specifications.

With IDE Integration (Interactive AI Assistant Mode - Recommended):

# Step 1: Install SpecFact CLI
pip install specfact-cli

# Step 2: Navigate to your project
cd /path/to/your/project

# Step 3: Bootstrap runtime + module profile
specfact init --profile solo-developer

# Step 4: Initialize IDE integration (one-time per project)
specfact init ide --ide cursor

# Step 5: Use slash command in IDE chat
/specfact.01-import legacy-api
# Or let your IDE copilot walk through the prompt-driven flow

Important for IDE Integration:

Interactive mode automatically uses your IDE workspace (no --repo . needed in interactive mode)
Slash commands use numbered format: /specfact.01-import, /specfact.02-plan, etc. (numbered for workflow ordering)
Commands follow natural progression: 01-import → 02-plan → 03-review → 04-sdd → 05-enforce → 06-sync
Your IDE copilot can guide the slash-command flow if the prompt supports follow-up questions
The CLI still performs deterministic command execution and validation
Do NOT use --mode copilot as a synonym for built-in AI - IDE integration is prompt-driven orchestration around the CLI

CLI-Only Mode (Alternative - for CI/CD or when IDE integration is not available):

# Analyze repository (CI/CD mode - fast)
specfact code import my-project \
  --repo ./my-project \
  --shadow-only \
  --report analysis.md

# Analyze with CoPilot mode (enhanced prompts - CLI only, not for IDE)
specfact --mode copilot code import from-code my-project \
  --repo ./my-project \
  --confidence 0.7 \
  --report analysis.md

# Review generated plan
cat analysis.md

Note: When using IDE integration, use slash commands (for example /specfact.01-import) instead of assuming the CLI itself becomes AI-powered. The IDE prompt layer is what connects your copilot to SpecFact.

See IDE Integration Guide for detailed setup instructions.

Sync Changes:

Keep plan artifacts updated as code changes:

# One-time sync
specfact project sync repository --repo . --target .specfact

# Continuous watch mode
specfact project sync repository --repo . --watch

Next Steps

Explore Commands: See Command Reference
Learn Use Cases: Read Use Cases
Understand Architecture: Check Architecture
Set Up IDE Integration: See IDE Integration Guide

Quick Tips

Python 3.11+ required: SpecFact CLI requires Python 3.11 or higher
Start in shadow mode: Use --shadow-only to observe without blocking
Use dry-run: Always preview with --dry-run before writing changes
Check reports: Generate reports with --report <filename> for review
Progressive enforcement: Start with minimal, move to balanced, then strict
CLI-only vs Interactive: Use uvx for quick testing, pip install + specfact init for better results
IDE integration: Use specfact init ide to set up slash commands in your IDE after bootstrap
Slash commands: Use numbered format /specfact.01-import, /specfact.02-plan, etc. (numbered for workflow ordering)
Global flags: Place --no-banner before the command: specfact --no-banner <command>
Bridge adapter sync: Use sync bridge --adapter <adapter-name> for external tool integration (Spec-Kit, OpenSpec, GitHub, etc.)
Repository sync: Use sync repository for code change tracking
Semgrep (optional): Install pip install semgrep for async pattern detection in specfact code repro

Supported Project Management Tools

SpecFact CLI automatically detects and works with the following Python project management tools. No configuration needed - it detects your project’s environment manager automatically!

Automatic Detection

When you run SpecFact CLI commands on a repository, it automatically:

Detects the environment manager by checking for configuration files
Detects source directories (src/, lib/, or package name from pyproject.toml)
Builds appropriate commands using the detected environment manager
Checks tool availability and skips with clear messages if tools are missing

Supported Tools

1. hatch - Modern Python project manager

Detection: [tool.hatch] section in pyproject.toml
Command prefix: hatch run
Example: hatch run pytest tests/
Use case: Modern Python projects using hatch for build and dependency management

2. poetry - Dependency management and packaging

Detection: [tool.poetry] section in pyproject.toml or poetry.lock file
Command prefix: poetry run
Example: poetry run pytest tests/
Use case: Projects using Poetry for dependency management

3. uv - Fast Python package installer and resolver

Detection: [tool.uv] section in pyproject.toml, uv.lock, or uv.toml file
Command prefix: uv run
Example: uv run pytest tests/
Use case: Projects using uv for fast package management

4. pip - Standard Python package installer

Detection: requirements.txt or setup.py file
Command prefix: Direct tool invocation (no prefix)
Example: pytest tests/
Use case: Traditional Python projects using pip and virtual environments

Detection Priority

SpecFact CLI checks in this order:

pyproject.toml for tool sections ([tool.hatch], [tool.poetry], [tool.uv])
Lock files (poetry.lock, uv.lock, uv.toml)
Fallback to requirements.txt or setup.py for pip-based projects

Source Directory Detection

SpecFact CLI automatically detects source directories:

Standard layouts: src/, lib/
Package name: Extracted from pyproject.toml (e.g., my-package → my_package/)
Root-level: Falls back to root directory if no standard layout found

Example: Working with Different Projects

# Hatch project
cd /path/to/hatch-project
specfact code repro --repo .  # Automatically uses "hatch run" for tools

# Poetry project
cd /path/to/poetry-project
specfact code repro --repo .  # Automatically uses "poetry run" for tools

# UV project
cd /path/to/uv-project
specfact code repro --repo .  # Automatically uses "uv run" for tools

# Pip project
cd /path/to/pip-project
specfact code repro --repo .  # Uses direct tool invocation

External Repository Support

SpecFact CLI works seamlessly on external repositories without requiring:

❌ SpecFact CLI adoption
❌ Specific project structures
❌ Manual configuration
❌ Tool installation in global environment

All commands automatically adapt to the target repository’s environment and structure.

This makes SpecFact CLI ideal for:

OSS validation workflows - Validate external open-source projects
Multi-project environments - Work with different project structures
CI/CD pipelines - Validate any Python project without setup

Common Commands

# Check version
specfact --version

# Get help
specfact --help
specfact <command> --help

# Initialize project snapshot
specfact project snapshot --bundle my-project

# Validate everything
specfact code repro

# Set enforcement level
specfact govern enforce stage --preset balanced

Getting Help

Documentation: docs/
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: [email protected]

Development Setup

For contributors:

# Clone repository
git clone https://github.com/nold-ai/specfact-cli.git
cd specfact-cli

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
hatch run contract-test-full

# Format code
hatch run format

# Run linters
hatch run lint

See CONTRIBUTING.md for detailed contribution guidelines.