Getting started with the CircleCI CLI
Content Marketing Manager
The CircleCI CLI brings CI into your terminal, where developers and coding agents can work with it directly. You can set up projects, trigger and monitor pipelines, investigate failures, retrieve test results and artifacts, manage project settings, and more. Agents can use the CLI through shell commands or its built-in MCP server, giving them the tools and context to validate changes, diagnose failures, and try again without switching to a browser.
This tutorial covers how to install the CLI, connect a project, and use the commands that give coding agents direct access to CI. A deliberately broken demo project shows the commands agents can use to monitor builds, retrieve failure context, investigate problems, and validate changes, all without leaving their development environment.
Using the CLI with coding agents
Coding agents with shell access can use the CLI directly, without additional integrations. Commands return structured JSON, exit codes, and condensed failure reports, giving agents the information they need without parsing lengthy logs or navigating the CircleCI web app.
The CLI supports agents such as Claude Code, Codex, and Gemini CLI, and other tools can identify themselves with the AI_AGENT environment variable.
Agents can use the CLI throughout the development cycle: pushing changes, monitoring builds, investigating failures, and validating fixes. Structured output and targeted failure context help them move through the loop without developers having to retrieve CI results manually. When a build fails, they can retrieve a consolidated failure report, request additional context when needed, and continue working toward a passing build. Developers can use the same commands directly to inspect or troubleshoot CI.
Connecting agents through MCP
The CLI also includes a built-in Model Context Protocol (MCP) server that exposes its commands as native agent tools. Rather than executing shell commands, agents can use MCP to check pipeline status, retrieve failure reports, inspect test results, trigger runs, and manage other CircleCI resources.
You can enable it for supported editors with a single command:
circleci mcp cursor enable # Cursor
circleci mcp vscode enable # VS Code
circleci mcp claude enable # Claude Desktop
The MCP server runs locally using your existing CLI authentication. Agents can interact with CircleCI through MCP tools or shell commands, depending on their environment. The examples below use shell commands to demonstrate the underlying capabilities.
See Connecting to the CircleCI CLI MCP for additional setup options.
Installing the CLI
Agents use whichever circleci binary is installed where they run, so install the CLI on that machine.
On macOS or Linux with Homebrew:
brew install circleci
On Debian or Ubuntu:
curl -1sLf 'https://packages.circleci.com/public/setup.deb.sh' | sudo -E bash
sudo apt install circleci
On Fedora or RHEL:
curl -1sLf 'https://packages.circleci.com/public/setup.rpm.sh' | sudo -E bash
sudo dnf install circleci
For Windows, Snap, and other options, see the install instructions on GitHub. To check the install, print the version:
circleci version
Replacing the legacy CLI
If a CircleCI CLI was already installed on your machine, check the version printed above. A version that starts with 0.1 is the legacy CLI, and it has to come off before the current one can take its place. Uninstall it with the package manager that installed it, for example brew uninstall circleci, then run the install command again. The migration guide lists the commands that changed. The current CLI (v1) supports CircleCI Cloud. CircleCI Server users should continue using CLI v0.
Signing in and setting up a project
To sign in to an existing CircleCI account:
circleci auth login
The CLI prompts for a CircleCI host and authentication method. Browser authentication opens a page to select an access level and authorize the CLI. Once approved, the CLI stores the token in the system keyring.
Agents running locally can use the existing CLI authentication. For agents running in containers or other environments without browser access, set CIRCLE_TOKEN to a personal API token instead.
Alternatively, circleci onboard handles authentication and project setup together. Run it inside a repository to sign in or sign up, create a starter .circleci/config.yml if needed, and connect the repository to CircleCI so pushes can trigger builds.
To verify authentication, run circleci auth me:
circleci auth me
Trying it on a demo project
The examples below use cli-test-project, a small Node.js app that generates release notes. The project contains a deliberate bug: it compares version numbers as text, treating 1.9.0 as newer than 1.10.0. Two of the three tests catch the problem, providing a failing build to investigate.
You can follow the examples with the demo project or run circleci onboard in your own GitHub repository and give your coding agent access to the project.
To use the demo, fork the repo on GitHub, clone the fork, and move into it:
git clone https://github.com/<github-username>/cli-test-project.git
cd cli-test-project
The CLI uses the current Git checkout to identify the relevant CircleCI project and branch. It reads the repo’s origin remote to find the matching CircleCI project, and the checked-out branch to decide which runs to show. That’s what lets agents work without extra setup: launched in the repo, they get the right project and branch from every command without being told which one.
If the repo has a .circleci/info.yml file, the CLI reads the project from there first. circleci onboard writes that file for CircleCI-native organizations, and circleci project link can write it for any project. To point a single command somewhere else, pass --project or --branch.
Then connect the repo to CircleCI:
circleci onboard
The following example shows the onboarding process, from initial setup to a connected project:
The demo already has a config, so onboard used it instead of writing a starter one. It confirmed authentication and connected the repo to CircleCI in the selected organization, under the accepted project name. The Pipelines link it printed opens the same project in the web app, and CircleCI builds the repo whenever it receives a push.
Agents working in the repo pick all of this up from the checkout, with no project ID to pass. In an organization created by signing in with GitHub (its name starts with gh/), onboard connects the project by following it, which starts the first build right away. In a CircleCI-native organization (circleci/), onboard also creates the project and adds a trigger that starts a run on every push. It records the project in .circleci/info.yml so the CLI can find it, and the first build waits for the next push, so push an empty commit to kick it off:
git commit --allow-empty -m "Run CI" && git push
The demo build fails because of the version comparison bug. With the CLI installed and the project connected, agents have everything they need to investigate the failure.
Checking on a build
Start with the list of recent runs. A run is one execution of the project’s pipeline, and the web app calls it a pipeline:
circleci run list --current-branch --limit 3
--current-branch limits results to the checked-out branch, while --limit controls how many runs are returned. Each row shows the branch, the commit, and whether the run passed. For more detail on the latest run on the current branch, use circleci run get. In a terminal, running it without arguments opens a menu of recent runs; --no-interactive skips the menu:
circleci run get --no-interactive
The run has one workflow, test-and-build, and it failed. Inside it, two jobs ran side by side: test failed and build succeeded. Each job has an ID, which the next commands use to dig in. Since build succeeded, the release notes it generated are still available, and a later section looks at them.
To follow a build as it runs, use circleci run watch. It waits until the run finishes and then reports the result. Pairing it with git push checks a change in one line:
git commit --allow-empty -m "Run CI"
git push && circleci run watch --sha "$(git rev-parse HEAD)"
The --sha flag associates the watch operation with the commit that was just pushed, even if CircleCI hasn’t created the run yet.
The run fails, and circleci run watch returns a nonzero exit code. A successful run returns 0; a failed run returns 1. Agents can use the exit code to determine whether a change passed CI without parsing build logs. When a run fails, they can request the failure report and begin investigating.
You can also start pipelines directly with circleci run trigger, without pushing a new commit. For faster feedback, circleci run watch --failfast exits as soon as a job fails rather than waiting for the entire run.
Pulling a failure report
Instead of clicking through the web app to find the error, one command collects every failure in the latest run:
circleci run get --failure-report
The failure report identifies the failed workflow (test-and-build), job (test), and step (Run tests, which exited with code 1). It includes the relevant error context while omitting 35 lines of routine output, reducing the amount of information agents need to process.
Both failing tests point to the same bug: compareVersions('1.10.0', '1.9.0') returns the wrong result because the code compares version numbers as text. Instead of retrieving and searching individual job logs, agents get a consolidated view of the failures in a single command, with the irrelevant output already removed.
Going deeper: the commands behind the report
The failure report provides a condensed view of what went wrong. When agents need more context, they can retrieve individual test results, full step logs, or build artifacts using targeted commands. Most take a job ID, which agents can extract from circleci run get using structured JSON output.
The following examples use the test and build job IDs:
TEST_JOB=<ID of the test job>
BUILD_JOB=<ID of the build job>
Test results
circleci testresult list shows the tests that failed:
circleci testresult list "$TEST_JOB"
To read one test’s full failure message, use testresult get with the test’s name:
circleci testresult get "$TEST_JOB" "orders 1.10.0 above 1.9.0" --plain
Step logs
The failure report named the step that failed: step 102. circleci job output get prints that step’s complete log, including the lines the report skipped. circleci job output list returns the available steps, allowing agents to retrieve additional logs as needed:
circleci job output get "$TEST_JOB" --step-num 102
Artifacts
The build job saved the release notes it generated as an artifact. circleci artifact downloads them:
circleci artifact "$BUILD_JOB" --output ./artifacts
cat artifacts/release-notes/RELEASE_NOTES.md
The demo’s bug shows up in what the build produced: 1.10.0 is the second-newest release, but it’s listed last. The cause is in the demo’s src/version.js:
export function compareVersions(a, b) {
if (a === b) return 0;
return a < b ? -1 : 1;
}
This compares versions as text, one character at a time, and the 1 in 1.10.0 sorts before the 9 in 1.9.0. Fixing the bug requires comparing each part of the version as a number rather than comparing the strings.
Rerunning a flaky failure
The demo fails because of the planted bug, but some failures are flaky and pass on a second try. For those, circleci workflow rerun --from-failed reruns just the jobs that failed. It takes the workflow ID from run get:
circleci workflow rerun <workflow-id> --from-failed
The rerun is a new workflow in the same run, and the output gives its ID. Once it finishes, check it with circleci workflow get:
circleci workflow get <new-workflow-id>
Only the test job runs again, and it fails because the underlying bug hasn’t changed. circleci workflow get reports the new attempt’s outcome, while run get still includes the original failure. Because rerunning or canceling workflows starts or interrupts CI work, developers should establish when agents need approval before taking those actions.
Getting data as JSON
Every command that returns data supports --json, giving agents structured output with named fields rather than terminal-formatted tables. Combined with --jq, agents can retrieve only the information they need, without requiring a separate jq installation.
For example, the same run list command can return a formatted table or a filtered JSON response containing only the run ID, branch, and outcome.
circleci run list --current-branch --limit 2
Compare that output to running it with the --json flag enabled:
circleci run list --current-branch --limit 2 --json --jq '.[] | {id, branch, current_outcome}'
Agents can use the named fields to extract values for subsequent commands. Each command documents its available fields under --help.
For example, the following command extracts the test job ID from the latest run:
TEST_JOB=$(circleci run get --json --jq '.workflows[0].jobs[] | select(.name == "test") | .id')
Checking config before pushing
circleci config validate checks .circleci/config.yml before a push spends a CI minute. To see it catch a mistake, misspell docker: as dokcer: in the demo’s test job and run it:
circleci config validate
The command identifies the invalid dokcer key. Agents can run circleci config validate before pushing CI config changes, using the command’s exit status to detect invalid config without starting a pipeline. To restore the demo config, run git checkout .circleci/config.yml.
Investigating failures with a coding agent
With the CLI installed and the project connected, coding agents can investigate failures directly. In the demo, Claude Code was given read-only access and a simple question: “Why did the latest CircleCI run on main fail?”
Claude Code used the CLI to inspect available commands, retrieve the failure report, and trace the error to compareVersions in the source code. The developer supplied the task, and Claude Code gathered the CI context needed to answer it.
Copying a fix prompt from the web app
CircleCI’s web app provides another way to give coding agents the context they need to investigate a failing pipeline. In the CircleCI web app, open a failed pipeline, click the small wrench icon on the failed workflow, and choose “Copy Fix Prompt” from the menu, which copies a ready-made prompt:
The prompt it copied for the demo’s failed run looks like this:
If the circleci CLI is not installed/authenticated, ask permission before
setting it up (see https://cli.circleci.com/).
Check out branch main. Pipeline 2d58b65f-a8d0-406a-a842-318ee19f1c0e failed; run "circleci run get 2d58b65f-a8d0-406a-a842-318ee19f1c0e --failure-report"
to see the failed steps.
Review the output, identify the root cause(s), and fix the code so the pipeline passes.
It gives agents what they need to start right away: the branch to check out, the pipeline ID, and the exact run get --failure-report command for the failed steps. It also tells them to ask before installing or signing in to the CLI if it isn’t set up yet. Pasted into an agent running in a clone of the repo, it starts the same investigation, this time asking the agent to fix the code rather than only diagnose it, with the developer reviewing the result.
CircleCI skills for agents
Skills are optional. As the example shows, agents can use the CLI natively with nothing more than a shell. For agents that support skills, official CircleCI agent skills add guidance for common workflows, and the CircleCI-Public/skills repo on GitHub describes each one. Its circleci plugin includes a cli skill that covers the everyday loop: validate the config, push, watch the run, read the failing logs and tests, and rerun. In Claude Code, install it from the repo’s plugin marketplace:
/plugin marketplace add CircleCI-Public/skills
/plugin install circleci@circleci-public-skills
Then ask for the skill by name with /circleci:circleci-cli.
Conclusion
The CircleCI CLI gives coding agents direct access to the tools and context they need to work with CI. Structured output, condensed failure reports, and targeted commands help agents investigate failures, validate changes, and continue toward a passing build while developers direct the work and review the results. Developers can use the same commands directly whenever they need to troubleshoot or manage CI.
Explore the full CLI reference or sign up for a free CircleCI account to connect your coding agent to CircleCI.
