CLI

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

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 (@carrick-tools/cli-<platform>-<arch>), avoiding postinstall build scripts and supporting --ignore-scripts. Dependency preparation and type checking during indexing can download registry packages, and index and refresh can also download authenticated hosted indexes.

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 revokes this machine’s key on the server, then removes the locally stored workspace credentials. Other machines and editor connections stay signed in. If Carrick cannot be reached, the credentials are still removed and the command says the key is still live. It does not unset environment variables.

carrick login stores the workspace credential in $XDG_CONFIG_HOME/carrick/credentials.json, falling back to ~/.config/carrick/ on macOS and Linux or %APPDATA%\carrick\ on Windows, with file mode 0600. 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.

Updates

Every command reads a cached answer to whether a newer carrick exists, refreshes it in the background, and prints the update command for the way this copy was installed. The check never blocks on the network. Set CARRICK_NO_UPDATE_CHECK=1 to turn it off for a reproducible run.

When you run Carrick through npx and an older global carrick exists, Carrick brings that global level with the version you ran, because the global answers your agent’s hooks and every new shell. It uses the package manager that owns the global and nothing that overrides your own npm configuration. On a machine with no global, carrick init asks before installing one, and carrick init --install-global gives that answer in a script. In CI the check warns and continues, so a workflow decides its own version, and carrick-tools/carrick@v1 in a workflow already moves to each release.

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 hooks run carrick hook post-edit on file edits to deliver instant diagnostics, and carrick hook post-read when the agent reads a file, to surface its callers and file dependencies. 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.

carrick init writes nothing, on this machine or in Carrick, until you accept what it proposes. It asks in this order:

The repositories this install covers.
The project the selected repositories belong in.
The proposal, which names the packages found, the repositories covered, any project to create, and any repository that would move out of the project it is in now.

Answering no, or pressing Ctrl-C at any question, ends the run with nothing written. In a folder of repositories with neither a terminal nor --repo, init stops without writing anything, and --yes covers all of them.

init prints one line per action, marked ◇ when done, ▲ for a warning that says what to do, and ■ for something it could not do and why. Without a terminal (CI, an agent’s shell, a pipe) it writes the same lines as plain text, with no colour and no spinner.

Each repository is identified by its origin remote. A remote written through a per-account SSH host alias ([email protected]:owner/repo.git) is resolved with ssh -G, so an alias whose HostName is github.com counts as an ordinary GitHub repository. When a remote still names no GitHub repository, init says which repository it was and leaves it out of the project and connection steps. A --repo owner/repo value that matches no repository in the folder attaches to the one repository there that has no identity.

An optional carrick-workspace.json adds repository paths through repos and removes directory names through exclude. A repository you leave out of the selection is written into exclude, so later scans, the editor hooks and the next init leave it alone, and carrick remove takes back only the names init added. A --repo value naming an excluded repository is refused, with the file that excludes it.

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.

index and refresh replay hosted answers for unchanged files when the hosted commit is available locally and cache versions match. Changed files keep their local facts while their hosted model answers are withheld, and no model runs on your machine.

On macOS, index, resume and refresh keep the machine from idle-sleeping until the scan finishes, for at most three hours, and print one line saying so. Closing the lid still puts it to sleep. Pass --no-keep-awake or set CARRICK_NO_KEEP_AWAKE=1 to let it sleep.

A Claude Code session opened in a workspace still waiting for its first hosted index starts carrick refresh in the background, at most once an hour. Set CARRICK_REFRESH_COOLDOWN_MS to change that interval.

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.

These commands read .carrick/ and write nothing. Add --json to any inspection command to receive structured JSON output, in the shape pinned in docs/local-mode-output.md.

Additional commands

Command	Action
`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 --stdio`	Starts the Language Server Protocol process used by editor extensions and LSP clients.
`carrick hook <name>`	Executes an agent lifecycle hook (`post-edit`, `post-read`, `session-start`, `stop`, `user-prompt`).
`carrick templates workflow`	Outputs the standard GitHub Actions workflow definition.
`carrick templates carrick.json`	Outputs a single-service configuration skeleton.
`carrick index --allow-unprepared`	Scans a repository even if package dependencies are uninstalled.
`carrick index --no-keep-awake`	Lets the machine idle-sleep during the scan. Also accepted by `resume`, `refresh` and `carrick <path>`.
`carrick <path> [--no-cache] [--allow-unprepared]`	Executes the full scanner binary as used in CI environments.
`carrick index -v`	Enables verbose scanner debug output.
`carrick --version`	Displays the installed CLI version.

Check the setup

carrick doctor re-reads the decisions made once at setup, such as which directories are services, which shared roots they include and which tsconfig resolves their types. CI rebuilds the index on every push to the default branch, but nothing rebuilds the configuration. The command exits non-zero when it finds a problem, and checks that:

Every directory, include and tsconfig a carrick.json declares exists.
.github/workflows/carrick.yml still holds the current template, printed as a diff of the lines it is missing. Comments are not compared, and steps of your own are shown but are not a finding.
The agent hook entries are the ones this version installs, and the command they run still resolves to this package.
Each agent client on this machine has the Carrick MCP server.
The hosted index answers for every service, with the local index’s distance from the working tree and from the default branch as notes.

carrick doctor writes nothing and runs no scan.

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.

Other hooks, other MCP servers and the settings files themselves stay. An MCP server called carrick that points anywhere other than api.carrick.tools is left alone and reported. Pass --workspace DIR to name a folder other than the current one. Running it twice is safe, and the second run says there is nothing left to remove. It also names the sections only their owner can unpick, which are the ## Carrick section of an AGENTS.md, the hook-pack entries in a committed .claude/settings.json, and the .claude negations in .gitignore. Revoking the key itself is a separate action, on the Account page.

Environment variables

Variable	Description
`CARRICK_TOKEN`	Overrides locally stored authentication credentials with an explicit API token.
`CARRICK_WORKSPACE`	Overrides the target workspace root directory.
`CARRICK_NO_UPDATE_CHECK`	Set to `1` to disable checking for newer CLI versions.
`CARRICK_ALLOW_UNPREPARED`	Set to `1` to scan repositories without installed package dependencies.
`CARRICK_NO_KEEP_AWAKE`	Set to `1` to let the machine idle-sleep during a scan.
`CARRICK_ALLOW_PARTIAL_ANALYSIS`	Set to `1` to upload index data when some services have incomplete model analysis.
`CARRICK_ALLOW_MISSING_TYPES`	Set to `1` to index operations even if TypeScript type extraction fails.
`CARRICK_REFRESH_COOLDOWN_MS`	Minimum interval in milliseconds between the background `carrick refresh` runs a Claude Code session starts while waiting for a hosted index. Defaults to one hour.
`CARRICK_RECHECK_BUDGET_MS`	Maximum duration in milliseconds allowed for `carrick check --recheck` before falling back to cached index data.

Quickstart walks through initial setup and repository onboarding.
Building the index covers the scaffold prompt, the first scan, and the CI workflow.
In your editor details editor integration and LSP settings.
Connecting your agent explains agent hooks and MCP server configuration.
carrick.json provides the complete schema for service definitions.