CLI

The carrick package carries the scanner, type sidecar, language server, Claude Code hooks and setup commands. It requires Node 24 or newer.

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

Sign in and out

carrick login opens a browser, authorises the Carrick CLI with PKCE and saves the resulting workspace credential in your operating system’s configuration directory. The command verifies the credential against your workspace before it succeeds. GitHub CLI credentials and GITHUB_TOKEN do not authenticate the Carrick CLI.

Set CARRICK_TOKEN when a non-interactive process needs an existing Carrick token. The environment value overrides the saved credential and is verified by carrick login and carrick init.

carrick login
carrick logout

carrick logout removes the saved local credential. It does not revoke the server-side key, and it does not unset CARRICK_TOKEN. Revoke a key from the Account page.

Derive and initialise a workspace

Run carrick init in a repository or in a folder whose immediate children are repositories. Rust derives the same service boundaries for setup, local indexing and CI. An existing carrick.json remains authoritative. When one is missing, init shows the proposed services and nearest compiler configuration before creating it once.

cd ~/code
carrick init

Init verifies the Carrick workspace, opens the repository connection page when a GitHub remote is not connected, writes missing per-repo configuration after confirmation, merges the Claude Code hooks and builds the first .carrick/ index. Re-running it preserves existing carrick.json bytes and other hooks.

An optional carrick-workspace.json can add repository paths with repos or exclude directory names with exclude. Init reads and preserves that file; it does not create one.

Preview the derived workspace without writing files or starting a scan:

carrick derive --workspace . --json

Use carrick init --skip-index to write the approved setup first, then run carrick index separately. Use --yes only after reviewing the same proposal interactively or with carrick derive.

Put a separate system in its project

Run init with a project slug when every proposed GitHub repository belongs to one named Carrick project:

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

The command lists the repositories and their current assignments, prints the Projects, GitHub App and Repos links, then opens the workspace Projects page in an interactive terminal. Create the project in the browser if needed, connect its repositories, and move the selected repositories to that project. The CLI reads resolve-repos until every proposed repository is connected and reports the requested project_slug; it does not create a project or change an assignment.

Init writes no local setup until it verifies every proposed repository in the requested project. A repository assigned to another project remains pending, and a proposal without a GitHub origin fails before the browser handoff. In a non-interactive shell, an unmet target prints the same links and exits with status 1 without writing. Project slugs contain 3–32 lowercase letters, digits and single hyphens.

Build and refresh the local index

carrick index
carrick refresh
carrick refresh --service api

index derives the workspace and rebuilds its local read model. refresh accepts the same workspace and service model, and --service narrows the scan before Carrick rejoins the complete workspace.

Both commands read the hosted index with the saved Carrick credential. Hosted candidates enrich matching repos at their indexed commit, while files changed in the working tree keep deterministic facts and withhold stale candidate rows. Repositories in the same Carrick project can contribute counterparts even when they are not checked out locally.

Large hosted responses use a short-lived staged HTTPS download automatically. The CLI validates and follows that URL during the read, and there is no separate staging command; the read only downloads.

Today the scan that produces the hosted rows runs in the GitHub Action, so index and refresh reflect the last successful default-branch run. From 0.3.60, carrick init runs that scan with inference from your own machine and uploads the result under the saved Carrick credential, while index and refresh stay the hosted read.

If the hosted read fails, the command reports the failure and may use the last credential-bound hosted snapshot. carrick status and carrick check state the resulting hosted provenance instead of contacting the network themselves.

Read the index

carrick check path/to/file.ts
carrick touch path/to/file.ts
carrick status

check prints the routes and calls for one file, their counterparts and the stored contract verdicts. touch prints the same indexed relationships without verdicts. status reports every indexed service, its source commit, changed-file count and hosted enrichment state.

These commands read .carrick/ and write nothing. Add --json for the versioned machine-readable response. The schemas and exit-code rules are pinned in local mode output.

Other commands

Command	Behaviour
carrick lsp --stdio	Start the language server used by the editor extension and other LSP clients
carrick hook post-edit	Read a Claude Code PostToolUse payload from standard input and answer from the local index
carrick hook session-start	Print the workspace index summary for a new or resumed Claude Code session
carrick templates workflow	Print the canonical GitHub Actions workflow
carrick <path>	Run the full scanner path used by the GitHub Action

Related

• Quickstart covers the full setup sequence.
• In your editor covers extension installation and surface settings.
• Connecting your agent covers hooks and hosted MCP access.