factory-cli

name	factory-cli
description	Complete reference for the factory CLI — all commands, arguments, options, and usage. Use when an agent needs to invoke factory commands, check correct syntax, or understand available options.

CLI reference for the factory runtime. Provides command syntax, arguments, options, and usage examples for all factory commands. Auto-generated by `factory update-claude-skill` — do not hand-edit.

<quick_start> Most common commands:

factory status Pipeline monitor — what's running, blocked, queued factory run AGENT [SPEC] Dispatch a specific agent factory start Automated dispatch loop until idle or gated factory needs Agent blockers and pending human requests factory decide SPEC Respond to hard decision gates factory advance SPEC Finalize a drafting spec with gathered context factory docs SPEC Update docs after spec completes pipeline factory reflect [AGENT] Agent self-examination pass </quick_start>

Commands map to OS primitives: status = top/htop run = process scheduler start = init dispatch loop needs = dmesg decide = interrupt handler advance = context-aware dispatch rebuild = process restart resolve = manual interrupt clear

Four categories: Operate (pipeline work), Inspect (read-only views), Configure (setup/settings), GC (garbage collection — also runs automatically).

<cli_overview>

Usage: factory [OPTIONS] COMMAND [ARGS]...

  Factory — local runtime for persistent AI agents.

  Operate:
    status          Pipeline monitor — agents, queues, next actions
    start           Automated dispatch loop (runs until idle or gated)
    run AGENT       Invoke a specific agent (heartbeat if no task given)
    advance SPEC    Gather context and finalize a drafting spec
    decide SPEC     Respond to hard decision gates
    needs           Show agent blockers and pending requests
    rebuild TASK    Re-queue failed work with failure report
    resolve TASK    Mark a failed task as resolved without rebuild
    reflect [AGENT] Agent self-examination pass

  Inspect:
    apps            Registered workflow apps and their pipelines
    perms           Unix-style permissions model (groups, modes)
    workspace       Directory tree with status indicators
    logs [AGENT]    Recent run logs
    triage          Manage factory-internal observations
    docs SPEC       Update docs after spec completes pipeline

  Configure:
    init                Create workspace directory structure
    init-project        Register cwd as a factory project (.factory marker)
    backend             Switch between kimi and anthropic backends
    scenario            Manage scenario holdout files for verification
    update-claude-skill Regenerate CLI reference skill from live commands

  GC (also runs automatically after every agent):
    cleanup-specs             Spec pipeline staleness
    cleanup-tasks             tasks/review/ staleness
    cleanup-research          tasks/research/ staleness
    cleanup-planning          tasks/planning/ staleness
    cleanup-factory-internal  Observation lifecycle

Options:
  --help  Show this message and exit.

Commands:
  advance                   Advance a drafting spec with gathered context
  apps                      Registered workflow apps and pipelines
  backend                   Switch all agents between kimi and anthropic
  cleanup-factory-internal  Remove promoted/dismissed observations
  cleanup-planning          Remove stale planning dirs (lifecycle complete)
  cleanup-research          Remove stale research requests (completed)
  cleanup-specs             Remove stale specs (upstream copies)
  cleanup-tasks             Remove stale review tasks (verified/failed)
  decide                    Respond to hard decision gates
  docs                      Update docs after spec completes pipeline
  fire-drill                Validate failure workflow with synthetic data
  init                      Create workspace directory structure
  init-project              Register cwd as a factory project
  logs                      Recent run logs (per-agent or all)
  needs                     Agent blockers and pending human requests
  perms                     Unix-style permissions (groups, modes, escalation)
  rebuild                   Re-queue failed work with failure report
  reflect                   Agent self-examination pass
  resolve                   Mark a failed task as resolved (no rebuild)
  run                       Invoke a specific agent (heartbeat if no task)
  scenario                  Manage verification scenario holdouts
  start                     Automated dispatch loop (downstream-first)
  status                    Pipeline monitor — agents, queues, next actions
  triage                    Manage factory-internal observations
  update-claude-skill       Regenerate CLI reference skill from live commands
  workspace                 Directory tree with item counts

</cli_overview>

<command_reference> Full per-command reference with arguments, options, examples, and exit codes: See references/commands.md </command_reference>

<success_criteria>

• Correct command identified for the agent's intent
• Arguments and options match the command signature
• Exit codes interpreted correctly (0 = success in all commands)
• GC commands not invoked manually unless debugging (they run automatically) </success_criteria>