Documentation structure for LLMs (llms.txt)
CircleCI Logo

Install and configure the Chunk CLI

24 days ago
Cloud

The chunk CLI is a developer tool that brings AI-powered code review and remote validation to your local workflow. The chunk CLI 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.

  • Trigger Chunk tasks in CircleCI Cloud from your terminal using chunk task.

  • 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, 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.

1. Installation

1.1 macOS and Linux install with Homebrew

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

$ brew install CircleCI-Public/circleci/chunk

1.2 Verify the installation

Confirm the chunk CLI is working and check the version:

$ chunk --version

2. Authentication

After installing the chunk CLI, set credentials for each service you plan to use. Authentication is required for some commands, such as chunk sidecar and chunk task.

2.1 CircleCI

Required for chunk sidecar and chunk task commands. The chunk CLI uses your CircleCI token to create and manage cloud sidecar environments for running remote validations.

$ chunk auth set circleci

Enter your CircleCI personal API token when prompted. Generate a personal API token from your User Settings 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.

$ chunk auth set anthropic

Enter your Anthropic API key when prompted. Generate an API key from the Anthropic console.

2.3 GitHub

Required for chunk build-prompt. The chunk CLI uses your GitHub token to mine PR review comments from your repository history.

$ 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:

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

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-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.

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, running validations, and installing skills, refer to How to Use the chunk CLI.

Update the Chunk CLI

Run the following command to update the chunk CLI:

$ brew upgrade chunk

Uninstall the Chunk CLI

To uninstall the chunk CLI, run the following command:

$ brew uninstall chunk

Manage credentials

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.

Next steps