npm package: @fluxloop_ai/cli
Description: Local-first CLI for skill regression prevention
Latest version: 0.0.12

# FluxLoop CLI

Local-first CLI for skill regression prevention.

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

```bash
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](/Users/user/Documents/fluxloop_reg/docs/manual/fluxloop_v1_usage_manual.md)

Related manuals:

- [Scenario YAML Manual](/Users/user/Documents/fluxloop_reg/docs/manual/fluxloop_cli_simulation_yaml_manual.md)
- [Replay Post-Processing Manual](/Users/user/Documents/fluxloop_reg/docs/manual/fluxloop_replay_post_processing_manual.md)
- [User Simulator Prompt Manual](/Users/user/Documents/fluxloop_reg/docs/manual/user_simulator_prompt.md)
- [v1.7 Skill Author Update Guide](/Users/user/Documents/fluxloop_reg/docs/manual/fluxloop_v1_7_skill_author_update.md)

## 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 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:

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

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

Day-to-day loop:

```bash
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

```text
.fluxloop/
  state/
    project.json
    context.json
    context.md
  sessions/
    discovered-sessions.json
  skill-workdirs/
    <skill-id>/
      skill.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.

## 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

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

## License

Apache-2.0