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.
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]
| 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
0 clean; 1 --fail-on matched; 2 flag parse or config error.
run
refactron run [target] [flags]
--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
0 plan applied (or dry-run printed); 1 verification failed (gate rejected); 2 flag parse error or missing path.
document
refactron document [target] [flags]
.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
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
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/
0 created; 1 config already exists.
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
Remove ~/.refactron/credentials.json. The next auth-gated command will prompt for re-login.
auth
Print authentication status — current account, token age, refresh-token presence — without modifying anything.
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]
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
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 / ?
Print the inline help table for all REPL verbs.
REPL only.
clear
Clear the terminal viewport.
REPL only.
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.
