Metadata-Version: 2.4
Name: refactorai-cli
Version: 0.7.14
Summary: Local-first CLI for the refactor platform
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: rich>=13.7.0
Requires-Dist: PyYAML>=6.0.1
Requires-Dist: refactorai-core>=3.2.23

# 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:

```bash
# 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:

```bash
pip install -e refactorai-core -e refactorai-cli
```

## Build

From repository root:

```bash
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

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

## Install test (local)

```bash
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.

```bash
# 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:

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