Documentation structure for LLMs (llms.txt)
CircleCI Logo

The CircleCI CLI

1 day ago
Cloud Server

The CircleCI command line interface (CLI) brings CircleCI’s tooling to your terminal.

Using CircleCI Server? CLI v1 is not supported for CircleCI Server. Install CLI v0 instead. See Install CLI v0 for CircleCI Server.

Quickstart

Follow these steps to authenticate and connect the CLI to your CircleCI project.

  1. Install the CircleCI CLI: Visit the CircleCI CLI page for installation instructions.

    If you currently have the legacy stable release installed (v0.1.x) you must uninstall this before installing CLI v1. For example, brew uninstall circleci or the appropriate command for your operating system and/or package manager. You can check your current version with circleci --version.

  2. Log in to CircleCI:

    circleci auth login

    This opens a browser window to complete authentication. Run circleci auth me to confirm the login succeeded.

  3. Navigate to your project directory:

    cd /path/to/your/project

  4. Link your project:

    circleci project link

    This writes a .circleci/info.yml file to your repository containing your project and organization IDs. Once linked, all project-scoped commands, such as pipeline list, run list, envvar list, and artifact, automatically resolve to the correct project without requiring a --project flag.

    Running circleci project link is recommended for all and required if your organization slug starts with circleci/ rather than gh/ or bb/. Without it, the CLI falls back to deriving the project from your git remote URL, which does not work for the circleci/ organization type and causes project-not-found errors.

  5. Try some commands:

    List your recent runs:

    circleci run list

    Validate your CircleCI config file:

    circleci config validate

  6. Enter the interactive terminal UI for inspecting CI runs.

    circleci run get

Features of the CircleCI CLI

The following sections highlight some features of the CircleCI CLI.

Secure OAuth authentication

Log in with a short browser-based auth flow. Tokens are stored in your credential management system so no manual token generation or pasting is required.

Log in with a short browser-based auth flow and store tokens in your credential management system.
circleci auth login    # opens a browser window to complete authentication
circleci auth me       # confirm the logged-in identity
circleci auth logout   # log out and remove stored credentials

Interactive run inspection

Use circleci run get to open an interactive terminal UI for inspecting CI runs. Access all the following without opening a browser:

  • Navigate from a run into its workflows, jobs, and steps.

  • Page through step output.

  • Jump to failed tests.

Browse recent runs interactively.
circleci run list              # list recent runs for the linked project
circleci run get               # browse recent runs interactively
circleci run get <run-id>      # open a specific run directly

From inside the TUI, use arrow keys to navigate, Enter to drill in, and Esc or q to go back.

Agent-ready

A built-in MCP server lets AI agents inspect CI runs, retrieve test results, and diagnose failures without leaving the agent’s context. Enable it for your editor with one command:

Enable MCP server for your editor.
circleci mcp claude enable    # Claude Desktop
circleci mcp cursor enable    # Cursor
circleci mcp vscode enable    # VS Code

To disable, replace enable with disable. You can also start the server manually with circleci mcp start, or stream it over HTTP with circleci mcp stream.

Readable output

Every command renders a formatted markdown report in the terminal. For scripting and data processing, all commands support --json for machine-readable output and --jq for inline filtering:

Generate machine-readable output and inline filtering.
circleci run list --json                        # full JSON output
circleci run list --jq '.[0].id'               # extract the most recent run ID
circleci job get <job-id> --jq '.status'       # get the status of a specific job

Modern terminal interface

The CLI respects standard terminal conventions:

  • Use NO_COLOR=1 to disable all color output.

  • Use PAGER to control the pager used for long output (defaults to less).

  • Use DO_NOT_TRACK=1 to disable telemetry (see also Telemetry).

  • Output formatting adjusts automatically when the CLI is not connected to a terminal. For example, the CLI strips both color and interactive elements when you pipe output to another command or run the CLI in a CI pipeline.

Telemetry

The CLI collects usage data to help improve the tool. Telemetry is enabled by default. For each command invocation, the CLI records the command path and the flags passed, along with metadata including your CLI version, OS, and a stable per-install device ID. Telemetry is automatically disabled when CI=true is set in the environment.

To disable telemetry permanently, run:

circleci setting set telemetry off

You can also disable it for a session using any of these environment variables:

  • CIRCLE_NO_TELEMETRY=1

  • DO_NOT_TRACK=1

  • NO_ANALYTICS=1

The CLI reference

You can find the full CircleCI CLI reference at CircleCI CLI reference.

You can also access reference information directly in your terminal in three ways:

  • Add --help to any command at any depth to see its description, flags, and examples:

    circleci --help
circleci run --help
circleci run list --help

  • Use circleci help <command> to see the description, flags, and examples for a specific command:

    circleci help run
circleci help run list

  • Use circleci help <topic> to see prose reference articles on specific subjects:

    circleci help getting-started
circleci help environment
circleci help telemetry
circleci help formatting

  • The reference topic generates a full dump of every command and flag in the CLI at runtime:

    circleci help reference

Migration from the legacy CLI

To help you migrate from the legacy CLI (v0.1.x) to the CircleCI CLI v1, see the CLI Migration Guide.

Share feedback

If you have any feedback or suggestions for the CircleCI CLI, or to report an issue, open an Issue on the GitHub repository.

Explaining CircleCI’s CLI offerings

The CircleCI CLI

The development tool used on your local machine for day-to-day development tasks. It handles testing and local workflow management.

The CircleCI environment CLI

A specialized command-line interface that retrieves and configures a task. It manages the execution of the job within a chosen compute environment.

The Chunk CLI

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.

Install CLI v0 for CircleCI Server

CLI v1 works with CircleCI Cloud only. If you use CircleCI Server, install CLI v0 instead using one of the following methods.

What you can do with CLI v0

The following table summarizes the top-level commands available in CLI v0.

Command What it does

config

Validate, pack, and process build config files.

context

Secure and share environment variables across projects.

diagnostic

Check the status of your CircleCI CLI.

info

Check information associated with your user account.

local

Debug and run jobs on your local machine.

namespace

Operate on orb namespaces.

orb

Create, publish, validate, and manage orbs.

pipeline

Operate on pipelines.

policy

Manage security policies.

project

Operate on projects.

runner

Operate on self-hosted runners.

setup

Set up the CLI with your credentials.

telemetry

Configure telemetry preferences.

trigger

Operate on triggers.

version

Display version information.

The table does not cover every command. Run circleci-v0 --help to see the full command list.

Install with Homebrew

If you use Homebrew on macOS or Linux, install CLI v0 with the following command:

brew install circleci-public/circleci/circleci@v0

This installs a circleci-v0 binary, so it can coexist with a CLI v1 circleci installation.

Install with the install script

On macOS and Linux, set the VERSION environment variable to pin the install script to the latest v0 release:

VERSION=0.1.47860 curl -fsSL https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/main/install.sh | bash

This installs a circleci-v0 binary to /usr/local/bin by default.

Manual install

Download the archive for your platform, including Windows, from the v0.1.47860 release page on GitHub.

Set up CLI v0 for your Server host

After installing CLI v0, point it at your Server installation.

  1. Run the setup command:

    circleci-v0 setup

  2. When prompted, provide the following:

    • A personal API token from your Server web app. Go to User Settings  Personal API Tokens to create one.

    • Your Server host URL, for example https://circleci.example.com. Do not use https://circleci.com.

      CLI v0 saves this configuration to ~/.circleci/cli.yml.

  3. Confirm the CLI can reach your Server host:

    circleci-v0 diagnostic
To run setup without interactive prompts, for example from a script, use circleci-v0 setup --no-prompt --host <your-server-url> --token <your-token>.

If you also use the CircleCI CLI for Cloud, keep the two separate. Run circleci auth login to authenticate CLI v1 with Cloud, and circleci-v0 setup to authenticate CLI v0 with Server.

Troubleshoot CLI v1 replacing your CLI v0 install

Homebrew or the CLI’s own update check can upgrade a circleci binary to CLI v1 without you asking for it. If circleci used to be your CLI v0 install, that upgrade breaks Server access, because CLI v1 does not work against a Server host. A typical sign is a Server command that used to work but now fails. The error is often a missing API route, or an authentication method that only exists for Cloud.

You do not need to uninstall CLI v1 to fix this. Install CLI v0 alongside it using the Homebrew or install script method described earlier on this page. This adds a separate circleci-v0 binary without touching your existing circleci install. From then on, run Server commands with circleci-v0 instead of circleci.

If a machine only ever connects to Server and you would rather run a single CLI, you can uninstall CLI v1 once CLI v0 is working. For example, brew uninstall circleci or brew uninstall --cask circleci@next, depending on how CLI v1 was installed.

Reference documentation for CLI v0

CLI v0 does not have a hosted reference site. Add --help to any circleci-v0 command at any depth to see its description, flags, and examples:

circleci-v0 --help
circleci-v0 config --help

Next steps

Using the CLI to complete common tasks is described across the docs. Some examples are:

  • Managing Contexts and environment variables.