How to use the chunk CLI
This page describes how to use the main features of the chunk CLI.
Prerequisites
-
An installed and configured
chunkCLI. See the Install and Configure the Chunk CLI page. -
A project initialized with
chunk init, or a.chunk/config.jsonfile with commands configured.
Generate a team review prompt
The chunk build-prompt command mines your GitHub pull request review history and uses Claude to generate a team-specific review prompt. The prompt captures your reviewers' patterns and preferences so that AI coding agents apply your team’s standards when reviewing code.
The command saves the generated prompt to .chunk/context/review-prompt.md, which the chunk-review skill uses automatically.
From your project directory:
$ chunk build-promptBy default, chunk build-prompt:
-
Targets the GitHub organization detected from your git remote.
-
Analyzes the top five most active reviewers.
-
Looks back three months from the current date.
You can customize this behavior with the following flags:
| Flag | Example | Description |
|---|---|---|
|
|
Override the auto-detected GitHub organization. |
|
|
Comma-separated list of repositories to analyze. Defaults to all repositories in the organization. |
|
|
Number of top reviewers to include. Default is five. |
|
|
Start date for the analysis window in |
|
|
Path where the command saves the generated prompt. |
Validate your changes
The chunk validate command runs the commands configured in your project’s .chunk/config.json. Use it to verify your changes pass all quality checks before pushing.
$ chunk validatechunk validate caches results by file content hash. Unchanged files skip re-execution on subsequent runs.
To run a specific named command:
$ chunk validate <name>Replace <name> with the name of the command as defined in .chunk/config.json.
The following flags are available:
| Flag | Description |
|---|---|
|
List all configured commands and their status. |
|
Show the commands that would run, without executing them. |
|
Ignore the cache and run all commands regardless of file changes. |
|
Validate commands remotely in the specified Chunk sidecar. Get a Chunk sidecar ID from |
Validate in a Chunk sidecar
| Chunk sidecars are available in preview if you are on a paid plan. The product is in its early stages and you may encounter bugs, unexpected behavior, or incomplete features. If you have feedback, you can share it on our Discord. When the feature is made generally available, there will be a cost associated with access and usage. |
To validate in a CircleCI Cloud environment instead of locally, pass a Chunk sidecar ID:
$ chunk validate --sidecar-id <sidecar-id>To get a Chunk sidecar ID, run chunk sidecar create and copy the ID printed when the environment is ready, or run chunk sidecar list to retrieve the ID of an existing Chunk sidecar. See the Manage Chunk sidecars section for details.
Manage Chunk sidecars
| Chunk sidecars are available in preview if you are on a paid plan. The product is in its early stages and you may encounter bugs, unexpected behavior, or incomplete features. If you have feedback, you can share it on our Discord. When the feature is made generally available, there will be a cost associated with access and usage. |
Chunk sidecars are CircleCI Cloud environments where the chunk CLI validates your changes remotely. This lets you validate changes against the same environment your CI pipeline uses, without running them locally.
Create a Chunk sidecar
$ chunk sidecar createThe chunk CLI auto-detects your tech stack, generates a Dockerfile, and provisions a cloud environment on CircleCI. The command prints the Chunk sidecar ID when the environment is ready. Use this ID with chunk validate --sidecar-id to run validations in that environment.
Install AI agent skills
The chunk skill install command installs chunk CLI skills into your AI coding agent (Claude Code, Cursor, or VS Code Copilot).
$ chunk skill installTo see available skills and their current installation status run the following:
$ chunk skill listThe following skills are available:
| Skill | Description |
|---|---|
|
Reviews pull requests and diffs using your team’s review standards from |
|
Creates and manages Chunk sidecar environments. |
|
Identifies test coverage gaps through mutation testing. |
|
Debugs CircleCI pipeline failures and identifies flaky tests. |
After installation, you can invoke these skills directly in your AI coding agent. For example, in Claude Code, type /chunk-review to start a code review.
Configure validation hooks
Running chunk init adds hooks to .claude/settings.json that trigger chunk validate automatically at key points:
-
PreToolUse hook: Blocks
git commitif validation fails, preventing bad code from entering the repository. -
Stop hook: Validates your changes when your Claude Code session ends, catching uncommitted changes.
To add or update hooks without re-running the full initialization run the following:
$ chunk init --skip-validateView and set configuration
To display the fully resolved chunk CLI configuration for your project run the following:
$ chunk config showTo set a configuration value:
$ chunk config set <key> <value>Supported keys:
| Key | Description |
|---|---|
|
The default Claude model to use for |
|
Your Anthropic API key. You can also set this with |