@context-forge/cli

Terminal interface for Context Forge — context assembly, project management, workflow navigation, and configuration.

How It Works

cf works like git — install it globally and it automatically detects your project based on your current working directory. No configuration files to manage per-project; just cd into any registered project and run commands.

Installation

# Install globally (recommended: meta-package installs both CLI and MCP server)
npm install -g @context-forge/context-forge

# Or install the CLI alone
npm install -g @context-forge/cli

# Initialize a project (from the project root)
cd ~/repos/my-project
cf init

# Install the ai-project-guide templates (recommended)
cf guides install

# Install Claude Code slash commands (recommended)
cf install-commands

cf init registers the current directory as a Context Forge project. cf guides install bootstraps the ai-project-guide prompt templates that Context Forge's context engine is designed around. cf install-commands adds /cf:* slash commands to Claude Code.

Quick Start

# All commands are discoverable
cf --help
cf project --help

# Check project status
cf status

# Set project fields
cf set phase 6
cf set slice 175

# Browse project artifacts
cf list initiatives    # Architecture initiatives
cf list slices         # Slices in the active plan
cf list tasks          # Task files with progress
cf list items          # Individual tasks from the active task file

# What should I do next?
cf next

# Detailed information
cf project get

# View available prompt templates
cf prompt list

# Get a specific prompt with project variables substituted
cf prompt get P5

Claude Code Slash Commands

When installed via cf install-commands, these slash commands are available directly in Claude Code sessions:

Each command runs cf under the hood — same CWD-based project resolution, same output.

Commands Reference

Listing Commands

Project & Workflow

Administration

Rule Resolutions

An adopted project keeps its own rules (CLAUDE.md, AGENTS.md, .cursor/rules, ...) beside the guide's. cf rules inventory lists both sides; for a composite file such as CLAUDE.md it gives the line range of the managed block, so only the project-owned text outside it is compared. The comparison is the agent's job (guide prompt conventions-reconciliation); cf never judges whether two rules conflict. Each decision is recorded with cf rules resolve. Each guide rule in the inventory has an agents field: the audiences from its agents: marker (claude, agents, copilot, cursor), or null when it goes to every agent. A resolution renders only in the managed blocks its rule reaches.

Resolutions are stored in .context-forge/rule-resolutions.json, which is committed to git:

{
  "version": 1,
  "resolutions": [
    { "guideRule": "git.md", "projectSource": "CLAUDE.md",
      "statement": "Every change goes through a PR; never commit directly to main." }
  ]
}

• A resolution is identified by the file pair (guideRule is the rule's file name in the guide, projectSource a checkout-relative path), never by rule text, so rewording a guide rule leaves it in force.
• statement is one line, stored and rendered verbatim. It may not contain a line break, a backtick in either name, or any context-forge marker comment. A malformed file fails setup-ide before anything is written.
• Every setup-ide run renders the live resolutions as a ## Project Rule Resolutions section at the end of each managed block (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md). Re-running gives identical files. Without a resolutions file the output is unchanged.
• Resolutions on a scoped guide rule excluded by rules.exclude are skipped without comment.
• If a resolution names a guide rule the guide no longer has, or a project file that no longer exists, setup-ide warns on stderr (exit code 0) and does not render it.
• To remove a resolution, edit the JSON file by hand.
• Precedence is advisory. The conflicting guide text stays in the block and in installed scoped rule files; the section tells the agent which rule wins.

Common Options

• --project <name|id> — Override the active project by name or ID
• --json — Output as JSON (not applicable to build and prompt get)

Project Resolution

cf resolves which project to operate on using a priority chain:

1. --project flag — highest priority. Accepts project name or ID.
2. CWD detection — if the current directory is inside a registered project's path, or inside a registered worktree path, that project (and worktree) is resolved automatically.
3. Git worktree detection — if CWD is an unregistered git worktree of a known project, the project is resolved automatically (useful before running cf worktree init).
4. default_project config — if set via cf config set default_project <name>, used as a fallback.

This means you can manage multiple projects just by cd-ing between them — no switching commands needed.

Phase Shorthands

cf prompt get and cf build --phase accept phase shorthands:

Shorthands are derived at runtime from the project's prompt asset file.

Phase / Instruction Auto-Set

Setting the development phase automatically updates instruction to match:

cf set phase 6
# Updated phase = Phase 6: Implementation on project my-project
# Updated instruction = Phase 6: Implementation (auto-set from phase)

Setting instruction directly does not change developmentPhase.

Smart Index Resolution

Setting artifact fields by numeric index resolves to the matching file on disk:

cf set slice 175
# Updated slice = 175-slice.context-output-consolidation on project my-project
# Updated tasks = 175-tasks.context-output-consolidation (auto-set from slice)

When no file exists yet, the CLI derives the stem from the slice plan entry:

cf set slice 166
# (no 166-slice.*.md on disk — derives from plan entry "Consistency Checker")
# Updated slice = 166-slice.consistency-checker on project my-project
# Updated tasks = 166-tasks.consistency-checker (auto-set from slice)

Setting fileSlice always auto-sets fileTasks to match.

Architecture

The CLI wraps @context-forge/core directly (no MCP layer). All core services are imported from @context-forge/core/node.

Development (monorepo)

pnpm --filter @context-forge/cli build     # Compile TypeScript
pnpm --filter @context-forge/cli dev       # Watch mode
pnpm --filter @context-forge/cli test      # Run tests
pnpm --filter @context-forge/cli typecheck # Type check

Changelog

v0.6.0

• Compound workflow commands — cf concept, cf initiatives, cf arch <n>, cf plan <n>, cf slice <n>, cf tasks <n>, cf implement <n> set artifact + phase + build context in one step
• cf list consolidation — all artifact listing under cf list <type> (cf list slices, cf list tasks, etc.)
• Slash commands — 16 Claude Code slash commands for compound commands, status, and workflow
• cf help --json — machine-readable command catalog for agent consumption
• cf version --json — version introspection with breaking changes tracking
• Structured JSON errors — error codes on all UserError instances, JSON error output via --json or CF_JSON=1
• Idempotent set — cf set detects no-change and skips write
• cf guides uninstall — clean removal of guide submodule or clone

v0.5.0

• Worktree support — cf worktree init|list|get|update|rm for parallel multi-initiative development; cf status --worktree and --worktrees for cross-directory access
• Worktree-aware project resolution — auto-detects project from git worktree path even before cf worktree init
• Worktree-scoped field routing — cf set phase/slice/tasks/arch/plan updates the active WorktreeContext when resolved from a worktree
• cf check across all worktrees — consistency checks see worktree-scoped fields (phase, slice, arch, etc.) correctly
• cf check --slice <n> — narrow checks to a specific slice; --yes skips confirmation in fix mode
• cf tasks command — renamed from cf task for consistency (cf tasks list, cf tasks items)
• cf backup — versioned project data backup with auto-pruning (keeps last 10)
• cf setup-ide claude — configures Claude Code integration with CLAUDE.md backup safety

v0.4.0

• Discovery commands — cf arch list, cf plan list, cf slice list, cf tasks list, cf tasks items for browsing project artifacts at every level
• Smart index resolution — cf set slice 166 derives the filename from the slice plan when no file exists on disk
• Auto-set fileTasks — setting fileSlice always auto-sets fileTasks, even when the task file doesn't exist yet
• Enhanced cf status — now shows Date, Arch, and Plan fields
• Workflow navigation — cf status and cf next powered by WorkflowNavigator with slice status derivation and priority-ordered next-action recommendations

v0.3.0

• Template variable completion — artifact fields (fileArch, fileSlicePlan, fileHLD, fileSpec) and aliases (arch, plan, hld, spec) available in prompt templates, with index extraction (archIndex, planIndex)
• Consolidated project context — cf build output uses clean key-value ### Project Context block instead of bracket-wrapped format; template field removed; schema field names used throughout
• Unified opening statement — always "Working on {name}..." regardless of workType
• Phase auto-sets instruction — cf set phase N also updates instruction to match
• Top-level shortcuts — cf set and cf get work as shortcuts for cf project set/get
• Codebase Reference — when the active prompt's profile lists fileComprehension or fileDocsMap, cf build adds a ### Codebase Reference section after Project Context naming the registered comprehension doc and the docs map, with the docs map shown as current or out of date (see docs/ADOPTION-PRIMITIVES.md)

v0.2.0

• CWD-based project detection — cf auto-detects the project from your current directory
• Name-based resolution — use --project orchestration with project names instead of IDs
• Resolution indicators — cf status shows how the project was resolved (from CWD, --project flag)
• Compact cf project list — Name/Path/Slice columns with * active indicator and ~ path shortening
• Tighter output formatting — consistent label alignment, suppressed empty fields, standardized error messages

v0.1.0

• Initial release with 8 commands: status, next, build, config, project, future, check, prompt
• Integration with @context-forge/core for context assembly
• Phase shorthands for prompt templates
• JSON output mode on all applicable commands