Skip to content

CLI Reference

The fcc command-line tool provides commands for project scaffolding, validation, simulation, and documentation generation. It is built with Click and installed as an entry point via pip install -e ..

Global Options

fcc --version    Show the framework version
fcc --help       Show available commands

Commands

fcc init

Initialize a new FCC project with scaffolded directory structure.

Synopsis:

fcc init --name <project-name> [--dir <target-directory>]

Options:

Option Required Default Description
--name Yes -- Project name
--dir No . Target directory for the new project

What it creates:

  • fcc_config.yaml -- Project configuration
  • pyproject.toml -- Python project file
  • src/ -- Source code directory
  • tests/ -- Test directory
  • data/ -- Data files directory (personas, workflows, schemas, scenarios, governance)
  • Makefile -- Build automation

Example:

fcc init --name my-doc-project --dir /path/to/workspace
cd /path/to/workspace
make venv && source .venv/bin/activate && make install-dev

fcc add-persona

Add a new persona to an existing FCC project.

Synopsis:

fcc add-persona <name> --phase <Find|Create|Critique> --id <short-id> [--dir <project-dir>]

Arguments:

Argument Description
name Full persona name (e.g., "Custom Analyst")

Options:

Option Required Default Description
--phase Yes -- FCC phase: Find, Create, or Critique
--id Yes -- Short identifier (e.g., CA)
--dir No . Project directory

Example:

fcc add-persona "Security Reviewer" --phase Critique --id SR

fcc validate

Validate the FCC project structure, checking for required files and directories.

Synopsis:

fcc validate [--dir <project-dir>]

Options:

Option Required Default Description
--dir No . Project directory to validate

Checks performed:

  • fcc_config.yaml exists
  • pyproject.toml exists
  • src/ directory exists
  • tests/ directory exists
  • data/ directory exists

Exit codes:

  • 0 -- Validation passed
  • 1 -- One or more validation issues found

Example:

fcc validate --dir /path/to/my-project

fcc simulate

Run an FCC workflow simulation using either mock (deterministic) or AI-powered mode.

Synopsis:

fcc simulate [--scenario <scenario-id>] [--mock | --no-mock] [--dir <project-dir>]

Options:

Option Required Default Description
--scenario No GEN-001 Scenario ID to run
--mock / --no-mock No --mock Use mock AI client (deterministic) or real AI
--dir No . Project directory

How it works:

  1. Loads the workflow graph from data/workflows/base_sequence.json.
  2. Creates an AIClient with either the mock provider or a real provider (Anthropic/OpenAI).
  3. Constructs an AISimulationEngine with max_steps=20.
  4. Runs the simulation starting from the RC node.
  5. Writes traces to traces_ai.json.

Example:

# Run with mock client (default, no API key needed)
fcc simulate --scenario GEN-001

# Run with real AI client
fcc simulate --no-mock --scenario ADV-001

fcc generate-docs

Generate docs-as-code documentation from persona specifications using Jinja2 templates.

Synopsis:

fcc generate-docs [--dir <output-dir>] [--personas <filter>]

Options:

Option Required Default Description
--dir No docs Output directory for generated documentation
--personas No all Filter: all, core, integration, governance, stakeholder, champions, or a single persona ID

Output:

Generates 56 documentation files per persona (tutorials, prompts, workflows) across the filtered set. With all 24 personas, this produces 1,348 files.

Example:

# Generate docs for all personas
fcc generate-docs --dir docs/generated

# Generate docs for core personas only
fcc generate-docs --personas core

# Generate docs for a single persona
fcc generate-docs --personas RC

fcc validate-docs

Validate generated documentation for completeness, checking for empty files.

Synopsis:

fcc validate-docs [--dir <docs-dir>]

Options:

Option Required Default Description
--dir No docs Documentation directory to validate

Checks performed:

  • Scans <dir>/fcc/personas/ recursively for .md files.
  • Flags any empty files.

Example:

fcc validate-docs --dir docs/generated

fcc sitemap

Generate a SITEMAP.md file for the documentation tree.

Synopsis:

fcc sitemap [--dir <output-dir>]

Options:

Option Required Default Description
--dir No docs Output directory

Output:

Generates <dir>/fcc/SITEMAP.md with a linked index of all generated documentation files.

Example:

fcc sitemap --dir docs/generated

Environment Variables

Variable Purpose
ANTHROPIC_API_KEY Required for --no-mock simulation with Anthropic
OPENAI_API_KEY Required for --no-mock simulation with OpenAI