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: ```bash npm install -g carrick carrick login cd ~/code carrick init ``` ## Authentication Carrick provides browser-based OAuth authentication with PKCE: ```bash 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//SKILL.md` and `.agents/skills//SKILL.md` (`carrick-impact`, `carrick-reuse`, `carrick-drift`, and `carrick-census`). See [task skills](/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](/building-the-index). To inspect the proposed configuration without writing files: ```bash 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: ```bash 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: ```bash 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-.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 ` 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: ```bash deno install --frozen --node-modules-dir=none ``` ### Monitoring background scans Check the progress of a running scan using `carrick status`: ```bash 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 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: ```bash carrick check path/to/file.ts carrick check path/to/file.ts --recheck carrick touch path/to/file.ts carrick status ``` - `carrick check `: Displays all routes, client calls, counterpart locations, and stored contract verdicts for the specified file. - `carrick check --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 `: 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 | 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 ` | Executes an agent lifecycle hook (`post-edit`, `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 [--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. | ## Remove Carrick To remove the local configuration created by `carrick init` and uninstall the CLI: ```bash 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 | 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_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_RECHECK_BUDGET_MS` | Maximum duration in milliseconds allowed for `carrick check --recheck` before falling back to cached index data. | ## Related - [Quickstart](/quickstart) walks through initial setup and repository onboarding. - [Building the index](/building-the-index) covers the scaffold prompt, the first scan, and the CI workflow. - [In your editor](/editor) details editor integration and LSP settings. - [Connecting your agent](/connecting-your-agent) explains agent hooks and MCP server configuration. - [carrick.json](/carrick-json) provides the complete schema for service definitions.