Skip to main content

refactorai-cli

Public CLI package for Refactor.

  • PyPI package name: refactorai-cli
  • Installed command: refactor
  • Python module package: refactorai_cli

By default, the CLI targets https://api.refactorai.codes. Use REFACTOR_PLATFORM_URL only when you need to override the control-plane URL (for self-hosted or local development environments).

Developer flow (init → setup → doctor → watch)

The standard flow after creating an account and generating a developer key:

# 1. Create the project (prompts for the developer key if needed) and register
#    it with the platform. Writes refactor.consti + refactor.config.
refactor init

# 2. Choose the execution mode and provision only what that mode needs.
#    Mode can be chosen in the web UI or here; the two stay in sync.
refactor setup --mode local_byok

# 3. Verify readiness for the resolved mode.
refactor doctor

# 4. Start the commit loop: commit in your editor, and each commit is reviewed,
#    refactored, verified, and merged, then it waits for the next commit.
refactor watch

Tip: rfc is a built-in short alias for refactor — rfc doctor, rfc watch, rfc review, etc. all work identically.

Refactor Terminal actions (refactor watch)

  • [r] refactor — resolve the selected commit's requests (per-request prompts).
  • [a] refactor all — resolve all of the selected commit's requests in one auto-approved pass (one up-front confirmation, then no per-request prompts).
  • [f] fresh review, [d] diff, [q] quit.

In local_heuristic (review-only) mode the terminal shows just [f] fresh review and [q] quit — [r]/[a]/[d] are hidden because heuristic mode detects issues but does not auto-apply fixes. Switch to a model mode (local_byok / local_model) to refactor.

Execution modes at a glance

Two independent axes: where the engine runs, and where verification (tests) runs. See docs/46-execution-variants-and-developer-flow.md.

variant engine verification (tests) runtime artifact
local_heuristic local (no LLM) none (deterministic + Semgrep) not required
local_model local local required
local_byok server local (Podman sandbox / toolchain) not required
local_managed server local (Podman sandbox / toolchain) not required
cloud_byok server server not required
cloud_managed server server not required

refactor setup is mode-aware: local_byok provisions the local verification environment (Podman first) + auth only — it does not download the runtime artifact or install a local model. Only local_model needs the runtime artifact.

local_heuristic needs no runtime artifact and no refactor setup: after refactor init, refactor review / refactor watch run a client-safe, non-LLM analysis — deterministic static checks (refactor_core.heuristics) merged with a Semgrep scan (the pip semgrep dependency). The deterministic checks cover language-agnostic hygiene (over-long lines, oversized files, merge-conflict markers, TODO/FIXME), Python (function length, bare except:, leftover print(), JS/TS (empty catch {}, console.log/debugger, long functions), and C-like long functions. Thresholds are configurable via heuristics.max_function_lines, heuristics.max_line_length, and heuristics.max_file_lines in refactor.config (falling back to your constitution's N lines rule, then built-in defaults). The quality gate is evaluated on the combined findings. It does not auto-apply fixes; switch to a model mode (local_byok / local_model) for automated resolution.

Semgrep powers the security findings and ships with the CLI (it is a dependency of refactorai-core), so developers never install it separately. The scanner is resolved via PATH, then this interpreter's venv bin (the pipx case), then python -m semgrep, so it works out of the box on a plain pipx install refactorai-cli with no PATH step. In the rare case it cannot be resolved, review / watch / doctor print a security scanner: ... reinstall hint instead of failing silently. Findings are stored in the central store; review prints the report.json path.

The verification environment is chosen by a single OS/machine-aware seam (refactor_core.verification_env): the Podman sandbox by default, falling back to the managed host toolchain when no container runtime is available. refactor doctor reports the selected environment (and refactor doctor --sandbox shows its full state), so a run and diagnostics always agree.

Customizing refactor.config

refactor init writes a bare-minimum refactor.config: just version, project_id, and a CLI-managed block seeded to local_heuristic. A normal developer never edits this file by hand — pick the mode (and provider keys, if any) in the web UI or via refactor setup --mode <variant>.

The managed block (single source of truth for the mode)

# >>> refactor managed (synced from server; do not edit) >>>
execution_variant: cloud_byok
provider: openai
model_id: gpt-4.1-mini
credential_ref: cred_01J...
# <<< refactor managed <<<
  • Owned by the CLI. refactor setup (terminal) writes it immediately; a change made in the web UI is pulled into this block on the next refactor doctor / refactor watch / refactor setup (server-wins).
  • Only these keys live here: execution_variant, provider, model_id, base_url (local_model), credential_ref. Secrets are never written — keep provider keys in the environment and reference them as ${ENV_VAR}.

What each mode needs

variant you provide
local_heuristic nothing
local_model nothing (setup writes the Ollama provider/model block)
local_byok provider API key in the env (${VAR}); provider/model via UI/setup
local_managed nothing
cloud_byok provider API key in env (or a UI credential); provider/model via UI/setup
cloud_managed nothing

Advanced knobs and precedence

Advanced settings (sandbox, verification, intelligence, compliance, watch, timeout, exclude, model_context_overrides, …) are not written by init; add only the ones you need anywhere outside the managed block. refactor init --full writes the fully-annotated template with every knob if you prefer to start from that.

Resolution precedence: CLI flags → environment (provider_key, REFACTOR_PROVIDER) → the synced managed block → code defaults. A key you place outside the managed block (later in the file) also takes precedence over the block, so power users can pin values while normal syncing continues.

Local development install

From repository root:

pip install -e refactorai-core -e refactorai-cli

Build

From repository root:

python -m pip install --upgrade build twine
python -m build "./refactorai-cli"

Artifacts are created in:

  • refactorai-cli/dist/*.whl
  • refactorai-cli/dist/*.tar.gz

Publish

python -m twine check ./refactorai-cli/dist/*
python -m twine upload ./refactorai-cli/dist/*

Install test (local)

python -m pip install ./refactorai-cli/dist/refactorai_cli-0.3.4-py3-none-any.whl
refactor --version

Cloud BYOK setup (bring your own provider key)

Run cloud inference with your own provider credentials (no local runtime required). Preferred path is env-key in project config (provider_key: ${ENV_VAR}). Platform-stored credentials (credential_ref) are optional fallback.

# 1. Authenticate (developer key with the run:byok entitlement).
refactor login

# 2A. Preferred: set BYOK directly from project env in refactor.config:
#
# execution_variant: cloud_byok
# provider: openai
# model_id: gpt-4.1-mini
# provider_key: ${OPENAI_API_KEY}
#
# 2B. Optional fallback: register a platform-stored credential from env.
export OPENAI_API_KEY=sk-...
refactor cloud credentials set --provider openai --from-env OPENAI_API_KEY --label "my key"
# -> prints a credential_ref, e.g. cred_01J...

# 3. If you use platform-stored fallback, set credential_ref in config:
#    credential_ref: cred_01J...

# 4. Verify readiness, then run.
refactor doctor
refactor review .
refactor code . --apply

Manage credentials:

refactor cloud credentials list
refactor cloud credentials remove --credential-ref cred_01J...

Metadata

Release files for refactorai-cli 0.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for refactorai-cli 0.14.0
File Size Uploaded Provenance Actions
refactorai_cli-0.14.0.tar.gz 223.3 kB Without provenance Details for refactorai_cli-0.14.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for refactorai-cli 0.14.0
File Interpreter ABI Platform Actions
refactorai_cli-0.14.0-py3-none-any.whl Python 3 none any Details for refactorai_cli-0.14.0-py3-none-any.whl

Total release size: 467.2 kB

Release files / refactorai_cli-0.14.0.tar.gz

Download URL refactorai_cli-0.14.0.tar.gz
Size 223.3 kB
Tags Source
SHA-256 checksum
How to use checksums
f8140112d8db99a92af723aff90757a9b557f4f03d6ce4c891d42e6da92db8a5
BLAKE2b-256 checksum
How to use checksums
c71bd45b7a3c1b1042aa83cc8a67a5defd502b2f39dd51ff1b2db5ef14121871
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / refactorai_cli-0.14.0-py3-none-any.whl

Download URL refactorai_cli-0.14.0-py3-none-any.whl
Size 243.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
327fc7269af9c7ee66cd9428c4377d03c81b1c7afa63d009dcb62acec1a41219
BLAKE2b-256 checksum
How to use checksums
ddd0efd9e4b2906d4566030d3e0671860709f06381beb282a4f7ce5f9cf06bbf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for refactorai-cli 0.14.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.14.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page