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

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

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

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.7.15
File Size Uploaded Provenance Actions
refactorai_cli-0.7.15.tar.gz 180.0 kB Without provenance Details for refactorai_cli-0.7.15.tar.gz

Built distribution (wheel)

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

Total release size: 379.7 kB

Release files / refactorai_cli-0.7.15.tar.gz

Download URL refactorai_cli-0.7.15.tar.gz
Size 180.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f40d13c79f19362837976b175259c7f6396c917289152df1f2bd4044c575637a
BLAKE2b-256 checksum
How to use checksums
802fc6775f4d41eb8aba066d7fe732fd6cb7d7b53f582dd2efbd454eb13e7b61
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.7.15-py3-none-any.whl

Download URL refactorai_cli-0.7.15-py3-none-any.whl
Size 199.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d1822958aa2aebf95bd532c99a97d96670491c4ba97d8ef83a2b2c7d5f80ca25
BLAKE2b-256 checksum
How to use checksums
a0387ef126726f1663db8d6abc4f7ee8d2055405fed57a1c76a061e03b986139
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.7.15

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