> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt) # How to use the chunk CLI This page describes how to use the main features of the `chunk` CLI. ## Prerequisites * An installed and configured `chunk` CLI. See the [Install and Configure the Chunk CLI](https://circleci.com/docs/guides/toolkit/install-and-configure-the-chunk-cli/) page. * A project initialized with `chunk init`, or a `.chunk/config.json` file 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-prompt ````````` By 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 `--org` `--org my-org` Override the auto-detected GitHub organization. `--repos` `--repos api,web` Comma-separated list of repositories to analyze. Defaults to all repositories in the organization. `--top` `--top 10` Number of top reviewers to include. Default is five. `--since` `--since 2024-01-01` Start date for the analysis window in `YYYY-MM-DD` format. Default is three months ago. `--output` `--output .chunk/context/review-prompt.md` 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 validate ````````` `chunk validate` caches results by file content hash. Unchanged files skip re-execution on subsequent runs. To run a specific named command: ````````` $ chunk validate ````````` Replace `` with the name of the command as defined in `.chunk/config.json`. The following flags are available: Flag Description `--list` List all configured commands and their status. `--dry-run` Show the commands that would run, without executing them. `--force-run` Ignore the cache and run all commands regardless of file changes. `--sidecar-id ` Validate commands remotely in the specified Chunk sidecar. Get a Chunk sidecar ID from `chunk sidecar create` output or `chunk sidecar list`. ### 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](https://discord.com/invite/circleci). 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 ````````` 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](#manage-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](https://discord.com/invite/circleci). 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 create ````````` The `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. ### List Chunk sidecars ````````` $ chunk sidecar list ````````` Lists all your Chunk sidecars and their IDs. Use this to retrieve a Chunk sidecar ID if you need it after creation. ### SSH into a Chunk sidecar ````````` $ chunk sidecar ssh ````````` ### Sync local files to a Chunk sidecar ````````` $ chunk sidecar sync ````````` ### Execute a command in a sidecar ````````` $ chunk sidecar exec ````````` ## 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 install ````````` To see available skills and their current installation status run the following: ````````` $ chunk skill list ````````` The following skills are available: Skill Description `chunk-review` Reviews pull requests and diffs using your team’s review standards from `.chunk/context/review-prompt.md`. `chunk-sidecar` Creates and manages Chunk sidecar environments. `chunk-testing-gaps` Identifies test coverage gaps through mutation testing. `debug-ci-failures` 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 commit` if 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-validate ````````` ## View and set configuration To display the fully resolved `chunk` CLI configuration for your project run the following: ````````` $ chunk config show ````````` To set a configuration value: ````````` $ chunk config set ````````` Supported keys: Key Description `model` The default Claude model to use for `chunk build-prompt`. `apiKey` Your Anthropic API key. You can also set this with `chunk auth set anthropic`. ## Next steps * [Set up Chunk in the CircleCI Web App](https://circleci.com/docs/guides/toolkit/chunk-setup-and-overview/)