Getting Started

Install & setup

Install the CLI globally with pipx, authenticate, enable Git hooks, and start the Refactor Terminal beside your editor or Git client.

15 minExternal developers and tech leads

Prerequisites

Python 3.11+ for CLI usage
pipx (recommended) for a global, isolated CLI install
Git access to your source repositories
A RefactorAI account at refactorai.codes
Developer key generated in the RefactorAI dashboard

Install the CLI

Install the CLI once in your developer environment. pipx is recommended because it makes refactor available globally while isolating its Python dependencies from your projects.

Install command

# Recommended: global, isolated install via pipx
pipx install refactorai-cli
refactor --help

# No pipx yet? Bootstrap it once:
#   python3 -m pip install --user pipx
#   python3 -m pipx ensurepath
# Windows PowerShell:
#   py -m pip install --user pipx
#   py -m pipx ensurepath
# Or fall back to plain pip:
#   python3 -m pip install --upgrade refactorai-cli

Authenticate with a platform-issued key

Authenticate with the developer key issued from the RefactorAI dashboard. The CLI uses the hosted API by default; set REFACTOR_PLATFORM_URL only for self-hosted or local development environments.

Hosted platform authentication

# Generate your key in https://refactorai.codes dashboard
refactor login --key <your_developer_key>
refactor whoami

Enable repository hooks

Run this once per repository. The hook sits at the Git layer, so it sees commits created from the terminal, VS Code, Cursor, JetBrains, GitHub Desktop, and most desktop Git clients.

Initialize RefactorAI and install hooks

cd <your-repo>
refactor init
refactor hook install
refactor hook status

Git clients must run local hooks

Some GUI clients expose settings to disable Git hooks. If new commits do not show up in refactor watch, check the Git client's hook settings or commit once from the terminal to verify the hook installation.

Open the Refactor Terminal

Keep refactor watch open like a dev server. In VS Code or Cursor, use the integrated terminal. In JetBrains, use the built-in terminal. With desktop Git apps, keep a regular terminal beside the app.

Start watching commits

# Keep this open beside your editor or Git client
refactor watch

# Agent/headless mode
refactor watch --json

Apply a team baseline configuration

Use a shared refactor.consti baseline so every repository follows the same local review and gate defaults. Start new teams in warn mode, then move stricter repositories to strict once the workflow is familiar.

Local commit-loop baseline

# refactor.consti
version: 1

settings:
  developer_key: ${REFACTOR_API_KEY}
  mode: local
  watch:
    auto_open: false
  gate_mode: warn

Validate your setup

Before sharing onboarding docs with your team, run a quick identity and environment validation.

Developer setup verification

refactor whoami
refactor doctor