CLI reference

The CodeLoop CLI ships as the npm package codeloop. Every command is invokable through npx codeloop <cmd> with zero global install. This page is the canonical reference for every command, flag, and exit code.

Install

# always-fresh, no global install (recommended)
npx codeloop <command>

# or install globally
npm install -g codeloop
codeloop <command>

# verify the version you're running
npx codeloop --version

The CLI requires Node.js 18 or newer. Run npx codeloop doctor at any time to confirm your machine is ready for the full loop.

Command index

init

Bootstrap a project (or, with --global, your whole machine). Auto-detects the stack (Flutter / Web / Node / Python / Ruby / Rails / Rust / .NET / Xcode) and writes:

• .codeloop/config.json— the project config.
• .cursor/mcp.json and .cursor/rules/*.mdc — Cursor configuration.
• .claude/settings.local.json and .claude/agents/*— Claude Code configuration.
• docs/specs/_master.md, docs/acceptance/*.md, UX checklist — spec templates.

# bootstrap the current project
npx codeloop init

# overwrite existing CodeLoop files
npx codeloop init --force

# install global activation (MCP + Claude memory file)
npx codeloop init --global

# pick the agent explicitly
npx codeloop init --agent cursor
npx codeloop init --agent claude
npx codeloop init --agent both

auth

Browser-based authentication. Opens codeloop.tech/cli-auth, where you sign in (GitHub / Google / Apple / email) and approve the request. The browser hands a fresh API key back to the CLI over a one-time loopback callback. The key is saved to ~/.codeloop/config.json.

npx codeloop auth

# fall back to email + password (headless / firewalled boxes)
npx codeloop auth --no-browser

# rotate the key from the browser flow
npx codeloop auth --rotate

signup

Create an account directly from the terminal. Prompts for name, email, and password, then prints and saves your first API key.

npx codeloop signup

login

Sign in to an existing account by email + password. For browser-based login (recommended), use auth instead.

npx codeloop login

verify

Run the full verification suite (lint + tests + build + screenshots for UI projects). Returns a structured pass / fail report and a run_id you can pass into codeloop_diagnose and codeloop_gate_check.

# full suite
npx codeloop verify

# only checks affected by recent changes
npx codeloop verify --scope affected

# force a specific platform
npx codeloop verify --platform flutter

# verbose stdout / stderr from runners
npx codeloop verify --debug

# point at a different project root
npx codeloop verify --project /abs/path/to/project

doctor

The most useful diagnostic in the CLI. Runs through every layer of the activation chain plus the runtime tooling required by the loop:

• Activation— global MCP config, agent rules, project config, Cursor User Rule registration, Claude memory file.
• Runtime tooling— ffmpeg, xcrun / simctl, screencapture, xdotool, xwininfo, PowerShell, adb, Playwright Chromium.
• Backend reachability — HEAD against BACKEND_URL/v1/version.

Each missing optional tool surfaces as a yellow warning with a one-line remedy. Each missing required tool fails with the exact install command for your OS.

npx codeloop doctor

# JSON output for CI
npx codeloop doctor --json

# only the activation checks (skip runtime tooling)
npx codeloop doctor --activation

status

One-shot summary of who you are and where you stand: account email, plan (trial / solo / team / enterprise / oss / lifetime), usage this period, days left on trial, and whether the current directory is a CodeLoop project.

npx codeloop status

dashboard

Launch the local Next-based artifact viewer at http://localhost:3737. See Local Dashboard for the full UI tour.

# default
npx codeloop dashboard

# custom port
npx codeloop dashboard --port 4000

# Cloudflare tunnel (public temporary URL)
npx codeloop dashboard --share

# read artifacts from a different directory
npx codeloop dashboard --runs-dir /tmp/codeloop-runs

design

One-shot design comparison from the CLI — useful for spot-checking a Figma diff outside the agent loop. Reads .codeloop/figma.json (or designs/ for local PNGs) and runs codeloop_design_compare as a one-off.

npx codeloop design

# limit to a single screen
npx codeloop design --screen home

# fail with non-zero exit if score drops below threshold
npx codeloop design --threshold 0.85

baseline

Manage visual regression baselines. Use this once a UI change is intentional and you want subsequent runs to match the new look.

# list baselines
npx codeloop baseline list

# accept the latest run as the new baseline
npx codeloop baseline update

# accept only one screen + viewport
npx codeloop baseline update --screen home --viewport desktop

# delete a baseline (next run will create a fresh one)
npx codeloop baseline reset --screen home

configure

Open .codeloop/config.json in your $EDITOR (defaults to vi on Unix and notepad on Windows). A thin convenience wrapper for the most common config tweak.

npx codeloop configure
EDITOR=code npx codeloop configure

cursor-rule

Print the canonical CodeLoop Cursor User Rule to stdout, ready for copy/paste into Cursor » Settings » Rules » User Rules. Useful when the extension is unavailable or you want to inspect what the rule contains.

npx codeloop cursor-rule

# pipe into the clipboard (macOS)
npx codeloop cursor-rule | pbcopy

install-cursor-extension

Install the CodeLoop Cursor extension VSIX (or, once published, from the Cursor / Open VSX marketplace). Bundles the auto-paste of the global User Rule, MCP server registration, and the in-IDE Doctor command. See Cursor extension.

npx codeloop install-cursor-extension

# pin to a specific version
npx codeloop install-cursor-extension --version 0.1.5

# build from source (CodeLoop checkout only)
npx codeloop install-cursor-extension --from-source

Environment variables read by the CLI

Exit codes

Related

• Quick Start— first-time install.
• Configuration — the .codeloop/config.json reference.
• Tool reference— the equivalent MCP tool surface.
• Troubleshooting— symptom-first index when something goes wrong.