CLI

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

Quick Start

npx bitfab-cli init

This runs the full onboarding flow:

Detects which editors you have installed
Installs the Bitfab plugin in your chosen editor
Authenticates via browser-based OAuth
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:

npx bitfab-cli init --editor claude
npx bitfab-cli init --editor codex
npx bitfab-cli init --editor cursor
npx bitfab-cli init --editor amp

With --editor amp, step 2 clones the Amp plugin into ~/.config/amp/plugins/bitfab and step 4 starts Amp with the setup skill to invoke. See Amp.

Commands

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

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.

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.

npx bitfab-cli plugin-install [--editor <name>]

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.

npx bitfab-cli login

Pass --force to re-authenticate when you’re already signed in. --force also opens a fresh Studio window even if one is already open, so it’s how you recover when login reports that a Studio window is already open but isn’t responding.

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.

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.

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.

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, or Amp headless (amp -x) with --editor amp. 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.

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. With --editor amp, starts Amp and prints the bitfab:assistant invocation to type, since Amp takes no initial message on launch.

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. With --editor amp, plugin pulls the latest plugin into ~/.config/amp/plugins/bitfab (run plugins: reload in Amp afterward), and sdk starts Amp with bitfab:update sdk to invoke.

npx bitfab-cli update [--editor <name>] [plugin | sdk | all]

Flags

`--editor`, `-e`

Target a specific editor (claude, codex, cursor, or amp). 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, --dangerously-bypass-approvals-and-sandbox 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. Cursor and Amp have no launch flag for this, so the CLI never asks there; passing the flag explicitly prints where the equivalent lives instead (amp.dangerouslyAllowAll in Amp’s settings).

`--limit`

Cap how many draft trace plans analyze-repo uploads (default 5). Passed through to the analyze-repo skill as its plan cap, on every editor including --editor amp. Applies to: analyze-repo. Note that setup --v2 analyze-repo has no --limit flag of its own and ignores one silently, so cap the run through analyze-repo --editor amp --limit <n>.

`--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. Session log capture on Amp ships in a follow-up release, so with --editor amp the flag is accepted and currently has no effect.

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

Amp

Clones the Bitfab plugin into ~/.config/amp/plugins/bitfab and confirms Amp loaded it
Starts Amp and prints the skill invocation to type (bitfab:setup, bitfab:assistant, bitfab:update sdk)
Runs analyze-repo headless through amp -x

npx bitfab-cli init --editor amp

Every command works with --editor amp. What differs from the other hosts is listed in the Amp plugin docs.

Requirements

Node.js 18+
At least one supported editor installed: claude, codex, cursor, or amp must be on your PATH
--editor amp also needs git, which installs the plugin

Getting Started

Primitives

Account

SDKs

Framework Integrations

Integrations

Web Portal

Reference

Changelog

Quick Start

Commands

`init`

`plugin-install`

`logout`

`session-logs`

`setup`

`analyze-repo`

`assistant`

`update`

Flags

`--editor`, `-e`

`--skip-permissions`

`--limit`

`--prompt`, `-p`

`--upload-logs`

What It Does Per Editor

Claude Code

Codex

Cursor

Amp

Requirements

​Quick Start

​Commands

​init

​plugin-install

​login

​logout

​session-logs

​setup

​analyze-repo

​assistant

​update

​Flags

​--editor, -e

​--skip-permissions

​--limit

​--prompt, -p

​--upload-logs

​What It Does Per Editor

​Claude Code

​Codex

​Cursor

​Amp

​Requirements

Quick Start

Commands

`init`

`plugin-install`

`login`

`logout`

`session-logs`

`setup`

`analyze-repo`

`assistant`

`update`

Flags

`--editor`, `-e`

`--skip-permissions`

`--limit`

`--prompt`, `-p`

`--upload-logs`

What It Does Per Editor

Claude Code

Codex

Cursor

Amp

Requirements