# CLI Reference

The `npx @45ck/prompt-language` CLI manages plugin installation and provides development utilities.

## Flags

### --help

Print usage and available commands.

```bash
npx @45ck/prompt-language --help
```

### --version

Print the installed plugin version.

```bash
npx @45ck/prompt-language --version
# prompt-language v0.3.0
```

## Commands

## Harness Environment Toggles

These env vars control host-facing prompt adaptation. They do not add new DSL primitives.

- `PROMPT_LANGUAGE_META_PROMPT`
  Controls NL-to-DSL confirmation/meta-prompting for supported interactive hooks.
- `PROMPT_LANGUAGE_CLAUDE_META_PROMPT`
  Overrides `PROMPT_LANGUAGE_META_PROMPT` for the Claude hook.
- `PROMPT_LANGUAGE_CODEX_META_PROMPT`
  Overrides `PROMPT_LANGUAGE_META_PROMPT` for the Codex hook.
- `PROMPT_LANGUAGE_SKILL_PROMPT_WRAPPER`
  Controls the skill-aware prompt wrapper used by prompt-turn runners.
- `PROMPT_LANGUAGE_CLAUDE_SKILL_PROMPT_WRAPPER`
  Overrides the skill-aware wrapper for Claude prompt turns.
- `PROMPT_LANGUAGE_CODEX_SKILL_PROMPT_WRAPPER`
  Overrides the skill-aware wrapper for Codex prompt turns.

Accepted true values: `1`, `true`, `on`

Accepted false values: `0`, `false`, `off`

Defaults:

1. NL meta-prompting is on by default for supported hooks.
2. Skill-aware prompt wrapping is on by default for Claude/Codex prompt turns.
3. Harness-specific vars override the global var for that harness.

### install (default)

Install the plugin into Claude Code. This is the default command — running `npx @45ck/prompt-language` without arguments does the same thing.

```bash
npx @45ck/prompt-language
npx @45ck/prompt-language install
```

What it does:

1. Copies plugin files (dist, hooks, skills, commands, agents, `.claude-plugin`, bin) to `~/.claude/plugins/cache/prompt-language-local/prompt-language/<version>/`
2. Generates a marketplace catalog (`marketplace.json`)
3. Registers the marketplace in Claude Code settings
4. Enables the plugin
5. Configures the status line (if not already configured)

### codex-install

Install the experimental Codex scaffold into the local Codex plugin/cache directories.

```bash
npx @45ck/prompt-language codex-install
```

What it does:

1. Copies the Codex-facing runtime assets (`dist`, `.codex-plugin`, `.codex`, `.agents`, `skills`, `agents`, `bin`) into the local Codex cache
2. Registers and enables the scaffold in Codex plugin settings
3. Writes or updates `~/.codex/config.toml` with a prompt-language-managed `codex_hooks = true` entry, while leaving user-owned entries unchanged

Important:

- this is an **experimental local scaffold**, not a claim of full Claude hook parity
- the shipped Codex story today is still the supervised headless runner used by `run`, `ci`, and `eval`

### status

Check whether the plugin is installed and configured correctly.

```bash
npx @45ck/prompt-language status
```

Example output:

```
prompt-language v0.3.0
  Installed:    yes (~/.claude/plugins/cache/prompt-language-local/prompt-language/0.3.0)
  Registered:   yes
  Marketplace:  yes
  Enabled:      yes
```

### codex-status

Check whether the local Codex scaffold is installed and whether `codex_hooks` is enabled.

```bash
npx @45ck/prompt-language codex-status
```

Example output:

```
prompt-language Codex scaffold v0.3.0
  Installed:    yes
  Registered:   yes
  Marketplace:  yes
  Enabled:      yes
  codex_hooks:  yes (managed)
```

### uninstall

Remove the plugin from Claude Code.

```bash
npx @45ck/prompt-language uninstall
```

Removes plugin files, marketplace registration, and settings entries. Also removes the status line configuration if it was set by the plugin.

### codex-uninstall

Remove the local Codex scaffold and clean up Codex plugin settings.

```bash
npx @45ck/prompt-language codex-uninstall
```

### init

Scaffold a starter flow in the current directory.

```bash
npx @45ck/prompt-language init
```

What it does:

1. Creates `.prompt-language/` directory with `.gitignore` (excludes session state files)
2. Creates `.prompt-language/vars/` directory for variable capture
3. Detects project type from `package.json` scripts
4. Generates `example.flow` with appropriate gates (`tests_pass`, `lint_pass`) based on available scripts

Run the generated flow:

```bash
claude -p "$(cat example.flow)"
```

### render-workflow

Render the lowered `.flow` text for a canonical workflow alias.

```bash
npx @45ck/prompt-language render-workflow clarify
npx @45ck/prompt-language render-workflow clarify | npx @45ck/prompt-language validate
```

Notes:

1. This is a convenience layer, not a second runtime.
2. The command prints ordinary prompt-language flow text so the lowered artifact stays inspectable before execution.
3. The first shipped alias is `clarify`.
4. The shipped `clarify` alias is preview-safe and read-only; it does not imply file writes or command execution.

### run

Execute a `.flow` file or inline flow text through Claude or a supported headless runner.

```bash
npx @45ck/prompt-language run --file my.flow
npx @45ck/prompt-language run my.flow
cat my.flow | npx @45ck/prompt-language run
npx @45ck/prompt-language run --runner codex my.flow
npx @45ck/prompt-language run --runner codex --json my.flow
npx @45ck/prompt-language run --runner opencode --model opencode/gpt-5-nano my.flow
```

Notes:

1. `--runner claude` is the default.
2. All shipped runners (`claude`, `codex`, `opencode`, `ollama`, `aider`) execute through the prompt-language headless runtime rather than bypassing flow semantics with a raw prompt handoff.
3. When `--runner codex` is selected without an explicit `--model`, prompt-language defaults to `gpt-5.2` on this workstation because the ambient Codex default may fall back to a rate-limited Spark profile.
4. OpenCode models use the `provider/model` form, for example `opencode/gpt-5-nano`.
5. Before execution starts, `run` performs shared preflight for runner availability and built-in gate prerequisites. A blocked preflight exits with code `2`.
6. On this workstation, prefer hosted harness models for headless runner paths; do not install local models here just to exercise `run`.
7. As of April 18, 2026, the checked-in factory-runtime evidence packs pin Claude and Codex lanes to medium reasoning effort via `PROMPT_LANGUAGE_CLAUDE_EFFORT` and `PROMPT_LANGUAGE_CODEX_REASONING_EFFORT` unless the caller overrides them. Treat that as an evaluation configuration of record, not as a product guarantee or universal recommendation.
8. As of April 10, 2026, `opencode/gpt-5-nano` passed smoke test `A` through the same OpenCode headless path, which confirms the runner surface can work when the model is tool-capable.
9. The bounded Gemma comparison remains documented in [OpenCode Gemma 4 Plan](../evaluation/opencode-gemma-plan.md); it is an evaluation note, not the default setup path.
10. `run --json` emits `{ status, diagnostics, outcomes, reason? }` for all shipped runners and uses explicit exit codes: `0` success, `1` terminal unsuccessful outcome, `2` blocked/profile-incompatible execution, `3` failed execution.
11. Codex support in `run` is the supervised headless path. The separate `codex-install` scaffold is experimental and should not be read as full native-lifecycle parity with Claude.
12. The skill-aware prompt wrapper used by Claude/Codex prompt turns can be disabled globally or per harness with the env vars listed above. This changes prompt envelope behavior, not flow semantics.

### ci

Run a flow in headless mode for CI or automation.

```bash
npx @45ck/prompt-language ci --file my.flow
npx @45ck/prompt-language ci --runner codex my.flow
npx @45ck/prompt-language ci --runner codex --json my.flow
npx @45ck/prompt-language ci --runner opencode --model opencode/gpt-5-nano my.flow
```

This is the same headless runner path used by `run --runner claude|codex|opencode|ollama|aider`, so prompt quality and tool-use behavior depend on the selected model. On this workstation, `ci --runner codex` defaults to `gpt-5.2` when `--model` is omitted.

As of April 18, 2026, the checked-in factory-runtime evidence packs also pin Claude and Codex lanes to medium reasoning effort via `PROMPT_LANGUAGE_CLAUDE_EFFORT` and `PROMPT_LANGUAGE_CODEX_REASONING_EFFORT` unless the caller overrides them. That is the documented experiment default used for captured evidence, not a promise that medium is always the best setting.

`ci` also runs the shared execution preflight before starting the runner. A blocked preflight exits with code `2` instead of attempting execution.

`ci --json` follows the same headless-report contract as `run --json`: `{ status, diagnostics, outcomes, reason? }` with exit codes `0`, `1`, `2`, and `3` for success, unsuccessful, blocked, and failed execution respectively.

The same per-harness skill-wrapper env vars apply to Claude/Codex prompt turns reached through `ci`.

### eval

Run a checked-in JSONL eval dataset and emit a machine-readable report.

```bash
npx @45ck/prompt-language eval --dataset experiments/eval/datasets/e1-repeated-failures.jsonl
npx @45ck/prompt-language eval --harness codex --candidate vanilla --output experiments/results/e1-repeated-failure/v1/codex-vanilla.json --dataset experiments/eval/datasets/e1-repeated-failures.jsonl
npx @45ck/prompt-language eval --harness codex --candidate gated --baseline experiments/results/e1-repeated-failure/v1/codex-vanilla.json --output experiments/results/e1-repeated-failure/v1/codex-gated.json --dataset experiments/eval/datasets/e1-repeated-failures.jsonl
```

Notes:

1. `--candidate vanilla` runs the checked-in prompt or flow exactly as written.
2. `--candidate gated` wraps prompt cases as a one-step flow and appends the dataset case's `gates` as real `done when:` checks.
3. `--harness` accepts `claude`, `codex`, or `opencode`.
4. `--baseline` points at a locked JSON report to compare against. `--baseline-report` remains an alias.
5. `--out` is accepted as a short alias for `--output`.
6. Codex-backed eval runs default to `gpt-5.2` when no `--model` is provided.
7. `--baseline` must point at a locked report for the same dataset bank; the runner rejects mismatched datasets and case sets.
8. If you do not pass `--output`, the CLI writes a timestamped report under `.prompt-language/eval-reports/`.
9. The seeded dataset bank and locked-results layout are documented in [Dataset Bank](../evaluation/dataset-bank.md).
10. On this workstation, use hosted harnesses for this command; do not install local models just to populate eval artifacts.

### list

Recursively list `.flow` files under the current directory.

```bash
npx @45ck/prompt-language list
```

### validate

Parse, lint, score, and render a flow without executing it.

```bash
npx @45ck/prompt-language validate --file my.flow
npx @45ck/prompt-language validate my.flow
cat my.flow | npx @45ck/prompt-language validate
npx @45ck/prompt-language validate --runner codex --json --file my.flow
npx @45ck/prompt-language validate --runner claude --mode interactive --json --file my.flow
```

Notes:

1. Plain `validate` remains parse/lint/render only.
2. `validate --runner ...` adds execution preflight for runner availability and built-in gate prerequisites without starting execution.
3. `validate --runner ... --mode interactive|headless` adds static profile-compatibility checks without starting execution.
4. The shipped compatibility blockers are currently: unsupported runner/mode combinations, `approve` in headless mode, and `send` / `receive` when validating Claude profiles without message passing.
5. Supported headless runtime profiles currently preserve `ask` / capture and `spawn` / `await` semantics for `claude`, `codex`, `opencode`, and `ollama`.
6. Headless profiles also surface warning-only UX diagnostics for interactive-only affordances such as the status line and watch mode.
7. `validate --json` emits `{ status, diagnostics, outcomes }` plus complexity and rendered flow metadata.
8. A blocked preflight exits with code `2`.
9. `validate` remains preflight-only, so it never emits the `unsuccessful` or `failed` execution statuses used by headless `run` / `ci`.

### demo

Print an annotated example flow to stdout.

```bash
npx @45ck/prompt-language demo
```

Shows a complete flow with comments explaining each section — useful as a quick syntax reference.

### statusline

Configure the Claude Code status line to show flow progress.

```bash
npx @45ck/prompt-language statusline
```

Sets up `~/.claude/settings.json` to run the status line script, which displays current flow status, active node, loop progress, and gate results in Claude Code's footer.

### watch

Launch a live TUI monitor that displays flow execution in real time.

```bash
npx @45ck/prompt-language watch
```

Shows a continuously-updating view of the flow state, including the current node, variable values, and gate status. Useful for watching long-running flows.

## Slash commands

These are available inside Claude Code sessions when the plugin is installed:

| Command          | Description                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------ |
| `/fix-and-test`  | Retry loop: fix failing tests, re-run, repeat up to 5 times. Gate: `tests_pass`                  |
| `/tdd`           | Red-green-refactor cycle. Gate: `tests_pass` + `lint_pass`                                       |
| `/refactor`      | Incremental refactoring with test verification. Gate: `tests_pass` + `lint_pass`                 |
| `/deploy-check`  | Lint, test, build pipeline. Gate: `tests_pass` + `lint_pass` + `file_exists`                     |
| `/flow:status`   | Show current flow state, active node, and gate results                                           |
| `/flow:reset`    | Reset flow and clear all session state                                                           |
| `/flow-validate` | Validate flow syntax: run `lintFlow` and show complexity score without executing                 |
| `/flow-audit`    | Query `.prompt-language/audit.jsonl` — supports `--failures`, `--slow`, `--type`                 |
| `/flow-vars`     | Inspect all session variables with full values, types, and list expansion                        |
| `/flow-eval`     | Evaluate a condition against session variables with intermediate trace + missing-variable errors |
