Skip to main content

​
1 — Install

npm install -g refactron@0.2.3
Or via PyPI (Python wrapper around the npm package — Node.js 18+ still required): 
pip install refactron
Confirm: 
refactron --version       # → 0.2.3

​
2 — Authenticate (one-time)

Refactron needs an account to run analyze, run, and document. 
refactron login
This opens a browser-based OAuth device flow — approve the request and the CLI stores your credentials in ~/.refactron/credentials.json. You won’t need to log in again on this machine. For CI or headless environments, skip the browser: open your Refactron dashboard, go to API Keys, and click Create Key. The key authenticates the CLI the same way a login session does.
The API Keys page in the Refactron dashboard
Expose the generated key as the REFACTRON_TOKEN environment variable: 
export REFACTRON_TOKEN=refactron_live_...
analyze, run, and document all read REFACTRON_TOKEN when it is set, so no refactron login step is needed in CI.

​
3 — Analyze

From your project root: 
refactron analyze .
Output (sample) — findings render as one bordered box per file, followed by summary tables:
Refactron analyze output: a bordered table of format_to_fstring findings under src/api/users.py followed by a SUMMARY block listing files affected, severity counts, and auto-fixable candidates
analyze reports every finding as an auto-fix candidate — it never runs a transform, so run --dry-run is the source of truth for what actually changes.

​
4 — Preview the refactor

refactron run --dry-run .
Shows the unified diff per file. Nothing has been written.

​
5 — Apply with verification

refactron run --apply .
The 3 gates run in order: syntax → imports → tests. If any gate fails, your tree is untouched — there is nothing to roll back. If all gates pass, the refactor is committed atomically (every file or none).

​
6 — Document the refactor (optional)

refactron document --apply
Runs on the snapshot from the last run --apply and writes docstrings, inline comments, a CHANGELOG entry, and a modernization report under docs/refactron/. This is the one step that uses an LLM, and it runs only on the already-verified diff — the worst case is a wrong sentence, never broken code. It needs an LLM provider configured (managed backend, Ollama, OpenAI, Anthropic, or Groq) — see .refactronrc.json → documentation.
Made a change you want to undo? refactron rollback reverts the last run --apply or document --apply — a drift-safe LIFO undo. See the CLI reference.

​
Next steps