The CircleCI CLI
The CircleCI command line interface (CLI) brings CircleCI’s tooling to your terminal.
Quickstart
Follow these steps to authenticate and connect the CLI to your CircleCI project.
-
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 circlecior the appropriate command for your operating system and/or package manager. You can check your current version withcircleci --version. -
Log in to CircleCI:
circleci auth loginThis opens a browser window to complete authentication. Run
circleci auth meto confirm the login succeeded. -
Navigate to your project directory:
cd /path/to/your/project -
Link your project:
circleci project linkThis writes a
.circleci/info.ymlfile to your repository containing your project and organization IDs. Once linked, all project-scoped commands, such aspipeline list,run list,envvar list, andartifact, automatically resolve to the correct project without requiring a--projectflag.Running
circleci project linkis recommended for all and required if your organization slug starts withcircleci/rather thangh/orbb/. Without it, the CLI falls back to deriving the project from your git remote URL, which does not work for thecircleci/organization type and causes project-not-found errors. -
Try some commands:
List your recent runs:
circleci run listValidate your CircleCI config file:
circleci config validate -
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.
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.
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:
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:
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=1to disable all color output. -
Use
PAGERto control the pager used for long output (defaults toless). -
Use
DO_NOT_TRACK=1to 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
This section describes CLI v1. CLI v0 asks for your consent before it collects any telemetry.
The CLI collects Usage Data so we can understand how the CLI is used and so we can improve it. We analyze how people and AI coding agents set up and use features such as Smarter Testing. We call the collection of Usage Data by the CLI "Telemetry," which is enabled by default. Telemetry can be disabled by setting CI=true in the environment.
Usage Data is sent to CircleCI through Segment and Amplitude. Each processes Usage Data on our behalf.
For each command invocation, the CLI records the following:
-
The command path. For extensions such as
circleci testsuite, this includes the subcommand you ran. -
The names of the flags you used, but not their values.
-
The exit code.
-
The name of the AI coding agent that ran the command, if any.
-
Metadata: your CLI version, OS, a stable per-install device ID and, if you are signed in, your CircleCI user ID.
When you use Smarter Testing (circleci testsuite), the CLI also records the following:
-
Which setup checks failed.
-
Test counts and timings.
-
The name of the AI coding agent that ran the command, if any.
-
The CircleCI project ID and the repository name, which includes your organization name (for example,
my-org/my-repo). -
Device and user IDs that link runs together.
This Usage Data is used for internal business purposes only. Usage Data is not used to train AI models, and it does not include the contents of your code.
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
--helpto 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
referencetopic 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
chunkCLI works with AI coding agents such as Claude Code, Cursor, and VS Code Copilot.
Next steps
Using the CLI to complete common tasks is described across the docs. Some examples are:
-
Managing Contexts and environment variables.