cf² CLI Usage Guide

cfcf and cf² are used interchangeably. Both are pronounced "cf square." cfcf in code and commands; cf² in docs.

This guide covers all cf² commands and typical workflows.

Prerequisites

cfcf binary installed (or Bun + source for development)
Git installed
At least one AI coding agent installed: Claude Code or Codex CLI

First-Time Setup

`cfcf init`

Run once after installing cfcf. Detects installed agents, asks for configuration defaults, and saves the config.

cfcf init

What it does:

Scans for installed agents (Claude Code, Codex CLI) and reports what it finds
Verifies git is available
Asks you to choose agents for seven roles: five iteration roles (dev, judge, architect, reflection, documenter) plus two interactive roles (Product Architect, Help Assistant). Each prompt asks for both adapter and model.
Asks for model selection per role via a numbered picker driven by each adapter's bundled model registry (e.g. opus / sonnet / haiku for Claude Code; gpt-5 / o3 / o3-mini for Codex). Pick 0 for "(use adapter default)" — note: NOT offered for claude-code-ollama / opencode-ollama, which require an explicit --model flag (item 6.33). Edit the per-adapter model list later from the web UI's Settings → Model registry section; the CLI picker reads the augmented list on each subsequent run. For the *-ollama adapters (item 6.28), the model list is sourced from ollama list rather than the cfcf seed registry; for the standalone opencode adapter the picker shows just the "(adapter default)" + custom-name options because opencode's provider auth (and therefore its valid model list) lives outside cfcf's view.
Detects ollama (item 6.28) and surfaces the count of locally-pulled models. When ollama is present alongside claude and/or opencode, the agent picker for each role conditionally includes claude-code-ollama and opencode-ollama so you can route unattended roles through a local model server. After init, ollama models are auto-refreshed on every cfcf server start (item 6.33) — newly-pulled models propagate to role-picker dropdowns without re-running cfcf init. There's also a "Refresh ollama models" button in the web UI Agent-roles section (Settings + workspace Config) for the impatient between-restarts case.
Surfaces three related warnings for the Claude Code paths (items 6.28 + 6.30) when picking adapters for unattended roles (dev / judge / reflection / documenter / architect — note: architect counts as unattended for ALL invocation paths, including manual cfcf review, since its spawn pipeline is headless claude -p regardless of how it's invoked):
- Yellow / policy-grade: fires when claude-code (direct, talking to Anthropic's API) is picked. Anthropic's third-party-harness policy restricts subscription OAuth to interactive use; the unattended cf² loop is the violation pattern. Recommendation: switch to codex, claude-code-ollama, opencode, or opencode-ollama.
- Blue / API-parse-error note (item 6.30, May 2026): fires when claude-code-ollama is picked. Some non-coder-tuned local models (notably gemma4:31b) produce tool-use / tool-result content blocks that Anthropic's strict Messages API parser rejects with API Error: Content block not found. If you hit this, switch to opencode-ollama for the same model — its OpenAI-compatible endpoint is more tolerant.
- Blue / log-visibility note: fires when claude-code-ollama is picked. The ollama path is policy-clean, but claude -p still buffers stdout for the entire run — log files stay silent until the agent exits, then dump the final response. If you want live progress monitoring during long iterations, prefer codex (streams natively) or the opencode adapters.
- All three warnings are informational; neither blocks the save. Only PA and HA on Claude variants do NOT trigger any warning (they take over your shell via stdio: "inherit" — the only paths actually within Anthropic's allowed-interactive scope). See cfcf help anthropic-policy for the full breakdown.
Asks for default iteration limits (max iterations, pause cadence) and the reflection safeguard ceiling (reflectSafeguardAfter, default 3 -- the maximum consecutive iterations the judge may skip reflection before cfcf forces it)
Asks for the pre-loop review + post-SUCCESS documenter flags (item 5.1):
- autoReviewSpecs (default false) -- if true, Start Loop first runs the Solution Architect and gates on its readiness signal
- readinessGate (default blocked) -- only consulted when autoReviewSpecs=true; levels are never / blocked / needs_refinement_or_blocked
- autoDocumenter (default true) -- if false, the loop skips the Documenter on SUCCESS; run cfcf document manually when you want docs
Explains the permission flags agents will run with (--dangerously-skip-permissions for Claude Code, -a never -s danger-full-access for Codex)
Saves everything to the config file

To re-run setup (e.g., after installing a new agent):

cfcf init --force

Server Management

cfcf runs a background server that manages workspaces, executes iterations, and streams logs. The CLI communicates with the server via HTTP.

`cfcf server start`

Start the cfcf server in the background.

cfcf server start                # Default port 7233
cfcf server start --port 8080    # Custom port

`cfcf server stop`

Stop the running server.

cfcf server stop

`cfcf server status`

Check if the server is running and show details.

cfcf server status

Output:

cfcf server v0.17.0
  Status:     running
  Port:       7233
  PID:        12345
  Uptime:     42s
  Configured: yes
  Agents:     claude-code, codex

The same information (plus the full global config) is available in the web GUI at http://localhost:7233/#/server. Since v0.7.3 that page is a full editor -- wire-compatible with cfcf config edit via the same PUT /api/config endpoint. Reach it from the Settings link in the top bar. The web UI's full top-level navigation:

Workspaces — dashboard + per-workspace iteration history, log viewer, config tab. Each card on the dashboard surfaces a pulse-animated chip ("● review running" / "● document running" / "● reflect running" / "● loop running") when ANY agent is actively running on that workspace, including standalone Review / Document / Reflect runs that don't touch the workspace's loop-status badge (F.22, v0.24).
Memory — Clio (cross-workspace memory): search, browse, ingest, audit, projects, trash.
Agents (item 6.8) — per-role instruction-template editor with versioning + promote-to-production. One sub-tab per role; the bundled cf² default is always selectable (read-only). Save edits as either a full version (replaces the default; doesn't auto-upgrade) or an augmented version (extension-only on top of the live default; auto-upgrades when cf² ships a new template).
Settings — global config (per-role agent + model, ollama-models refresh button, model registry, notifications).
Help — in-shell version of the documentation guides.

`cfcf server reap` (item 6.31, v0.21.0)

Detect + interactively kill orphan agent processes left behind by a previous server PID — typically when the server died via SIGKILL or an OS panic, bypassing the SIGINT/SIGTERM signal handlers that normally clean up child agents on graceful shutdown. Pure system call — does NOT require the cfcf server to be running.

cfcf server reap                 # interactive: lists candidates, asks y/N before killing
cfcf server reap --yes           # non-interactive: kill anything detected

The matcher is conservative — three conjoined filters (PPID==1 + same effective user + cfcf-spawned command shape). Empty case:

No zombie agent processes detected.

Boot-time auto-reap runs the same logic on every cfcf server start, so manual reaping is only needed if you don't want to bounce the server. See troubleshooting.md → "Loop appears hung / silent" if you suspect orphans.

Global Configuration

`cfcf config show`

Display the current global configuration.

cfcf config show

Output:

Config file: /Users/you/Library/Application Support/cfcf/config.json
Dev agent:        claude-code
Judge agent:      codex
Architect agent:  claude-code
Documenter agent: claude-code
Reflection agent: claude-code (model: opus)
Product Architect agent: claude-code (model: sonnet)
Help Assistant agent:    claude-code (model: sonnet)
Max iterations:   10
Pause every:      never
Reflect safeguard: force after 3 consecutive judge opt-outs
Permissions:      acknowledged
Available agents: claude-code, codex

`cfcf config edit`

Re-run the interactive setup (same as cfcf init --force).

cfcf config edit

Quick Status

`cfcf status`

One-command overview of cfcf state: configuration, server status, and active workspace loops.

cfcf status                          # Overview of everything
cfcf status --workspace my-project     # Detailed loop status for a workspace

With --workspace, shows the current loop phase, iteration progress, judge determinations, and pending questions.

Workspace Management

Workspaces link cfcf to a local git repository. Each workspace has its own configuration (agents, iteration limits, etc.) that inherits from the global defaults.

`cfcf workspace init`

Create a new cfcf workspace linked to a git repository.

cfcf workspace init --repo /path/to/my-project --name my-project

The repo must be:

An existing directory
A git repository (has been git init'd)
Has at least one commit

Options:

--repo <path> (required) -- Absolute or relative path to the git repo
--name <name> (required) -- Human-readable workspace name

The workspace inherits agent settings from your global config. To override per-workspace, use the API or edit the workspace config file directly.

`cfcf workspace list`

List all workspaces.

cfcf workspace list

`cfcf workspace show`

Show detailed configuration for a workspace.

cfcf workspace show my-project

`cfcf workspace delete`

Delete a workspace from cfcf. This removes the cfcf config only -- your git repo is untouched.

cfcf workspace delete my-project

Product Architect (interactive Problem Pack authoring)

`cfcf spec [task...]`

Launch the Product Architect — an interactive cf² agent that helps you author + iterate the Problem Pack files (problem-pack/problem.md / success.md / constraints.md / hints.md / style-guide.md / context/*.md). The agent CLI's TUI takes over your shell until you exit. PA has the full cf² docs in its system prompt, so it knows what each file is for + how downstream agents will use them.

cfcf spec                                          # interactive on cwd
cfcf spec "Tighten the success.md auth criteria"   # opens with this task
cfcf spec --repo /path/to/elsewhere                # explicit repo path
cfcf spec --agent claude-code                      # override config.productArchitectAgent
cfcf spec --print-prompt                           # debug: print prompt + exit
cfcf spec --safe                                   # opt back into per-command permission prompts

What PA does:

Greets + summarises the State Assessment cf² injects at launch (git status, workspace registration, Problem Pack files, server, prior memory)
Insists on git init + cfcf workspace init first if missing (drives both itself, with permission)
Drafts the Problem Pack files with you, asking clarifying questions
Reviews existing Problem Pack content + suggests refinements (before/after loops)
Persists session memory in Clio + locally on disk

PA hard-refuses to: write code (→ dev role), design architecture or write plan.md (→ Solution Architect), review iteration quality (→ judge), do reflection (→ cfcf reflect), write final docs (→ cfcf document). It redirects you to the right role.

Permissions. By default PA runs with full permissions — same as the iteration-time agents. The user accepted this trust contract at cfcf init; PA inherits it. --safe opts back into per-command permission prompts + the default codex sandbox for one session.

Memory. PA maintains a three-tier memory:

pa-workspace-memory (Clio, one per workspace) — the rolling digest that gets injected into every PA prompt
pa-session-<sessionId> (Clio, one per session) — full transcript archive, immutable
<repo>/.cfcf-pa/session-<id>.md (disk, one per session) — live scratchpad written turn-by-turn

Plus pa-global-memory (Clio, one cross-workspace doc) for user preferences spanning all workspaces.

See product-architect.md for the full reference (memory protocol, sandbox details, web UI integration).

Solution Architect Review

`cfcf review`

Run the Solution Architect agent to review your Problem Pack before starting unattended development. Advisory, repeatable -- run as many times as you like.

cfcf review --workspace my-project

What the architect does:

Reviews problem.md, success.md, constraints, hints, and context files
Checks context completeness -- is there enough for a dev agent to work unattended?
Identifies gaps and ambiguities that would cause an engineer to ask questions
Runs an initial security assessment
Outlines solution options and trade-offs
Produces an implementation plan (cfcf-docs/plan.md) for the dev agent to build on
Writes a readiness assessment: READY / NEEDS_REFINEMENT / BLOCKED / SCOPE_COMPLETE — the last value (added 2026-05-02) means the architect believes the plan is fully delivered and recommends ending the loop.

First-run vs re-review mode (v0.7.0+)

The architect automatically detects which mode to use:

First-run mode: cfcf-docs/plan.md is absent or has no completed items. The architect produces a fresh plan from scratch and scaffolds the initial docs/ stubs.
Re-review mode: cfcf-docs/plan.md already has completed [x] items. The architect reads the full prior history (iteration logs, decision log, reflection reviews), compares to the current Problem Pack, and either:
- Appends new pending iterations when new requirements are detected (completed items never touched), or
- Leaves plan.md alone and says so in architect-review.md when the existing plan still covers the pack.
cf² enforces the non-destructive rule: if the architect's rewrite removes a completed item or an iteration header, plan.md is auto-reverted to the pre-spawn snapshot and a warning is logged. Re-review also skips re-scaffolding docs/*.md (already maintained by dev + documenter).

Typical flow:

cfcf review --workspace my-project     # Architect identifies gaps
# → User reads architect-review.md, refines problem-pack/
cfcf review --workspace my-project     # Re-review after changes
# → Architect says READY
cfcf run --workspace my-project        # Start unattended development

Running Iterations

`cfcf run` -- Dark Factory Loop

Start the full iteration loop. Each iteration runs dev → judge → reflect (conditional) → decide and produces up to three separate commits; when autoReviewSpecs=true a leading pre-loop review phase runs on main and gates the loop on the architect's readiness signal; when the judge determines SUCCESS, documenter runs (unless autoDocumenter=false). This is the primary workflow.

Pause vs. resume. cfcf run has no --action flag — it always starts a fresh loop. Pause-action choice (continue / finish_loop / stop_loop_now / refine_plan / consult_reflection) happens at resume time via cfcf resume --action <action>. See cfcf resume below.

cfcf run --workspace my-project

What happens:

Starts the iteration loop asynchronously.
Pre-loop review (conditional, autoReviewSpecs=true). Runs on main. Solution Architect reviews the Problem Pack, commits architect-review.md + plan.md + signals + doc stubs as cfcf pre-loop review (<readiness>). If the readinessGate rejects, the loop pauses with the architect's gaps as pendingQuestions; on Resume the architect re-runs (see cfcf resume below). If the gate accepts, the loop enters iteration 1 branched off main.
For each iteration: a. Reads the Problem Pack, rebuilds iteration-history.md from committed iteration-logs, assembles context (cfcf-docs/ + sentinel-merged CLAUDE.md/AGENTS.md). b. Creates a git feature branch: cfcf/iteration-N. c. Launches the dev agent with the assembled context. Commits as cfcf iteration N dev (<adapter>). d. Launches the judge agent to evaluate the iteration. Archives the assessment. Commits as cfcf iteration N judge (<adapter>). e. Launches the reflection agent (conditional -- runs unless the judge set reflection_needed: false AND the reflectSafeguardAfter ceiling hasn't been hit). Non-destructively rewrites pending plan items when the evidence warrants. Commits as cfcf iteration N reflect (<health>): <key_observation>. f. Decision engine evaluates judge + reflection signals:
- SUCCESS → run Documenter (unless autoDocumenter=false), merge, push to remote, stop.
- PROGRESS → continue to next iteration.
- STALLED → apply onStalled policy (continue / stop / alert).
- ANOMALY → pause and alert user.
- Reflection recommend_stop: true → pause (takes precedence over a judge continue). g. If pause cadence reached → pause and wait for user review. h. If auto-merge enabled → merge the iteration branch to main.
The CLI polls for status, showing phase transitions in real-time.
On pause: shows questions and hints for cfcf resume.
On completion: shows iteration history and outcome.

Options:

--workspace <name> (required) -- workspace name or ID
--problem-pack <path> (optional) -- custom Problem Pack path (default: <repo>/problem-pack/)
--auto-review / --no-auto-review (optional, item 5.1) -- per-run override: force the Solution Architect to run as a pre-loop phase (--auto-review) or skip it (--no-auto-review). When the flag is omitted the workspace's autoReviewSpecs config value decides.
--auto-document / --no-auto-document (optional, item 5.1) -- per-run override for the post-SUCCESS Documenter. When omitted the workspace's autoDocumenter config value decides.
--readiness-gate <level> (optional, item 5.1) -- per-run override for the pre-loop readiness gate: never | blocked | needs_refinement_or_blocked. Only consulted when auto-review is on.

Per-run overrides are persisted on loop-state.json for this run, so a pause + resume keeps the same behaviour across server restarts.

`cfcf run` -- Manual Mode

Run any command within a workspace (for testing, debugging, or non-agent tasks).

cfcf run --workspace my-project -- echo "hello"
cfcf run --workspace my-project -- npm test
cfcf run --workspace my-project -- make build

Same branch/commit/log behavior, but without context assembly or agent launching.

Problem Pack

The Problem Pack is a directory of Markdown files that define your problem. Located at <repo>/problem-pack/ by default (scaffolded by cfcf workspace init).

Required files:

problem.md -- what needs to be built or fixed
success.md -- how success is measured (test criteria)

Optional files:

constraints.md -- guardrails, limitations
hints.md -- technical hints, preferred approaches
style-guide.md -- code style guidelines
context/ -- additional context (architecture docs, API specs, etc.)

cfcf-docs/ (Generated by cfcf)

When running in agent mode, cfcf writes a cfcf-docs/ directory into the repo. This contains:

Process definition, iteration history, judge feedback, user feedback
Templates for the agent to fill in (handoff document, signal file)
The agent's evolving plan and decision log

These files are tracked in git. See docs/design/agent-process-and-context.md for the full specification.

Loop Control

`cfcf resume`

Resume a paused iteration loop. The loop pauses when:

Pause cadence is reached (every N iterations).
The dev agent or judge signals user_input_needed.
The judge detects an anomaly (token exhaustion, circling, etc.).
The reflection agent sets recommend_stop: true.
The pre-loop Solution Architect's readiness signal fails the readinessGate (when autoReviewSpecs=true). In this case the loop hasn't yet entered iteration 1 -- it paused before the first iteration branch was created.

cfcf resume --workspace my-project
cfcf resume --workspace my-project --feedback "Focus on error handling in the API layer"
cfcf resume --workspace my-project --action finish_loop
cfcf resume --workspace my-project --action consult_reflection --feedback "judge says SUCCESS but reflection says STALLED — which is right?"
cfcf resume --workspace my-project --action stop_loop_now --feedback "started by mistake, no scope to deliver"

Structured pause actions (--action <action>, item 6.25, 2026-05-02). Defaults to continue for back-compat. Validated by commander's choices(); bad values are rejected at parse time. The five values:

Action	What the harness does
`continue` (default)	Run the next dev iteration. Free-text `--feedback` becomes guidance for the dev agent.
`finish_loop`	Exit the loop on a positive note. Documenter runs if `autoDocumenter=true`.
`stop_loop_now`	Exit the loop immediately. No documenter regardless of config. Free-text `--feedback` is captured as an audit note in a new `loop-stopped` history event.
`refine_plan`	Run the architect synchronously to revise `cfcf-docs/plan.md` with your feedback as direction, then resume the loop.
`consult_reflection`	Run reflection in consult mode with `--feedback` as the query. Reflection sets `harness_action_recommendation` in its signals; the harness then routes per the recommendation.

Action availability is gated by pause reason. The server validates the action against the current pauseReason and rejects mismatched combinations with a clear error and the list of allowed actions. For example:

consult_reflection is only valid when reflection signals are available (i.e. at least one iteration has run).
refine_plan is valid in pre-loop pauses (architect blocked the loop) and in mid-loop pauses; it is not valid mid-iteration when the dev agent is asking a user_input_needed question.
On the special scope_complete pause case (architect's SCOPE_COMPLETE verdict), only finish_loop / stop_loop_now / refine_plan are accepted; continue and consult_reflection are hidden.

--feedback lifecycle. The optional --feedback text is written to cfcf-docs/user-feedback.md and read by the next agent spawn. Two distinct code paths use this, both via the same flag:

Pause reason	Who reads the feedback
Pre-loop review blocked	The architect on the next pre-loop spawn (re-review mode if applicable).
Any in-loop pause (cadence, anomaly, stalled, dev/judge user_input_needed, reflection recommend_stop)	The dev agent at the start of the next iteration; carried through to that iteration's `cfcf-docs/user-feedback.md`.

In both cases cfcf clears state.userFeedback once the consuming agent has been spawned, so later iterations don't silently inherit stale guidance.

Pre-loop review resume tips:

Fastest path: edit problem-pack/problem.md (and success.md if needed) to close the gaps the architect listed as pendingQuestions, then cfcf resume --workspace <name> with no feedback. The architect re-reads the source.
Faster-still path for tiny clarifications: skip the edit and pass --feedback "...". The architect sees your text in user-feedback.md on the next spawn.
Status peek: cfcf status --workspace <name> prints the current pendingQuestions so you can see exactly what the architect asked before you type your answer.

`cfcf document`

Run the Documenter agent to produce polished final workspace documentation. This runs automatically when the loop completes with SUCCESS, but you can also invoke it manually at any time.

cfcf document --workspace my-project

The documenter reads the entire codebase and produces:

docs/architecture.md — system architecture overview
docs/api-reference.md — API documentation (if applicable)
docs/setup-guide.md — setup and usage guide
docs/README.md — workspace overview and quick start

Re-run anytime to regenerate documentation after changes.

`cfcf reflect`

Run the Reflection agent ad-hoc against the current state of a workspace. Outside the iteration loop; does NOT modify loop-state.json and does NOT write an iteration-log (no iteration happened). Useful for a strategic health-check between loop runs, or after editing the Problem Pack and before kicking off the next cfcf run.

cfcf reflect --workspace my-project
cfcf reflect --workspace my-project --prompt "focus on the auth-layer drift"

What the reflection agent does:

Reads the full cross-iteration history: decision-log.md, all iteration-logs/iteration-*.md, all prior iteration-reviews/*.md, any prior reflection-reviews/*.md, a compact per-iteration-branch git log assembled by cfcf, and the tail (~500 lines) of the most recent dev log.
Classifies iteration health (converging | stable | stalled | diverging | inconclusive) with reasoning.
Optionally rewrites the pending portion of cfcf-docs/plan.md. Completed items and iteration headers are protected: any destructive rewrite is auto-reverted and logged.
May set recommend_stop: true to escalate to the user -- during a loop this pauses it; ad-hoc it just shows up in architect-review-style output.
Appends a decision-log.md entry (category strategy) summarising what changed and why.

Results:

cfcf-docs/reflection-analysis.md -- human-readable cross-iteration analysis
cfcf-docs/cfcf-reflection-signals.json -- parsed signals for cfcf + UI
Optional: non-destructive edits to cfcf-docs/plan.md
Entry in cfcf-docs/decision-log.md

Web parity: POST /api/workspaces/:id/reflect (see docs/api/server-api.md).

`cfcf stop`

Stop a running or paused iteration loop.

cfcf stop --workspace my-project

The iteration branch is preserved. You can review the code, then restart with cfcf run.

Maintenance commands

`cfcf self-update`

Upgrade cf² to the latest (or a specific) version. Runs the same install pathway as the curl-based installer; the ~/.cfcf/ data dir (Clio DB, logs, embedder models) is never touched.

cfcf self-update                             # check + interactive upgrade (npm)
cfcf self-update --check                     # check only; print latest vs current
cfcf self-update --yes                       # non-interactive (use in CI)
cfcf self-update --version v0.17.0           # install a specific tag
cfcf self-update --source tarball            # GitHub Releases mirror
cfcf self-update --base-url file:///tmp/dist # any HTTP / file:// mirror

See installing.md for the full upgrade story (env-var equivalents, atomicity, etc.).

`cfcf doctor`

Health-check your install: PATH, Bun version, native packages, agent CLIs, Clio DB, embedder, shell tab-completion, server reachability. Use after install/upgrade or when something feels off.

cfcf doctor                                  # human-readable report
cfcf doctor --json                           # machine-readable (CI / scripts)

Each check prints OK / WARN / FAIL with a short diagnosis + suggested fix when applicable. The check count grows over time as we add new diagnostics.

`cfcf help`

Print user-facing documentation, or launch the interactive Help Assistant (cf² support agent).

cfcf help                                    # topic hub (table of contents)
cfcf help <topic>                            # print that topic to stdout
cfcf help --full                             # print the full user manual (~280 lines)
cfcf help assistant                          # launch the Help Assistant TUI
cfcf help assistant --workspace my-project   # include workspace state in the prompt
cfcf help assistant --print-prompt           # debug: print system prompt + exit

The Help Assistant is one of the two interactive agent roles (alongside the Product Architect). It has the full cf² docs in its system prompt and can read your Clio memory + run diagnostics. Read-only by default — it asks before mutating anything.

Clio — cross-workspace memory

Clio is cf²'s persistent memory layer (~/.cfcf/clio.db, shared across all workspaces, scoped by named Clio Project). See Clio quickstart for the conceptual walkthrough; this section is the verb-by-verb reference.

The verb structure follows a single mechanical rule (see docs/research/cli-verb-normalisation.md): collection-wide / Clio-wide / headline operations stay top-level (search, audit, reindex, stats); operations that act on a noun-instance live under that noun's namespace (docs, metadata, projects, embedder).

cfcf memory is a top-level alias for cfcf clio — cfcf memory search "..." works identically.

`cfcf clio search`

Search Clio for documents matching <query>. Doc-level dedup by default (one row per matching document, Cerefox parity).

cfcf clio search "<query…>" \
    [--project <name>]                    # scope to one Clio Project
    [--mode fts|hybrid|semantic]          # default: auto (hybrid if embedder active, else fts)
    [--alpha 0.7]                         # hybrid blend weight; α × cosine + (1−α) × normalised_BM25
    [--min-score 0.5]                     # min cosine for vector-only candidates
    [--small-doc-threshold 20000]         # docs ≤ N chars return FULL content per hit
    [--context-window 1]                  # large-doc path: chunks per side around the matched chunk
    [--match-count 5]                     # max hits (default 5 doc-level; 10 with --by-chunk)
    [--metadata '{"role":"reflection"}']  # exact-match metadata filter
    [--by-chunk]                          # raw view: one row per matching CHUNK (not doc-level)
    [--json]

The mode resolves in this order: explicit --mode > clio.defaultSearchMode global config > auto. Per-call --alpha, --small-doc-threshold, --context-window override the corresponding clio.* config keys.

`cfcf clio audit`

Query the Clio audit log (newest first). Mutation events only (reads aren't logged — would dwarf real activity).

cfcf clio audit \
    [--event-type create|update-content|edit-metadata|delete|restore|migrate-project] \
    [--actor <name>]
    [--project <p>]
    [--document-id <id>]
    [--since <iso>]                       # e.g. 2026-04-01T00:00:00Z
    [--limit 100]
    [--json]

`cfcf clio reindex`

Re-embed chunks under the currently-active embedder. Prompts y/N with the impact summary before running. Idempotent: skips chunks already matching the active embedder.

cfcf clio reindex [--project <name>] [--force] [--batch-size 32] [-y|--yes] [--json]

Pair with cfcf clio embedder set <name> --reindex for the canonical embedder-switch flow.

`cfcf clio stats`

DB size, doc + chunk counts, applied migrations, active embedder.

cfcf clio stats [--json]

`cfcf clio docs` — document operations

Default action (no subcommand) is list. cfcf clio doc is not an alias — only the plural form is canonical.

`cfcf clio docs list`

cfcf clio docs list \
    [--project <name>]
    [--limit 50] [--offset 0]
    [--include-deleted]                   # include soft-deleted alongside live
    [--deleted-only]                      # trash-bin view (mutually exclusive with --include-deleted)
    [--json]

`cfcf clio docs ingest`

Ingest a Markdown doc into Clio. Either pass a file path or pipe via --stdin.

# Default: cfcf detects the workspace at $PWD and routes to its
# effective Clio Project (item 6.9). No --project needed when you're
# inside a registered workspace's repo.
cfcf clio docs ingest <file> --title "..."

# Explicit project (any of: shared user-named project, cf-system-*, etc.):
cfcf clio docs ingest <file> --project <name> --title "..." \
    [--artifact-type design-guideline] [--tier semantic] [--tags a,b,c] \
    [--author <name>] [--metadata '{...}'] [--source <free-text>]
cat note.md | cfcf clio docs ingest --stdin --project <name> --title "..."

# Update an existing doc instead of creating a new one:
cfcf clio docs ingest notes.md --project <name> --title "Note" --update-if-exists
cfcf clio docs ingest notes.md --project <name> --document-id <uuid>

Default-project resolution (when --project is omitted, item 6.9 follow-up):

cfcf hits GET /api/workspaces and looks for a workspace whose repoPath (realpath-resolved) matches $PWD.
Match found → routes to that workspace's effective Clio Project (workspace.clioProject if set, otherwise cf-workspace-<id>). cfcf prints [clio] auto-routing ingest to <project> (workspace <name> at $PWD) to stderr.
No match → falls back to cf-system-default with a stderr note explaining what happened. Pass --project explicitly if the fallback isn't right.

Agents always pass --project explicitly per the role templates (the prompt-assembler substitutes the workspace's effective project into every CLI example). The auto-routing default exists for human free-form ingests.

--update-if-exists matches by title within the same Project; --document-id <uuid> is the deterministic path. When both are passed, --document-id wins. Updates snapshot the prior content into a version row — recall via cfcf clio docs get <id> --version-id <uuid>.

When --document-id is set, --title becomes optional — if omitted, the existing doc's title is preserved (5.11 follow-up).

`cfcf clio docs get`

Reconstruct full document content from chunks. Defaults to the live (current) version.

cfcf clio docs get <document-id> \
    [--version-id <uuid>]                 # retrieve an archived version (UUIDs from `cfcf clio docs versions`)
    [--raw]                               # print only the content (no metadata header) -- useful in pipes
    [--json]

`cfcf clio docs edit`

Metadata-only edit. Mutate title / author / Clio Project / metadata WITHOUT re-ingesting content. No version snapshot is taken (versions protect chunks; metadata edits don't touch chunks). One edit-metadata audit row per non-empty edit, carrying a before/after diff.

cfcf clio docs edit <document-id> \
    [--title "..."]                       # rename
    [--author "..."]                      # set/clear author (empty string clears to 'agent')
    [--project <name>]                    # move to a different Clio Project (by name or UUID)
    [--set-meta key=value ...]            # incremental metadata add/overwrite (repeatable)
    [--unset-meta key ...]                # incremental metadata removal (repeatable)
    [--actor <name>]                      # audit-log attribution (defaults to 'agent')
    [--json]

Examples:

cfcf clio docs edit 8a3f… --title "Decisions log (renamed)"
cfcf clio docs edit 8a3f… --project cfcf
cfcf clio docs edit 8a3f… --set-meta reviewed_by=fotis --set-meta status=approved --unset-meta draft

`cfcf clio docs delete`

Soft-delete. Sets deleted_at; the doc, its chunks, and its versions remain in the DB. Idempotent.

cfcf clio docs delete <document-id> [--author <name>]

`cfcf clio docs restore`

Undo a soft-delete. Idempotent: restoring an already-live doc returns restored=false.

cfcf clio docs restore <document-id> [--author <name>]

`cfcf clio docs versions`

List archived versions for a document, newest first.

cfcf clio docs versions <document-id> [--json]

`cfcf clio metadata` — metadata-scoped operations

No default subcommand: cfcf clio metadata prints help.

`cfcf clio metadata search`

Find documents by metadata-only filter (no FTS query). Top-level scalar matches.

cfcf clio metadata search \
    --filter '{"role":"reflection"}' \
    [--updated-since 2026-04-01T00:00:00Z] \
    [--project <name>] [--include-deleted] \
    [--match-count 50] [--json]

`cfcf clio metadata keys`

Discovery: list every top-level metadata key currently in the corpus, with sample values. Most-used keys first.

cfcf clio metadata keys [--project <name>] [--json]

`cfcf clio projects` — Clio Project management

Default action is list.

cfcf clio projects [--json]                              # list (default)
cfcf clio projects list [--json]                         # explicit
cfcf clio projects create <name> [--description "..."]   # create
cfcf clio projects show <name-or-id>                     # show one

`cfcf clio embedder` — embedder management

Singular noun (only one embedder is active at a time). Default cfcf init-installed embedder is nomic-embed-text-v1.5 (q8, 768-d, 8k-token context).

cfcf clio embedder list                                  # catalogue with active marker
cfcf clio embedder active                                # current active embedder
cfcf clio embedder install                               # uses clio.preferredEmbedder from config
cfcf clio embedder install nomic-embed-text-v1.5         # explicit name
cfcf clio embedder set <name>                            # interactive: prompts y/N with impact summary
cfcf clio embedder set <name> --reindex                  # safe switch: re-embeds existing chunks under the new model
cfcf clio embedder set <name> --force                    # recovery only (no checks); degrades vector search until reindex
cfcf clio embedder set <name> -y                         # non-TTY-friendly (skip prompt)

The interactive prompt summarises three signals before you confirm: how many chunks already carry an embedding (will become inconsistent), how many exceed the new embedder's recommendedChunkMaxChars ceiling (truncation risk), and whether your clio.maxChunkChars config exceeds that ceiling (will be capped).

Workspace ↔ Clio Project assignment

By default each workspace gets its own cf-workspace-<id> Clio Project at registration time, so memory stays per-workspace unless you opt in to sharing. Pass --project <name> only when you want this workspace to pool memory with sibling workspaces under a named shared Project (e.g. backend-services for a family of TS API repos).

# At init time — default (per-workspace `cf-workspace-<id>` auto-created):
cfcf workspace init --repo <path> --name <name>

# Interactive prompt — pick from existing shared Projects, name a new one, or skip
# (TTY only; suppressed by --no-prompt):
cfcf workspace init --repo <path> --name <name>

# Opt into sharing — pool with sibling workspaces under a named Project:
cfcf workspace init --repo <path> --name <name> --project <shared-project>

# Later — re-point to a different Project:
cfcf workspace set <name> --project <new-clio-project>                      # future ingests only
cfcf workspace set <name> --project <new-clio-project> --migrate-history    # rekey historical docs too

cf-workspace-* and cf-system-* are reserved namespaces (cfcf-managed). The CLI + web pickers filter them out so you can't accidentally pin a workspace to another workspace's bucket or to a system project.

Shell completion

Tab completion is auto-installed on every cfcf install/upgrade — you should rarely need to run these commands by hand.

`cfcf completion install`

Auto-install completion for the detected shell. Writes the completion script to a canonical path AND appends a sentinel-marked block to your ~/.zshrc or ~/.bashrc.

cfcf completion install                  # auto-install for $SHELL (bash or zsh)
cfcf completion install --no-rc-edit     # write the script but DON'T touch your rc file
cfcf completion install --print-only     # print manual setup instructions instead of writing

The rc-file edit is sentinel-marked:

# >>> cfcf shell completion (managed by `cfcf completion install`) >>>
# Auto-added on cfcf install/upgrade. Delete this block (begin to end markers)
# to opt out; cfcf only modifies content between the >>> and <<< sentinels.
fpath=(~/.zsh/completions $fpath)
autoload -U compinit && compinit
# <<< cfcf shell completion <<<

cfcf only modifies content between the markers. The rest of your rc file is byte-for-byte preserved across updates.

Manual-setup detection. If you already have your own fpath=(~/.zsh/completions ...) line outside our sentinels, cfcf leaves your rc alone (skipped-manual action) — we don't fight users who wired it up themselves.

`cfcf completion uninstall`

Symmetric: removes the rc block AND the completion script. Idempotent.

cfcf completion uninstall

`cfcf completion bash` / `cfcf completion zsh`

Emit the raw completion script to stdout (for advanced users who want to redirect manually).

cfcf completion bash > ~/.cfcf-completion.bash
cfcf completion zsh  > ~/.zsh/completions/_cfcf

Auto-install paths

Install path	Auto-runs `cfcf completion install`?
`scripts/install.sh` (curl-based)	✓ explicit call after `npm install -g --prefix ~/.bun`
`cfcf self-update`	✓ spawns the new binary post-upgrade
`npm install -g --prefix ~/.bun @cerefox/codefactory` (manual npm path)	✓ `postinstall` hook in the published `package.json`
`bun install -g @cerefox/codefactory` (Bun-only alternative)	✗ Bun blocks postinstalls by default — run `cfcf completion install` manually after `bun pm -g trust …`

Supported shells + platforms

	bash	zsh	fish	PowerShell
macOS	✓	✓	not supported	n/a
Linux	✓	✓	not supported	n/a
Windows	not supported (cfcf doesn't ship for native Windows; use WSL)

If your shell isn't recognised, cfcf completion install is a no-op + emits a hint. fish completion is tracked as a future addition.

Diagnostics

cfcf doctor includes a "Shell tab completion" check that verifies the script exists at the canonical path AND your rc file references it. See troubleshooting.md if tab doesn't fire.

Configuration Storage

cfcf stores configuration in the platform-standard directory:

Platform	Location
macOS	`~/Library/Application Support/cfcf/`
Linux	`~/.config/cfcf/`
Windows	`%APPDATA%/cfcf/`

Override with CFCF_CONFIG_DIR environment variable.

Directory structure:

cfcf config dir/
  config.json               # Global config (from cfcf init)
  server.pid                # Server PID file (when running)
  workspaces/
    my-workspace-a1b2c3/
      config.json           # Workspace-specific config
      loop-state.json       # Current loop run state (phase, iterations, etc.)
      history.json          # Persistent history of all agent runs (reviews, iterations, documents)

Log storage:

Agent output logs are stored separately (they can be large):

~/.cfcf/
  logs/
    my-project-a1b2c3/
      iteration-001-dev.log       # Dev agent log per iteration
      iteration-001-judge.log     # Judge agent log per iteration
      reflection-001.log          # Nth reflection run (loop or ad-hoc)
      architect-001.log           # Nth architect review
      documenter-001.log          # Nth documenter run
      notifications.log           # JSON Lines audit trail of notifications

Each architect / documenter / reflection invocation gets its own sequence-numbered log so re-running preserves history.

Override with CFCF_LOGS_DIR environment variable.

Notifications

cfcf can ping you at key moments during long-running unattended loops so you can walk away and get notified only when needed. This is the "dark factory" operating mode.

Events

loop.paused — Loop pauses because of the review cadence, agent questions, an anomaly, or reaching max iterations
loop.completed — Loop reaches a terminal state (success, failure, stopped, max iterations)
agent.failed — An agent process exits with non-zero status and no signals (e.g., judge config was wrong)

Channels

Channel	What it does	Platforms
`terminal-bell`	Writes the ASCII BEL character (`\a`) to server stderr — most terminals beep or flash	all
`macos`	Native macOS Notification Center entry via `osascript`	macOS only
`linux`	Native Linux desktop notification via `notify-send` (part of libnotify)	Linux only
`log`	Appends a JSON Lines entry to `~/.cfcf/logs/<workspace>/notifications.log` — always-on audit trail	all

Configuration

Configured via cfcf init or by editing the global config file directly:

{
  "notifications": {
    "enabled": true,
    "events": {
      "loop.paused": ["terminal-bell", "macos", "log"],
      "loop.completed": ["terminal-bell", "macos", "log"],
      "agent.failed": ["terminal-bell", "macos", "log"]
    }
  }
}

Set enabled: false to disable all notifications. Remove channels from a specific event's array to silence that event. Workspace config can override the global default.

Notes

macOS notifications require Terminal.app (or the calling terminal) to have notification permission in System Settings → Notifications. First use may silently fail if permission has never been granted.
Dispatch is fire-and-forget with a 5-second per-channel timeout. A slow or failing channel never blocks the loop or other channels.
No rate limiting in v1 — if you set pauseEvery: 1, you'll get a notification on every iteration.

Environment Variables

Variable	Default	Description
`CFCF_PORT`	`7233`	Server port
`CFCF_CONFIG_DIR`	(platform-specific)	Config directory override
`CFCF_LOGS_DIR`	`~/.cfcf/logs`	Log directory override

Typical Workflow

# One-time setup
cfcf init                                          # Configure agents and defaults
cfcf server start                                  # Start the server

# Per-workspace setup + Problem Pack -- two paths:

# Path A (recommended): interactive Product Architect drives both
cd /path/to/repo
cfcf spec
# PA introduces itself, offers to run `git init` if needed, drives
# `cfcf workspace init` (eliciting workspace name in conversation),
# then helps draft + iterate problem-pack/* with you.

# Path B: do it manually
cfcf workspace init --repo /path/to/repo --name my-app
# Edit problem-pack/problem.md, problem-pack/success.md, etc. yourself

# Architect review (recommended before unattended development)
cfcf review --workspace my-app                       # Architect identifies gaps
# Read cfcf-docs/architect-review.md, refine problem-pack/
cfcf review --workspace my-app                       # Re-review after refinements
                                                    # (re-review-aware on existing workspaces)

# Start the dark factory loop
cfcf run --workspace my-app
# cfcf runs: dev → judge → reflect (unless judge opts out) → decide → repeat
# Three separate commits per iteration: dev / judge / reflect
# On SUCCESS: documenter runs automatically to produce final docs
# On pause: review and provide feedback
cfcf resume --workspace my-app --feedback "Focus on X"

# Ad-hoc strategic health-check (no iteration)
cfcf reflect --workspace my-app
cfcf reflect --workspace my-app --prompt "focus on auth-layer drift"

# Monitor progress anytime
cfcf status --workspace my-app

# Stop if needed
cfcf stop --workspace my-app

FilesExpand file tree

cli-usage.md

Latest commit

History

cli-usage.md

File metadata and controls

cf² CLI Usage Guide

Prerequisites

First-Time Setup

cfcf init

Server Management

cfcf server start

cfcf server stop

cfcf server status

cfcf server reap (item 6.31, v0.21.0)

Global Configuration

cfcf config show

cfcf config edit

Quick Status

cfcf status

Workspace Management

cfcf workspace init

cfcf workspace list

cfcf workspace show

cfcf workspace delete

Product Architect (interactive Problem Pack authoring)

cfcf spec [task...]

Solution Architect Review

cfcf review

First-run vs re-review mode (v0.7.0+)

Running Iterations

cfcf run -- Dark Factory Loop

cfcf run -- Manual Mode