Getting Started with SpecFact CLI

Welcome to SpecFact CLI! This guide will help you get started in under 60 seconds.

Installation

Choose your preferred installation method:

  • Installation Guide - All installation options (uvx, pip, Docker, GitHub Actions)
  • Installation Guide - Optional dependencies for graph-based analysis (pyan3, syft, bearer, graphviz)

Quick Start

Module System Note

SpecFact runs on a lifecycle-managed module system.

  • Core runtime manages lifecycle, registry, contracts, and orchestration.
  • Feature behavior is implemented in module-local command implementations.
  • This allows feature modules to evolve independently without repeatedly rewiring CLI core logic.

Your First Command

For Legacy Code Modernization (Recommended):

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

# Interactive AI Assistant mode (requires pip install + specfact init)
# See First Steps guide for IDE integration setup

For New Projects:

# Install a project-oriented bundle first, then inspect the mounted workflow surface
specfact module install nold-ai/specfact-project
specfact project --help

Note: Interactive AI Assistant mode provides better feature detection and semantic understanding, but requires pip install specfact-cli and IDE setup. CLI-only mode works immediately with uvx but may show 0 features for simple test cases.

Migration Note (0.40.0)

Flat root commands were removed. Use the mounted grouped command forms:

  • specfact validate ... -> specfact code validate ...
  • specfact code repro ... -> specfact code repro ...
  • specfact sync ... -> specfact project sync ...
  • specfact govern enforce ... -> specfact govern enforce ...
  • specfact policy ... -> specfact backlog policy ...

First-run bundle selection examples:

specfact init --profile solo-developer
specfact init --install backlog,codebase
specfact init --install all

Marketplace bundle install examples:

specfact module install nold-ai/specfact-codebase
specfact module install nold-ai/specfact-backlog

Official bundles are published in the nold-ai/specfact-cli-modules registry and verified as official tier during install. Some bundles install dependencies automatically:

  • nold-ai/specfact-spec -> pulls nold-ai/specfact-project
  • nold-ai/specfact-govern -> pulls nold-ai/specfact-project

Modernizing Legacy Code?

New to brownfield modernization? See our Brownfield Engineer Guide for a complete walkthrough of modernizing legacy Python code with SpecFact CLI.

Next Steps

Need Help?