> 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 that brings AI-powered code review and remote validation to your local workflow. It works with AI coding agents such as Claude Code, Cursor, and VS Code Copilot.

Some of the things you can do with the chunk CLI include:

*   Mine your team’s GitHub pull request history to generate a team-specific review prompt for AI agents using `chunk build-prompt`.
    
*   Validate commands locally or in CircleCI Cloud environments using `chunk validate`.
    
*   Install AI agent skills for code review, mutation testing, and CI failure debugging using `chunk skill install`.
    
*   Set up pre-commit and session-end hooks that automatically validate in Claude Code using `chunk init`.
    

**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/chunk-setup-and-overview/), the AI-powered CI/CD assistant in the CircleCI web app.

## Supported platforms

The `chunk` CLI supports macOS and Linux on both arm64 and x86\_64 architectures. Windows is not supported.

## Installation

### macOS and Linux install with Homebrew

The recommended installation method for both macOS and Linux is Homebrew:

`````````
$ brew install CircleCI-Public/circleci/chunk
`````````

### Verify the installation

Confirm the chunk CLI is working and check the version:

`````````
$ chunk --version
`````````

## Authentication

After installing the `chunk` CLI, set credentials for each service you plan to use.

### CircleCI

Required for `chunk sidecar` and `chunk task` commands.

`````````
$ chunk auth set circleci
`````````

Enter your CircleCI personal API token when prompted. Generate a personal API token from your [User Settings](https://app.circleci.com/settings/user/tokens) in the CircleCI web app.

### Anthropic

Required for `chunk build-prompt`.

`````````
$ 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).

### GitHub

Required for `chunk build-prompt`.

`````````
$ chunk auth set github
`````````

Enter a GitHub personal access token with `repo` scope when prompted.

### Check authentication status

To see which credentials you have configured:

`````````
$ chunk auth status
`````````

### Remove credentials

To remove stored credentials for a provider:

`````````
$ chunk auth remove <provider>
`````````

Replace `<provider>` with `circleci`, `anthropic`, or `github`.

## Initialize a project

Run `chunk init` in your project directory to configure chunk for that project:

`````````
$ 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.
    
*   Generates hook configuration in `.claude/settings.json` for Claude Code.
    

After initialization, `chunk validate` runs the detected commands and `chunk build-prompt` mines your GitHub PR history.

The following flags are available:

 

Flag

Description

`--force`

Overwrite an existing `.chunk/config.json`.

`--skip-hooks`

Skip generating hook configuration in `.claude/settings.json`.

`--skip-validate`

Skip command detection. Creates the config file without running command auto-detection.

`--project-dir <path>`

Set the project directory. Defaults to the current directory.

## Update the chunk CLI

`````````
$ brew upgrade chunk
`````````

## Uninstall the chunk CLI

`````````
$ brew uninstall chunk
`````````

## 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)
    
*   [Install AI Agent Skills](https://circleci.com/docs/guides/toolkit/how-to-use-chunk-cli/#install-skills)