Getting Started with SpecFact CLI

This guide will help you get started with SpecFact CLI in under 60 seconds.

Primary Use Case: SpecFact CLI is designed for brownfield code modernization - reverse-engineering existing codebases into documented specs with runtime contract enforcement. See First Steps for brownfield workflows.

Installation

Option 1: uvx (CLI-only Mode)

No installation required - run directly:

uvx specfact-cli@latest --help

Best for: Quick testing, CI/CD, one-off commands

Limitations: CLI-only mode uses AST-based analysis which may show 0 features for simple test cases. For better results, use interactive AI Assistant mode (Option 2).

Option 2: pip (Interactive AI Assistant Mode)

Required for: IDE integration, slash commands, enhanced feature detection

# 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 (pyan3, syft, bearer, graphviz), install these packages in your environment.

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:

# Initialize IDE integration (one-time per project)
specfact init ide

# Or specify IDE explicitly
specfact init ide --ide cursor
specfact init ide --ide vscode

# Install required packages for contract enhancement
specfact init --install-deps

# Initialize for specific IDE and install dependencies
specfact init ide --ide cursor --install-deps

Note: Interactive mode requires Python 3.11+ and automatically uses your IDE workspace (no --repo . needed in slash commands).

Option 3: 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

Option 4: 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

      - 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 operational modes:

CLI-only Mode (uvx): Fast, AST-based analysis for automation
- Works immediately with uvx specfact-cli@latest
- No installation required
- May show 0 features for simple test cases (AST limitations)
- Best for: CI/CD, quick testing, one-off commands
Interactive AI Assistant Mode (pip + specfact init --profile ...): Enhanced semantic understanding
- Requires pip install specfact-cli and first-run bundle selection (--profile or --install)
- Better feature detection and semantic understanding
- IDE integration with slash commands
- Automatically uses IDE workspace (no --repo . needed)
- Best for: Development, legacy code analysis, complex projects

Mode Selection:

# CLI-only mode (uvx - no installation)
uvx specfact-cli@latest code import --repo . my-project

# Interactive mode (pip + specfact init - recommended)
# After: pip install specfact-cli && specfact init
# Then use slash commands in IDE: /specfact.01-import legacy-api --repo .

Note: Mode is auto-detected based on whether specfact command is available and IDE integration is set up.

Installed Command Topology

Fresh install exposes only core commands:

specfact init
specfact backlog auth
specfact module
specfact upgrade

Commands available after bundle installation:

specfact project ...
specfact project sync ...
specfact backlog ...
specfact code ...
specfact code analyze ...
specfact code drift ...
specfact code validate ...
specfact code repro ...
specfact spec ...
specfact govern ...
specfact govern enforce ...

Profile outcomes:

Profile	Installed bundles	Available groups
`solo-developer`	`specfact-codebase`	`code`
`backlog-team`	`specfact-project`, `specfact-backlog`, `specfact-codebase`	`project`, `project sync`, `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

Install the project bundle and inspect the currently mounted project workflow surface:

specfact module install nold-ai/specfact-project
specfact project --help
specfact project sync --help

The mounted project group contains the currently supported project-bundle workflows in this release.

With IDE Integration (Interactive AI Assistant Mode):

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

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

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

# Step 4: Use the current mounted commands or repo-local slash workflows
specfact project --help
specfact project sync --help

Important:

Interactive mode automatically uses your IDE workspace
Verify repo-local slash workflows against the generated IDE templates in your checkout
No --repo . parameter needed in interactive mode (uses workspace automatically)
Use specfact project --help, specfact code --help, and specfact backlog --help as the source of truth for mounted commands

See IDE Integration Guide for detailed setup instructions.

For Spec-Kit Migration

Convert an existing GitHub Spec-Kit project:

# Start a one-time import
specfact project sync bridge \
  --adapter speckit \
  --repo ./my-speckit-project

# 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: Initialize IDE integration (one-time per project)
specfact init
# Or specify IDE: specfact init ide --ide cursor

# Step 4: Use slash command in IDE chat
/specfact.01-import legacy-api
# Or let the AI assistant prompt you for bundle name and other options

Important for IDE Integration:

Interactive mode automatically uses your IDE workspace (no --repo . needed in interactive mode)
Verify repo-local slash workflows against the generated IDE templates in your checkout
The AI assistant will prompt you for bundle names and confidence thresholds if not provided
Better feature detection than CLI-only mode (semantic understanding vs AST-only)
Do NOT use --mode copilot with IDE slash commands - IDE integration automatically provides enhanced prompts

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 my-project \
  --repo ./my-project \
  --report analysis.md

# Review generated plan
cat analysis.md

Note: --mode copilot is for CLI usage only. When using IDE integration, use slash commands (e.g., /specfact.01-import) instead - IDE integration automatically provides enhanced prompts without needing the --mode copilot flag.

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
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 to set up slash commands in IDE (requires pip install)
Slash commands: Use the IDE templates generated for your checkout and keep them aligned with the mounted CLI surface
Global flags: Place --no-banner before the command: specfact --no-banner <command>
Bridge adapter sync: Use project sync bridge --adapter <adapter-name> for external tool integration (Spec-Kit, OpenSpec, GitHub, etc.)
Repository sync: Use project 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

# Inspect currently mounted project workflows
specfact project --help
specfact project sync --help

# Validate everything
specfact code repro

# Set enforcement level
specfact govern enforce stage --help

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.