FluxLoop CLI

Local-first CLI for skill regression prevention.

Run FluxLoop from the target project root, not from the FluxLoop source tree itself.

cd /path/to/your-project
pnpm add -D @fluxloop_ai/cli
pnpm exec fluxloop --help

The cli/ directory in this repository is only for developing FluxLoop itself.

Full user manual: docs/manual/fluxloop_v1_usage_manual.md

Related manuals:

• Skill Lifecycle Manual
• Scenario YAML Manual
• Replay Post-Processing Manual
• User Simulator Prompt Manual
• v1.7 Skill Author Update Guide

Public Surface

| Command | Purpose | |---------|---------| | fluxloop project init | Bootstrap .fluxloop/state for the resolved project | | fluxloop project env set | Persist workspace-local env vars in .fluxloop/.env | | fluxloop context show | Show canonical context.json state | | fluxloop skills register | Persist target skill metadata under .fluxloop/skill-workdirs/<skill-id>/skill.json | | fluxloop skills analyze | Persist raw FinalSkillAnalysis metadata under .fluxloop/skill-workdirs/<skill-id>/analysis.json | | fluxloop sessions list | Discover recent Claude sessions scoped to the current project | | fluxloop sessions inspect | Inspect a session turn/message map and capture anchors | | fluxloop scenarios scaffold | Generate a canonical RegressionScenario YAML skeleton | | fluxloop scenarios lint | Lint interactive scenario contracts beyond schema shape | | fluxloop capture | Capture a trace seed for trace | | fluxloop replay | Replay a regression scenario and write a scenario-owned experiment suite | | fluxloop diff | Compare experiment roots, suite reports, run directories, or run results |

Release-Ready Happy Path

One-time setup per project:

fluxloop project init
fluxloop project env set ANTHROPIC_API_KEY <value>
fluxloop skills register reporter --install-path .claude/skills/reporter --default
fluxloop skills analyze reporter

skills register는 --source-dir를 함께 주지 않는 한 --install-path가 이미 존재하고 SKILL.md를 포함해야 한다.

Day-to-day loop:

fluxloop sessions list
fluxloop capture --latest --latest-assistant --seed-id login-flow-success
fluxloop scenarios scaffold reporter-login-guard --mode trace --seed .fluxloop/skill-workdirs/reporter/seeds/login-flow-success.yaml
fluxloop scenarios lint .fluxloop/skill-workdirs/reporter/scenarios/reporter-login-guard/scenario.yaml
fluxloop replay .fluxloop/skill-workdirs/reporter/scenarios/reporter-login-guard/scenario.yaml
fluxloop diff --baseline <prior-experiment-root> --latest <latest-experiment-root>

scenarios scaffold --mode trace defaults to compiled_scenario.version: 2 and includes the interactive conversation block. Use --scenario-version 1 only when you explicitly need the legacy single-turn trace contract.

scenarios scaffold --mode new now defaults to compiled_scenario.version: 3, uses launch_prompt, and writes a companion scenario-script.yaml. Use --scenario-version 1 only when you explicitly need the legacy single-turn new contract. --mode new --scenario-version 2 is invalid.

compiled_scenario.version: 3 is the current interactive contract:

• new interactive: mode: new
• trace interactive: mode: trace
• simulator hidden context stays isolated from the agent
• language_code is shared only through new runtime system prompt append

Scaffold output is now intentionally generic: it leaves compiled_scenario.assertions empty and expects the author to fill in the real observable contract.

Use fluxloop sessions inspect <session-id> when you need to inspect turn boundaries or choose a non-latest anchor manually. Use fluxloop replay --strict-scenario-lint <scenario-path> when scenario lint warnings should fail preflight instead of being reported as warnings.

Canonical Local Store

.fluxloop/
  state/
    project.json
    context.json
    context.md
  sessions/
    discovered-sessions.json
  skill-workdirs/
    <skill-id>/
      skill.json
      analysis.json
      seeds/
        <seed-id>.yaml
      scenarios/
        <scenario-id>/
          scenario.yaml
          scenario-script.yaml
          experiments/
            <experiment-id>/
              experiment.json
              source-skill-manifest.json
              suite-report.json
              report.md
              diff-result.json
              diff-report.html
              run-001/
                run-result.json
                response.txt
                transcript.json
                simulator-decisions.json
                artifacts-manifest.json
                artifacts/
                diffs/

context.json is the canonical mutable state. context.md is a generated mirror and is never parsed by the engine.

Context updates:

• scenarios scaffold updates current_scenario_id
• capture updates current_session_id and current_seed_id
• replay updates current_scenario_id, current_skill_id, last_experiment_id, and last_experiment_dir

Output Contract

• Human-readable success and failure output goes to stderr.
• --json writes exactly one machine-readable JSON document to stdout.
• scenarios lint exits 41 when lint errors are present.
• diff exits 0 when comparison succeeds, even if changes are found.
• When replay omits --output-dir, the default suite root is .fluxloop/skill-workdirs/<skill-id>/scenarios/<scenario-id>/experiments/<experiment-id>/.
• replay --strict-scenario-lint upgrades scenario lint warnings to invalid scenario failures before runtime execution.
• When diff omits --output-dir, the default diff-result.json location is the latest experiment root.
• skills analyze persists the raw FinalSkillAnalysis payload to .fluxloop/skill-workdirs/<skill-id>/analysis.json; replay does not consume that file in v1.

v1.7 Boundary

v1.7 is the current usable local-first regression loop:

• project init
• sessions list / sessions inspect
• scenarios scaffold / scenarios lint
• capture --latest / --latest-assistant
• single-turn legacy new and trace (compiled_scenario.version: 1)
• interactive trace (compiled_scenario.version: 2 or 3)
• interactive new (compiled_scenario.version: 3)
• companion scenario-script.yaml asset flow
• scenario-owned experiments, reports, and diffs

Explicitly outside the current boundary:

• generalized runtime-agnostic skill activation
• open-ended conversation product behavior
• GUI-driven replay workflows

Environment Variables

| Variable | Purpose | |----------|---------| | ANTHROPIC_API_KEY | Required for Claude Agent SDK replay; can be stored in .fluxloop/.env |

Replay automatically loads .fluxloop/.env from the resolved project root. You no longer need to prefix commands with unset CLAUDECODE &&; the replay runtime clears that variable for the child Claude SDK process automatically.

Developing

cd cli
pnpm install
pnpm run dev -- --help
pnpm run build
pnpm run test
pnpm run lint

License

Apache-2.0