Guides

CLI

Reference for Carrick login, workspace setup, the scan that builds the index, refreshes, file checks and status output.

Updated  ·  view as markdown

The carrick CLI provides workspace initialisation, static analysis, index synchronization, diagnostics, and Language Server Protocol (LSP) capabilities.

Carrick requires Node 24 or newer to execute the sidecar that resolves TypeScript request and response types. The package includes the Rust scanner binary, the type sidecar, the Language Server Protocol (LSP) server, and agent hooks. The scanner binary installs as a platform-specific optional dependency, avoiding postinstall build scripts and supporting --ignore-scripts.

Install the CLI, sign in, and initialise your workspace:

npm install -g carrick
carrick login
cd ~/code
carrick init

Authentication

Carrick provides browser-based OAuth authentication with PKCE:

carrick login
carrick logout
  • carrick login opens a browser window to authorise your CLI with your Carrick workspace and stores the credentials locally.
  • carrick logout removes locally stored workspace credentials. It does not revoke the remote API key or unset environment variables.

carrick login stores the workspace credential in your operating system’s configuration directory. Note that GitHub CLI credentials and GITHUB_TOKEN do not authenticate Carrick. If you run carrick init on a machine without stored credentials, the CLI launches the sign-in flow automatically.

In non-interactive environments or automated scripts, set the CARRICK_TOKEN environment variable to authenticate with an existing Carrick API key. With CARRICK_TOKEN set, carrick login verifies that token instead of opening the browser.

Workspace initialisation

Run carrick init in a single repository or in a directory containing sibling repositories:

carrick init [DIRECTORY] [--repo OWNER/REPO]... [--project SLUG] [--mcp EDITOR] [--allow-move]

    -w, --workspace DIR  The folder holding the repos (default: this one)
        --repo OWNER/REPO  A repo this install covers: repeatable, or one
                         comma-separated list. In a folder of repos without a
                         terminal to choose in, this is required. It also names
                         the GitHub repo whose origin remote names none
        --project SLUG   Put those repos in this Carrick project, creating it
                         if it is not there. A repo that is in another project
                         is MOVED out of it, which changes what every agent
                         querying either project can see, so the move is named
                         and asked about separately
        --allow-move     Accept those moves without being asked. --yes does not
        --mcp EDITOR     Also add Carrick to this editor's own MCP configuration,
                          which is a file outside this workspace: repeatable, or one
                          comma-separated list. Without a terminal no editor file is
                          written unless this names one, and --yes does not name one
    -y, --yes            Take the proposal as printed
        --install-global Install carrick on this machine where there is none,
                         so the agent hooks can run it by name after this run
                         ends. A terminal is asked instead; --yes is not this

When run in a directory of sibling repositories, carrick init prompts you to select repositories, discovers services across package manifests, and writes:

  • .carrick/proposal.json: Contains the detected service layout. This directory includes its own .gitignore so local proposal state remains uncommitted.
  • Claude Code hook settings: Merged into .claude/settings.json (or .claude/settings.local.json if carrick is not on PATH). The PostToolUse hook runs carrick hook post-edit on file edits to deliver instant diagnostics, and the SessionStart hook runs carrick hook session-start to refresh index state.
  • Task skills: Installs four standardized agent skills in .claude/skills/<name>/SKILL.md and .agents/skills/<name>/SKILL.md (carrick-impact, carrick-reuse, carrick-drift, and carrick-census). See task skills.
  • carrick-workspace.json: Records excluded repositories so subsequent scans ignore them.
  • .codex/hooks.json: Configures edit recording and reuse checks for Codex environments.
  • MCP configuration: Configures Claude Code via claude mcp add and prompts to configure detected editors such as Cursor, Windsurf, or VS Code.

If the repositories are already indexed in Carrick Cloud, carrick init downloads the index directly into .carrick/. It writes no carrick.json and runs no scan; your agent writes the config from the proposal, as described in Building the index.

To inspect the proposed configuration without writing files:

carrick derive --workspace .

Project boundaries and repository linking

Repositories that interact with one another belong in the same project. Use the --project flag to specify or create a project slug:

cd ~/code/second-system
carrick init --project second-system

During initialisation, Carrick links repositories to your workspace via the Carrick GitHub App. The CLI opens the authorization URL in your browser and polls until approval completes.

A workspace owner or admin must complete this grant. If you cancel the wait with Ctrl-C, local setup continues, and you can verify the connection later by re-running carrick init.

Building and synchronising the index

Use the following commands to compile or update the Carrick index:

carrick index
carrick index --detach
carrick index --dispatch
carrick resume
carrick refresh
carrick refresh --service api
  • carrick index: Scans files declared in carrick.json, extracts routes, calls, and types, and uploads the compiled index to Carrick Cloud.
  • carrick index --detach: Runs the scan in a detached background process and outputs a scan ID with a log path (.carrick/scan-<id>.log). This is recommended for AI agents to avoid command timeout caps.
  • carrick index --dispatch: Submits files for cloud analysis as an asynchronous job without waiting for completion. Run carrick resume subsequently to retrieve the compiled index.
  • carrick refresh: Re-runs local deterministic extraction and downloads updated classification rows from Carrick Cloud without running remote models or uploading. Use --service <name> to limit extraction to a single service before re-joining workspace contracts.

For Deno workspaces, ensure Deno 2.9.4 or newer is installed and prepare the module graph before scanning:

deno install --frozen --node-modules-dir=none

Monitoring background scans

Check the progress of a running scan using carrick status:

carrick status

carrick status reports active scan progress, file counts, and completion status:

  • Active progress reports the current indexing phase and processed file counts (e.g. scan 5089ed60 running for 3m12s: indexing gateway — 118 of 240 files).
  • Completion reports finished scans (e.g. scan <id> finished after 14m22s. The index is written.).
  • Interrupted or failed scans report error details directly.

Inspecting local contracts

Query the local index for file-level and workspace-level contract status:

carrick check path/to/file.ts
carrick check path/to/file.ts --recheck
carrick touch path/to/file.ts
carrick status
  • carrick check <file>: Displays all routes, client calls, counterpart locations, and stored contract verdicts for the specified file.
  • carrick check <file> --recheck: Re-extracts and re-evaluates the specified file against the existing index within a 10-second budget (configurable via CARRICK_RECHECK_BUDGET_MS), verifying uncommitted working-tree changes without contacting the network.
  • carrick touch <file>: Lists indexed routes and calls for a file without computing contract verdicts.
  • carrick status: Lists indexed services, last-scanned commit hashes, and local modified file counts.

Add --json to any inspection command to receive structured JSON output.

Additional commands

CommandAction
carrick derive --workspace .Prints the detected repository and service proposal without modifying files or running scans.
carrick doctor [DIRECTORY]Inspects configuration paths, CI workflows, agent hooks, and skill file digests, reporting any discrepancies.
carrick remove [--keep-login]Removes local .carrick directories, agent hooks, MCP registrations, and credentials while preserving tracked repository files.
carrick lsp --stdioStarts the Language Server Protocol process used by editor extensions and LSP clients.
carrick hook <name>Executes an agent lifecycle hook (post-edit, session-start, stop, user-prompt).
carrick templates workflowOutputs the standard GitHub Actions workflow definition.
carrick templates carrick.jsonOutputs a single-service configuration skeleton.
carrick index --allow-unpreparedScans a repository even if package dependencies are uninstalled.
carrick <path> [--no-cache] [--allow-unprepared]Executes the full scanner binary as used in CI environments.
carrick index -vEnables verbose scanner debug output.
carrick --versionDisplays the installed CLI version.

Remove Carrick

To remove the local configuration created by carrick init and uninstall the CLI:

carrick remove
npm uninstall -g carrick

carrick remove removes local hook entries, unregisters the MCP server from local agent configs, deletes .carrick/, and clears local credentials. Tracked repository files such as carrick.json and .github/workflows/carrick.yml remain under version control, and the CLI prints git rm commands if you choose to delete them.

Environment variables

VariableDescription
CARRICK_TOKENOverrides locally stored authentication credentials with an explicit API token.
CARRICK_WORKSPACEOverrides the target workspace root directory.
CARRICK_NO_UPDATE_CHECKSet to 1 to disable checking for newer CLI versions.
CARRICK_ALLOW_UNPREPAREDSet to 1 to scan repositories without installed package dependencies.
CARRICK_ALLOW_PARTIAL_ANALYSISSet to 1 to upload index data when some services have incomplete model analysis.
CARRICK_ALLOW_MISSING_TYPESSet to 1 to index operations even if TypeScript type extraction fails.
CARRICK_RECHECK_BUDGET_MSMaximum duration in milliseconds allowed for carrick check --recheck before falling back to cached index data.
all docs raw markdown llms-full.txt dashboard