CircleCI CLI for coding agents

A coding agent investigating a failed CircleCI build can read run data in a terminal with the CircleCI CLI. A CircleCI run starts when an event, such as a code change, matches a project’s trigger. CLI v1 can list recent runs and return machine-readable JSON for an agent to inspect and summarize.

CLI v1 works with CircleCI Cloud. CircleCI Server uses the separate v0 CLI, so check which CircleCI service hosts the project before installing. Install v1 by following the operating-system instructions in the official CLI documentation.

Set up the CLI

Sign in to your CircleCI account and link the local project copy so the CLI can reliably read its runs. In a terminal, sign in through the browser, confirm which account is active, and link the local project copy:

circleci auth login
circleci auth me
circleci project link

circleci auth login starts a browser-based OAuth sign-in. The CLI stores its credentials in the operating system’s credential manager. circleci auth me shows which account is signed in to the CLI.

Run circleci project link from the repository directory. It writes the project and organization IDs to .circleci/info.yml, a local file that lets the CLI identify the project for project-specific commands. CircleCI recommends linking before reading runs. The step is required for organizations whose slug starts with circleci/; for other organizations, the CLI can try to identify the project from the Git remote.

If the checkout contains CircleCI configuration, validate it with:

circleci config validate

This checks the local configuration file. It does not fetch run history from CircleCI Cloud. The login and project-link commands change local authentication or project settings; the run commands below read remote CI data. CircleCI documents these setup steps and run commands.

Read runs as JSON

Ask the CLI for recent runs in the linked project:

circleci run list --json

The --json option returns machine-readable output in a structured format an agent can read and inspect. The CLI also supports --jq for filtering its output, but an agent should use only fields it has actually observed rather than assume a JSON structure.

To inspect a particular run, pass its ID to circleci run get and request JSON:

circleci run get <run-id> --json

The run details can show workflows and jobs, along with outcomes and timings. They can also include step information. The returned data determines which details are available, so an agent should base its summary on the fields it receives. With no run ID, circleci run get opens an interactive terminal view, which is intended for a person rather than an unattended agent.

A focused agent task could be:

Read recent CircleCI runs for this checkout using circleci run list --json. Find failed runs in the returned data, inspect their details with circleci run get <run-id> --json, and summarize the failures using only information present in the output. Include the run identifier and any reported workflow, job, step, or exit-code details. Do not change files or rerun jobs.

Before asking the agent to read runs, confirm that the CLI is signed in and the checkout is linked. If the CLI reports that it cannot find the project, check the local .circleci/info.yml link and the Git remote rather than guessing a project identifier.

Keep CLI versions separate

CLI v1 uses circleci run for CircleCI Cloud run operations. CircleCI Server users need CLI v0 instead; commands from the two versions should not be mixed. The migration guide lists older commands removed from v1, including local job execution commands. For an agent task that reads cloud run history, use the v1 commands above.