--- title: "Install and configure the Chunk CLI" description: "How to install and configure the Chunk CLI, a tool for integrating AI code review standards and remote validation into your development workflow." doc_version: "unversioned" last_updated: "2026-08-20" --- > For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt) # Install and configure the Chunk CLI The [`chunk` CLI](https://github.com/CircleCI-Public/chunk-cli) is a developer tool for AI-assisted development workflows. It works with AI coding agents such as Claude Code, Cursor, and VS Code Copilot, and does two things: 1. **Generates team review context**: mines your GitHub PR review history, analyzes it with Claude, and produces a `.chunk/context/review-prompt.md` file that encodes how your team actually reviews code. AI coding agents pick this file up automatically and apply your team’s standards. 2. **Validates changes remotely**: runs your quality checks (tests, lint, format) in a clean CircleCI Cloud environment before you push, so you catch failures that only reproduce outside your machine. After following these steps, say "review my changes" in Claude Code to get a review against your team’s standards. Say "validate on the sidecar" to run checks in a CircleCI Cloud environment. **Chunk CLI vs Chunk by CircleCI.** The `chunk` CLI is a local developer tool. It is separate from [Chunk by CircleCI](https://circleci.com/docs/guides/toolkit/chunk-setup-and-overview/), the AI-powered CI/CD assistant in the CircleCI web app. ## 1\. Installation The `chunk` CLI supports macOS and Linux (arm64 and x86\_64). Windows is not supported. Install with Homebrew: ```console $ brew install CircleCI-Public/circleci/chunk ``` Verify the installation: ```console $ chunk --version ``` ## 2\. Authentication After installing the `chunk` CLI, set credentials for each service you plan to use. Some commands require authentication, such as `chunk sidecar` and `chunk task`. ### 2.1 CircleCI Required for `chunk sidecar` and `chunk task` commands. The `chunk` CLI uses your CircleCI credentials to create and manage cloud sidecar environments for running remote validations. The recommended method uses browser-based OAuth. If you already have a CircleCI account: ```console $ chunk auth login ``` If you are new to CircleCI: ```console $ chunk auth signup ``` Both commands open your browser for a secure login flow. If you prefer to use a personal API token instead: ```console $ chunk auth set circleci ``` Enter your CircleCI personal API token when prompted. Generate a token from your [User Settings](https://app.circleci.com/settings/user/tokens) in the CircleCI web app. ### 2.2 Anthropic Required for `chunk build-prompt`. The `chunk` CLI uses your Anthropic API key to analyze GitHub PR comments with Claude and generate team-specific review prompts. ```console $ chunk auth set anthropic ``` Enter your Anthropic API key when prompted. Generate an API key from the [Anthropic console](https://console.anthropic.com/settings/keys). ### 2.3 GitHub Required for `chunk build-prompt`. The `chunk` CLI uses your GitHub token to mine PR review comments from your repository history. ```console $ chunk auth set github ``` Enter a GitHub personal access token with `repo` scope when prompted. ## 3\. Initialize and validate a project ### 3.1 Initialize a project Run `chunk init` in your project directory to configure the `chunk` CLI for that project: ```console $ chunk init ``` `chunk init` performs these actions: * Detects your build, test, lint, and format commands. * Creates a `.chunk/config.json` file with the detected commands. * Installs shell completions. * Generates hook configuration in `.claude/settings.json` for Claude Code. * Installs AI agent skills into your coding agent. The following flags are available for `chunk init`: | Flag | Description | | --- | --- | | `--force` | Overwrite an existing `.chunk/config.json`. | | `--skip-hooks` | Skip generating hook configuration in `.claude/settings.json`. | | `--skip-git-hook` | Skip installing the git pre-commit hook. | | `--skip-skills` | Skip installing AI agent skills. | | `--skip-completions` | Skip installing shell completions. | | `--skip-validate` | Skip command detection. Creates the config file without auto-detecting commands. | | `--project-dir ` | Set the project directory. Defaults to the current directory. | ### 3.2 Validate your project After initialization, run `chunk validate` to run the detected commands. You can also run `chunk build-prompt` to mine your GitHub PR history for a team-specific review prompt. For detailed information on using the `chunk` CLI, including generating review prompts and running validations, refer to [How to Use the `chunk` CLI](https://circleci.com/docs/guides/toolkit/how-to-use-chunk-cli/). ## 4\. Install AI agent skills `chunk init` installs skills automatically, but you can also run `chunk skill install` directly at any time to install or reinstall skills into your AI coding agent (Claude Code, Cursor, or VS Code Copilot): ```console $ chunk skill install ``` To see available skills and their current installation status: ```console $ chunk skill list ``` The following skills are available: | Skill | Trigger phrases | Description | | --- | --- | --- | | `chunk-review` | "review my changes", "review PR #123" | Reviews pull requests and diffs using your team’s review standards from `.chunk/context/review-prompt.md`. | | `chunk-sidecar` | "validate on the sidecar", "sidecar dev loop" | Creates and manages Chunk sidecar environments for cloud validation. | | `chunk-testing-gaps` | "find testing gaps", "mutation test" | Identifies test coverage gaps through mutation testing. | | `debug-ci-failures` | "debug CI", "why is CI failing" | Debugs CircleCI pipeline failures and identifies flaky tests. | Once installed, invoke skills directly in your AI coding agent. In Claude Code, type `/chunk-review` to review a diff or `/chunk-sidecar` to validate changes in a CircleCI Cloud environment. ## Maintenance | Task | Command | | --- | --- | | Update the CLI | `brew upgrade chunk` | | Uninstall the CLI | `brew uninstall chunk` | | Check authentication status | `chunk auth status` | | Remove credentials for a provider | `chunk auth remove ` (`circleci`, `anthropic`, or `github`) | ## Next steps * [Generate a Team Review Prompt From Your GitHub PR History](https://circleci.com/docs/guides/toolkit/how-to-use-chunk-cli/#generate-a-review-prompt) * [Validate Your Changes](https://circleci.com/docs/guides/toolkit/how-to-use-chunk-cli/#run-validation) * [Trigger Chunk Tasks](https://circleci.com/docs/guides/toolkit/how-to-use-chunk-cli/#trigger-chunk-tasks)