> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitfab.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install and configure the Bitfab plugin from your terminal

The Bitfab CLI installs the plugin, authenticates, and launches setup for Claude Code, Codex, or Cursor in one command.

## Quick Start

```bash theme={null}
npx bitfab-cli init
```

This runs the full onboarding flow:

1. **Detects** which editors you have installed
2. **Installs** the Bitfab plugin in your chosen editor
3. **Authenticates** via browser-based OAuth
4. **Launches** the setup command (`/bitfab:setup`) in your editor

If multiple editors are detected, you'll be prompted to choose one. To skip the prompt, pass `--editor`:

```bash theme={null}
npx bitfab-cli init --editor claude
npx bitfab-cli init --editor codex
npx bitfab-cli init --editor cursor
```

## Commands

Every command supports `-h` and `--help`. You can also use `help <command>`:

```bash theme={null}
npx bitfab-cli --help
npx bitfab-cli analyze-repo --help
npx bitfab-cli help analyze-repo
```

### `init`

Full onboarding: install the plugin, authenticate, and launch setup.

```bash theme={null}
npx bitfab-cli init [--editor <name>]
```

### `plugin-install`

Install the Bitfab plugin without authenticating or launching setup. Useful if you want to handle login separately.

```bash theme={null}
npx bitfab-cli plugin-install [--editor <name>]
```

### `login`

Authenticate with Bitfab. Opens your browser for OAuth, then saves credentials to `.bitfab/credentials.local.json` when that project-local file exists, otherwise to `~/.config/bitfab/credentials.json`.

```bash theme={null}
npx bitfab-cli login
```

Pass `--force` to re-authenticate when you're already signed in. `--force` also clears a stale Studio session before opening, so it's how you recover when login reports that a Studio window is recorded as open but is not responding.

```bash theme={null}
npx bitfab-cli login --force
```

### `logout`

Remove stored credentials. If project-local credentials exist, removes `.bitfab/credentials.local.json`; otherwise removes `~/.config/bitfab/credentials.json`.

```bash theme={null}
npx bitfab-cli logout
```

### `session-logs`

Read or update the saved session-log collection preference. This is the same shared setting used by setup and `analyze-repo` when no per-run `--upload-logs` or `--no-upload-logs` flag is passed.

```bash theme={null}
npx bitfab-cli session-logs status
npx bitfab-cli session-logs enable
npx bitfab-cli session-logs disable
```

### `setup`

Launch the editor's setup command (`/bitfab:setup` for Claude Code, `$bitfab:setup` for Codex) without reinstalling the plugin. For Cursor, prints the setup command and next steps.

```bash theme={null}
npx bitfab-cli setup [--editor <name>]
```

### `analyze-repo`

Headlessly scan the repository for AI workflows and upload a **draft trace plan** for each of the top candidates, with no prompts and no code changes. Runs the editor's analyze-repo command non-interactively through Claude Code, Codex, or Cursor Agent. After upload, it prints a compact terminal summary of the suggested workflows, instrumentation effort, capture methods, and replay mocks. If you're not signed in and the CLI is attached to a terminal, it opens the browser login flow first; in non-interactive environments, sign in ahead of time with `npx bitfab-cli login` or set `BITFAB_API_KEY`. Use `--limit` to cap how many plans it uploads (default 5), and `--prompt` (or a trailing quoted argument) to steer what the scan focuses on.

```bash theme={null}
npx bitfab-cli analyze-repo [--editor <name>] [--limit <n>] [--prompt <text>] [--upload-logs | --no-upload-logs]
npx bitfab-cli analyze-repo --prompt "focus on the billing and checkout flows"
```

### `assistant`

Launch the Bitfab assistant (`/bitfab:assistant` for Claude Code, `$bitfab:assistant` for Codex) to iterate on traced functions. Any extra arguments are passed through to the editor command. To forward an argument that looks like a bitfab flag, place it after `--`: everything after `--` is passed through verbatim.

```bash theme={null}
npx bitfab-cli assistant [--editor <name>] [args...]
npx bitfab-cli assistant -- --some-editor-flag value
```

### `update`

Update the Bitfab plugin and SDKs. The CLI refreshes the plugin directly (marketplace update + plugin update), then launches the editor's update command for SDK updates. Pass `plugin`, `sdk`, or `all` to control scope.

```bash theme={null}
npx bitfab-cli update [--editor <name>] [plugin | sdk | all]
```

## Flags

### `--editor`, `-e`

Target a specific editor (`claude`, `codex`, or `cursor`). If omitted, the CLI detects installed editors and prompts you to choose.

### `--skip-permissions`

Run the launched agent without permission prompts (translates to `--dangerously-skip-permissions` for Claude Code, `--full-auto` for Codex). If you omit this flag, the CLI will ask interactively whether to skip permissions. Pass `--no-skip-permissions` to keep permission prompts without being asked.

Applies to: `init`, `setup`, `assistant`, `update`.

### `--limit`

Cap how many draft trace plans `analyze-repo` uploads (default 5). Passed through to the `analyze-repo` skill as its plan cap.

Applies to: `analyze-repo`.

### `--prompt`, `-p`

Free-text guidance steering what `analyze-repo` focuses on (for example, `--prompt "focus on the billing and checkout flows"`). You can also pass it as a trailing quoted argument without the flag. Passed through to the `analyze-repo` skill, which biases its scan and ranking toward the areas you name while still filling any remaining plan slots from the rest of the repo.

Applies to: `analyze-repo`.

### `--upload-logs`

Upload the `analyze-repo` run's session logs to Bitfab to help diagnose issues (translates to the plugin's session-log capture for that run). Pass `--no-upload-logs` to keep them local. If you omit both, the CLI uses your saved session-log preference, asking once if it isn't set yet.

Applies to: `analyze-repo`.

## What It Does Per Editor

### Claude Code

* Adds the `bitfab` marketplace (from `Project-White-Rabbit/bitfab-claude-plugin`)
* Enables auto-updates for the marketplace
* Installs the plugin at user scope
* Launches `claude /bitfab:setup`

### Codex

* Adds the `bitfab` marketplace (from `Project-White-Rabbit/bitfab-codex-plugin`)
* Enables the plugin in `~/.codex/config.toml`
* Launches `codex $bitfab:setup`

### Cursor

* Copies the `/add-plugin` command to your clipboard
* Opens Cursor so you can paste and run the command
* Prints next steps for completing setup in Cursor

## Requirements

* Node.js 18+
* At least one supported editor installed: `claude`, `codex`, or `cursor` must be on your PATH