CLI Reference - Refactron

Refactron is a single binary, refactron, with two execution modes:

One-shot: refactron <command> [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`

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>`	path	none	Also write the analysis report (with import/call graphs) as JSON to `<path>`.

refactron analyze src/
refactron analyze . --json > report.json
refactron analyze . --fail-on high   # CI gate

❯ analyze .
❯ analyze src/

Exit codes: 0 clean; 1 --fail-on matched; 2 flag parse or config error.

`run`

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=<list>`	csv or `all`	`all`	Limit to specific transform IDs.
`--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=<n>`	int	30	Context lines per file in dry-run output.
`--files=<glob>`	glob	none	Scope the dry-run preview to a subset of planned changes.
`--json`	bool	false	Emit `{ mode, plan }` as JSON.

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

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

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=<name>`	`backend \| ollama \| openai \| anthropic \| groq`	`backend`	Override `.refactronrc.json`’s `documentation.provider`.
`--model=<name>`	string	provider default	Override the model name.

refactron document                  # dry-run, prints DocPatch
refactron document --apply          # write docstrings + CHANGELOG
refactron document --provider=ollama --model=qwen2.5-coder:7b --apply

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

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.

refactron init
refactron init my-project/

❯ init

Exit codes: 0 created; 1 config already exists.

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`

refactron logout

Remove ~/.refactron/credentials.json. The next auth-gated command will prompt for re-login.

`auth`

refactron auth

Print authentication status — current account, token age, refresh-token presence — without modifying anything.

`status`

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

❯ session list
❯ session <id>

session list prints all saved sessions newest-first. session <id> loads a previously-saved session and makes it active in this REPL — subsequent run / document calls operate against it. REPL only.

`rollback`

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.

refactron rollback                    # undo the last run / document --apply
refactron rollback --dry-run          # preview the revert
refactron rollback --all              # unwind every journalled operation

❯ 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` / `?`

❯ help
❯ ?

Print the inline help table for all REPL verbs. REPL only.

`clear`

❯ clear

Clear the terminal viewport. REPL only.

`exit` / `quit`

❯ 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.

​analyze

​run

​document

​init

​login

​logout

​auth

​status

​session

​rollback

​help / ?

​clear

​exit / quit

​Global behaviour