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.

Auto-update: what happens when you relaunch your IDE

CodeLoop has no manual update step. Every time you relaunch Cursor or Claude Code:

1. The IDE re-spawns the MCP server via npx -y codeloop-mcp-server (the default mcp.json registration written by codeloop init --global). npx silently re-resolves the latest published version — no prompts, no flags.
2. As soon as the MCP server starts, it fires off a detached npx -y codeloop@latest --version in the background. This pre-warms the npx cache for the codeloop CLI so the next time you run npx codeloop <anything>in a terminal it skips the “Need to install the following packages” prompt and uses the cached tarball.
3. The pre-warm marks itself complete only after the npx process exits with code 0. If it fails (network down, npx missing, etc.), it retries on the very next IDE relaunch instead of waiting out a cool-down.

What this means in practice:close Cursor / Claude Code, reopen it, wait ~10 seconds, and both pieces are on the latest. That’s the entire update procedure. npx codeloop update is purely a verification tool — you almost never need to run it.

Force a manual cache refresh

If you ever want to update the codeloopCLI cache without restarting your IDE — for example you’re in the middle of a long debugging session, or the IDE’s background pre-warm hasn’t completed yet — run this single command in any terminal:

npx -y codeloop@latest --version

That’s exactly what the MCP server runs in the background on every IDE launch. The -yflag tells npx to auto-accept the install (so you never see the “Ok to proceed?” prompt), and --version is a near-zero-cost subcommand that exits as soon as the tarball lands in the npx cache. After it finishes, every subsequent npx codeloop <anything> in this and every future terminal session runs silently.

Common cases for running this manually:

• You opened a terminal seconds after relaunching Cursor and beat the background pre-warm to it.
• You’re on a fresh machine that hasn’t been through a full IDE relaunch cycle yet.
• You just published a new CodeLoop release yourself and want the latest tag to land immediately.
• You’re scripting a CI step that calls npx codeloop verify and want to avoid the interactive install prompt blocking the pipeline.

Equivalent forms for skipping the prompt one-off without pre-warming the cache:

npx -y codeloop <command>           # auto-yes on this single invocation
npx codeloop@latest <command>      # version pin — npx never prompts on an explicit @tag

What if I’m on a pinned MCP version?

If your mcp.json was hand-written with a specific version (e.g. codeloop-mcp-server@0.1.27), npx pins to that tag and never upgrades it. npx codeloop update detects this and points you at the fix:

# rewrite ~/.cursor/mcp.json and ~/.claude/mcp.json to the always-fresh form
npx codeloop init --global

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

# 0.1.51+ — skip post-edit hooks (Cursor afterFileEdit + Claude PostToolUse)
# Use this if you want to opt out of the auto-prompt for codeloop_verify
# on every file edit. Existing hooks are NOT removed by this flag.
npx codeloop init --no-hooks
# (or set CODELOOP_SKIP_HOOKS=1 in your environment for the same effect)

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

# wipe the persistent init-hint cache (0.1.40+)
npx codeloop doctor --clear-init-cache

# delete artifacts/runs/ older than 30 days OR with a corrupt PNG (0.1.41+)
npx codeloop doctor --prune-artifacts

# preview without deleting
npx codeloop doctor --prune-artifacts --dry-run

# customise the age threshold (default 30)
npx codeloop doctor --prune-artifacts --older-than-days 14

# 0.1.51+ — reset the server-side iteration counter for THIS project
# (~/.codeloop/loop-state.json). Use after the agent escalates because
# gate_attempts (cap 15) or diagnose_attempts (cap 8) hit and you've made
# a fix out-of-band that the agent should retry.
npx codeloop doctor --reset-loop-state

0.1.41+ — --prune-artifacts. Walks artifacts/runs/ in the current workspace and deletes any run whose modification time is older than --older-than-days N (default 30) OR whose screenshots/ directory contains a PNG that fails the PNG-dim sniff used by codeloop_design_compare (i.e. would have poisoned a future comparison with a 0% score). Each pruned run prints the reason (stale, age=<days> or corrupt: <file>) so you can audit the action. Pair with --dry-run for a no-op preview before committing to the delete. This addresses the legacy-corrupt-PNG leak surfaced by the Photometry-DB E2E (H7).

doctor also prints a Versionssection at the top: the CLI version that’s running, plus the last cached snapshot of the latest codeloop and codeloop-mcp-server versions on npm. For a fresh, authoritative check, use codeloop update.

Starting with 0.1.40, doctor also runs a rules-drift check that compares the version stamps in your local .cursor/rules/codeloop.mdc and CLAUDE.mdagainst the running CLI version. If they don’t match, doctor prints Rules out of date — run npx codeloop init to refresh. The rule files are stamped with <!-- codeloop-rules-version: X.Y.Z --> at the top so init can rewrite them safely on every CodeLoop release.

Use --clear-init-cachewhen the “[CodeLoop] This project has not been initialized” hint keeps reappearing on a project where you HAVE already run npx codeloop init. The flag wipes ~/.codeloop/init-hint-cache.json, the persistent map of which projects have already been initialized.

0.1.51+ — --reset-loop-state. Wipes the server-side iteration counter for the current project from ~/.codeloop/loop-state.json. The counter caps the auto-fix loop at 15 codeloop_gate_check attempts and 8 codeloop_diagnose attempts; once it hits the cap codeloop_gate_check forces recommendation: "escalate" and refuses to flip back to continue_fixing without a reset. See the H7 row in the 0.1.51 troubleshooting table.

update

Check the installed CodeLoop CLI and MCP-server versions against the latest published on npm. CodeLoop runs entirely through npxby default — there’s no global binary — so “which version am I on?” is non-obvious. update answers it.

Updates are automatic. Every time Cursor or Claude Code restarts, the MCP server is re-resolved by npx -y and pulls the newest codeloop-mcp-server. The MCP server’s startup hook (added in 0.1.29) ALSO pre-warms the npx cache for the codeloop CLI in the background, so the next time you run npx codeloop updatein a terminal it skips the “Need to install the following packages: codeloop@X.Y.Z. Ok to proceed?” prompt and goes straight to a clean “You’re on the latest” message. One restart of your IDE updates both caches.

What it reports:

• codeloop (CLI)— the version of the CLI that npx just resolved (this process). Compared against https://registry.npmjs.org/codeloop/latest.
• codeloop-mcp-server— the version your IDE will load. We look in ~/.cursor/mcp.json, ~/.claude/mcp.json, and the npx cache to detect whether you’re pinned to a specific tag (e.g. codeloop-mcp-server@0.1.27) or always-fresh (-y codeloop-mcp-server, recommended).
• recommended_command— one or two shell lines that bring you to the latest. The CLI suggests npx clear-npx-cache so the next npx codeloop downloads the new tarball; for the MCP server it tells you to restart Cursor / Claude Code (or edit a pinned mcp.json entry).

# fresh check (hits npm, ~1s)
npx codeloop update

# don't hit the network — show the last cached snapshot
npx codeloop update --offline

# JSON envelope for scripts / CI
npx codeloop update --json

CodeLoop also runs a passive update check at the start of every CLI invocation (cached to 6 hours, hard-timed to 1.5s, silent on failure). If a newer CLI is on npm it prints a one-line banner to stderr after the command body finishes. Disable it with NO_UPDATE_NOTIFIER=1 or CODELOOP_SKIP_UPDATE_CHECK=1; both are auto-skipped when CI=true.

Why does npx sometimes ask “Ok to proceed?”

That prompt is a built-in npm safety check, not a CodeLoop message. It fires when npx’s cache for the codelooppackage is older than what’s on npm. The MCP server side never sees it because the IDE’s mcp.json uses npx -y, which auto-accepts. After 0.1.29 the MCP server pre-warms the CLI cache on every IDE launch, so a single Cursor / Claude Code restart silently catches both caches up and you stop seeing this prompt entirely. If you want to skip the prompt manually, use any of:

npx -y codeloop update          # auto-yes (same as the MCP server does)
npx codeloop@latest update      # version pin — npx never prompts on an explicit @version
npm install -g codeloop         # one-time global install; no npx needed afterwards

Tuning the CLI-cache pre-warm

The MCP server’s background pre-warm is throttled to once per hour per machine and is a no-op in CI / offline / opt-out environments. Set any of these env vars before launching Cursor / Claude Code:

• CODELOOP_FORCE_CLI_WARM=1— bypass the 1-hour cooldown and warm immediately on the next MCP launch. Useful when debugging Windows edge cases or when you just published a new CLI version yourself.
• CODELOOP_SKIP_CLI_WARM=1 — specifically disables this pre-warm but keeps the rest of CodeLoop running.
• CODELOOP_SKIP_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER=1 — disables the pre-warm and the passive CLI update notice.
• CI=true — auto-skipped, no env var needed.

Each warm cycle writes a tiny status file at ~/.codeloop/cli-warm-marker.jsonwith the timestamp of the last successful warm — delete it (or use the force flag) to re-run on demand. The file is written only after the background npx exits with code 0, so a failed warm always retries on the next launch instead of pretending it succeeded.

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.