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 nextrefactor 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/*.whlrefactorai-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.28
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| refactorai_cli-0.7.28.tar.gz | 188.4 kB | Without provenance | Details for refactorai_cli-0.7.28.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| refactorai_cli-0.7.28-py3-none-any.whl | Python 3 | none | any | Details for refactorai_cli-0.7.28-py3-none-any.whl |
Total release size: 396.5 kB
Release files / refactorai_cli-0.7.28.tar.gz
| Download URL | refactorai_cli-0.7.28.tar.gz |
|---|---|
| Size | 188.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
914557e7f5588aa98178b7767d4caa55cccd43c34bf084cc5f01759047539f53
|
|
BLAKE2b-256 checksum How to use checksums |
596d052ec011d7020051d631a3636a5f9c4d37bd9e6f2bb08071d484588603de
|
| 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.28-py3-none-any.whl
| Download URL | refactorai_cli-0.7.28-py3-none-any.whl |
|---|---|
| Size | 208.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ce50e65475da42afd52276c8e95cf3fe06ec83b9de0629a0b77b07ebb9095b25
|
|
BLAKE2b-256 checksum How to use checksums |
6a015648b43b0734e5997d8339cb65cd7566ab427417ceeb0b814840a8f5de47
|
| 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.28
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.