> ## Documentation Index > Fetch the complete documentation index at: https://docs.refactron.dev/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > Every Refactron command, flag, and exit code. Refactron is a single binary, `refactron`, with two execution modes: * **One-shot:** `refactron [flags]` runs the command and exits. * **Interactive REPL:** `refactron` (no command) drops you into a `❯` prompt that accepts the same verb names. The verbs in this reference work in both modes unless noted otherwise. ## `analyze` ```bash theme={null} refactron analyze [target] [flags] ``` Read-only scan. Detects transform patterns across the project, prints a findings report — one bordered box per file plus TRANSFORMS / BY TRANSFORM / SUMMARY tables — and exits. Never mutates anything. | Flag | Type | Default | Description | | ---------------- | ----------------------- | ------- | ----------------------------------------------------------------------------- | | `--json` | bool | false | Emit findings as JSON to stdout instead of the formatted report. | | `--confidence` | `high \| medium \| low` | `high` | Minimum analyzer confidence to surface. Lower = noisier. | | `--fail-on` | `high \| medium \| low` | none | Exit non-zero if any finding meets or exceeds this confidence. | | `--graph=` | path | none | Also write the analysis report (with import/call graphs) as JSON to ``. | ```bash one-shot theme={null} refactron analyze src/ refactron analyze . --json > report.json refactron analyze . --fail-on high # CI gate ``` ```bash REPL theme={null} ❯ analyze . ❯ analyze src/ ``` **Exit codes:** `0` clean; `1` `--fail-on` matched; `2` flag parse or config error. *** ## `run` ```bash theme={null} refactron run [target] [flags] ``` Plan + verify + (optionally) apply transforms. Without `--apply`, runs as a dry-run and prints a bordered diff box per file. With `--apply`, the three gates run with live progress — gate-by-gate, falling back to per-file verification when the batch fails — and only the files that pass are written atomically. | Flag | Type | Default | Description | | --------------------- | ----------------------- | ----------- | ------------------------------------------------------------------------ | | `--apply` | bool | false | After verification passes, write the changes atomically. | | `--dry-run` | bool | true | Show the diff without writing. Mutually exclusive with `--apply`. | | `--transforms=` | csv or `all` | `all` | Limit to specific [transform IDs](/transforms). | | `--confidence` | `high \| medium \| low` | `high` | Analyzer confidence threshold (overrides `.refactronrc.json`). | | `--test-cmd` | string | auto-detect | Override the test runner used by Gate 3 (overrides `.refactronrc.json`). | | `--diff-context=` | int | 30 | Context lines per file in dry-run output. | | `--files=` | glob | none | Scope the dry-run preview to a subset of planned changes. | | `--json` | bool | false | Emit `{ mode, plan }` as JSON. | ```bash one-shot theme={null} refactron run --dry-run # see what would change refactron run --apply # verify + write refactron run --transforms=var_to_const_let,implicit_any --apply refactron run src/auth/ --apply # scoped to a directory ``` ```bash REPL theme={null} ❯ run # dry-run ❯ run --apply ❯ run --transforms=callback_to_async_await --apply ``` **Exit codes:** `0` plan applied (or dry-run printed); `1` verification failed (gate rejected); `2` flag parse error or missing path. *** ## `document` ```bash theme={null} refactron document [target] [flags] ``` Reads `.refactron/last-apply.json` (the snapshot from the most recent `run --apply`) and, via the configured LLM provider, generates **docstrings**, **inline comments**, a **CHANGELOG entry**, and a **modernization report** under `docs/refactron/`. It either prints the result (dry-run, the default) or writes it (`--apply`). After an `--apply`, every documented file is re-checked for syntax; a file that fails is rolled back on its own. This is the only command that touches an LLM, and it operates **only on already-verified diffs** — the worst-case is a wrong docstring, never broken code. | Flag | Type | Default | Description | | ------------------- | -------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- | | `--apply` | bool | false | Write docstrings + inline comments into source files, append `CHANGELOG.md`, and emit the modernization report. | | `--no-comments` | bool | false | Skip inline-comment generation (docstrings + CHANGELOG + report only). | | `--no-report` | bool | false | Skip the modernization report under `docs/refactron/`. | | `--no-cache` | bool | false | Bypass the prompt/response cache under `.refactron/cache/llm/`. | | `--json` | bool | false | Emit the `DocPatch` as JSON. | | `--provider=` | `backend \| ollama \| openai \| anthropic \| groq` | `backend` | Override `.refactronrc.json`'s `documentation.provider`. | | `--model=` | string | provider default | Override the model name. | ```bash one-shot theme={null} refactron document # dry-run, prints DocPatch refactron document --apply # write docstrings + CHANGELOG refactron document --provider=ollama --model=qwen2.5-coder:7b --apply ``` ```bash REPL theme={null} ❯ document ❯ document --apply ``` **Exit codes:** `0` success (dry-run or apply); `7` not authenticated; `8` no `.refactron/last-apply.json` snapshot — run `run --apply` first; `9` provider configuration error (missing API key, factory threw); `10` flag parse error or internal error; `11` partial success — every documented file failed the post-apply syntax re-check and was rolled back. *** ## `init` ```bash theme={null} refactron init [target] ``` Scaffold a `.refactronrc.json` template into the target directory (default: `.`). Errors if a config already exists. | Flag | Type | Default | Description | | ---------- | ---- | ------- | -------------------------------------------- | | `[target]` | path | `.` | Directory to write `.refactronrc.json` into. | ```bash one-shot theme={null} refactron init refactron init my-project/ ``` ```bash REPL theme={null} ❯ init ``` **Exit codes:** `0` created; `1` config already exists. *** ## `login` ```bash theme={null} refactron login ``` Open the OAuth 2.0 Device Authorization flow in the browser. On success, credentials are written to `~/.refactron/credentials.json`. REPL only (also runs automatically when an unauthenticated user invokes any auth-gated command). *** ## `logout` ```bash theme={null} refactron logout ``` Remove `~/.refactron/credentials.json`. The next auth-gated command will prompt for re-login. *** ## `auth` ```bash theme={null} refactron auth ``` Print authentication status — current account, token age, refresh-token presence — without modifying anything. *** ## `status` ```bash theme={null} ❯ status ``` Print the active session's summary (id, target, finding count, severity histogram, age). If no session is active in this REPL, falls back to the most recent saved session under `.refactron/work-sessions/`. REPL only. *** ## `session` ```bash theme={null} ❯ session list ❯ session ``` `session list` prints all saved sessions newest-first. `session ` loads a previously-saved session and makes it active in this REPL — subsequent `run` / `document` calls operate against it. REPL only. *** ## `rollback` ```bash theme={null} refactron rollback [target] [flags] ``` Undo the most recent `run --apply` or `document --apply` operation. Refactron journals every applied operation under `.refactron/journal/`; `rollback` reverts the newest entry (LIFO) — restoring changed files to their pre-operation content and deleting files the operation created. It is **drift-safe**: if a file has been edited since the operation was applied, `rollback` refuses rather than discard your work — re-run with `--force` to override. | Flag | Type | Default | Description | | ----------- | ---- | ------- | ------------------------------------------------------------------------ | | `--all` | bool | false | Revert every journalled operation, newest-first — not just the last one. | | `--force` | bool | false | Roll back even when a target file has drifted since it was applied. | | `--dry-run` | bool | false | Print what would be reverted without writing anything. | ```bash one-shot theme={null} refactron rollback # undo the last run / document --apply refactron rollback --dry-run # preview the revert refactron rollback --all # unwind every journalled operation ``` ```bash REPL theme={null} ❯ rollback ``` **Exit codes:** `0` reverted (or nothing to roll back, or `--dry-run`); `1` blocked by drift without `--force`, or bad flags; `2` internal error during revert. *** ## `help` / `?` ```bash theme={null} ❯ help ❯ ? ``` Print the inline help table for all REPL verbs. REPL only. *** ## `clear` ```bash theme={null} ❯ clear ``` Clear the terminal viewport. REPL only. *** ## `exit` / `quit` ```bash theme={null} ❯ exit ❯ quit ``` Leave the REPL. *** ## Global behaviour * **`refactron --version` / `-v`** — print the version and exit (fast path, \< 10ms target). * **`refactron --help` / `-h`** — print the top-level command list and exit. * Authentication is required for `analyze`, `run`, `document`, `init` — these commands return exit code `7` and prompt for login when credentials are missing or expired. * A `.refactronrc.json` in the project root is auto-loaded; CLI flags always override its values.