Preview release — this branch (
main) tracks the new CLI rewrite. It is under active development and not yet stable. For the current stable CLI, see stable installation.
This is CircleCI's command-line application.
Documentation | Code of Conduct | Contribution Guidelines |
circleci is CircleCI's official command line tool. It is an agent-friendly CLI that brings CI runs, jobs,
configuration, and other CircleCI features to the terminal right where you're already working.
The CLI is supported for users on circleci.com and CircleCI server; with support for macOS, Windows, and Linux.
A ground-up rewrite of the agent-friendly CircleCI CLI is available for preview.
circleci run— Full pipeline run management: list, get, trigger, cancel, and watch runs from the terminal.run watchblocks until a run completes and exits with a status code that reflects the result, making it easy to script CI gating.circleci deploy— View deployed components and versions across environments, and initialize CircleCI Deploys for a project.circleci dlc purge— Invalidate Docker layer caching for a project to force a fresh image build on the next run.circleci workflow— List, inspect, cancel, and rerun individual workflows.circleci pipeline— List and inspect pipelines.circleci envvar— Manage project environment variables.--jsonon every command — Every data-returning command supports--jsonfor machine-readable, scriptable output.- MCP server — First-class Model Context Protocol support: register the CLI as an MCP server in Claude, Cursor, or VS Code with a single command.
- Shell completions — Bash and Zsh completions via
circleci completion.
Note: This is a preview release. Commands and flags may change before stable. Please open an issue with any feedback.
Install the preview (v1.x) CLI via one of the following package managers:
If you have the stable CLI installed:
brew uninstall circleciThen:
brew install circleci-public/circleci/circleci@nextwinget install --id CircleCI.CLI.Previewsudo snap install circleci --channel=edge
sudo snap connect circleci:password-manager-serviceDebian packages are hosted at packages.circleci.com for various operating systems including:
To install packages, you can quickly setup the repository automatically:
curl -1sLf 'https://packages.circleci.com/public/setup.deb.sh' | sudo -E bashor you can manually configure it yourself before installing packages:
apt-get install -y debian-keyring # debian only
apt-get install -y debian-archive-keyring # debian only
apt-get install -y apt-transport-https
# For Debian Stretch, Ubuntu 16.04 and later
keyring_location=/usr/share/keyrings/circleci-deps-public-archive-keyring.gpg
# For Debian Jessie, Ubuntu 15.10 and earlier
keyring_location=/etc/apt/trusted.gpg.d/circleci-deps-public.gpg
curl -1sLf 'https://packages.circleci.com/public/gpg.B3F71F41836351D6.key' | gpg --dearmor >> ${keyring_location}
curl -1sLf 'https://packages.circleci.com/public/config.deb.txt?distro=ubuntu&codename=xenial&component=main' > /etc/apt/sources.list.d/circleci-deps-public.list
sudo chmod 644 ${keyring_location}
sudo chmod 644 /etc/apt/sources.list.d/circleci-deps-public.list
apt-get updateNote: Please replace ubuntu, xenial and main above with your actual operating system (distribution and distribution release/version) and components (based on what's in this repository).
Then install:
sudo apt install circleciRPM packages are hosted at packages.circleci.com for various operating systems including:
For most RPM based distributions (RHEL, CentOS, Fedora, SUSE), you can quickly setup the repository automatically:
curl -1sLf 'https://packages.circleci.com/public/setup.rpm.sh' | sudo -E bashor manual Yum setup (RHEL, CentOS, Amazon Linux):
yum install yum-utils pygpgme
rpm --import 'https://packages.circleci.com/public/gpg.B3F71F41836351D6.key'
curl -1sLf 'https://packages.circleci.com/public/config.rpm.txt?distro=el&codename=7' > /tmp/circleci-deps-public.repo
yum-config-manager --add-repo '/tmp/circleci-deps-public.repo'
yum -q makecache -y --disablerepo='*' --enablerepo='circleci-deps-public'Note: Please replace el and 7 above with your actual distribution/version and use Wildcards when enabling multiple repos.
or manual DNF setup (Fedora):
dnf install yum-utils pygpgme
rpm --import 'https://packages.circleci.com/public/gpg.B3F71F41836351D6.key'
curl -1sLf 'https://packages.circleci.com/public/config.rpm.txt?distro=fedora&codename=29&dnf_version=5' > /tmp/circleci-deps-public.repo
dnf config-manager addrepo --from-repofile='/tmp/circleci-deps-public.repo'
dnf -q makecache -y --disablerepo='*' --enablerepo='circleci-deps-public' --enablerepo='circleci-deps-public-source'Note: Please replace fedora and 29 above with your actual distribution/version.
Then install:
dnf install circlecior:
yum install circleciIf you need the previous stable version, install via HomeBrew, Snap, WinGet, or Chocolatey:
brew install circlecisudo snap install circleciwinget install --id CircleCI.CLIRun the following command to login to the CircleCI CLI:
circleci auth loginThe CLI supports the MCP protocol. To enable it, run:
Claude:
circleci mcp claude enable # Enable in Claude desktop
claude mcp add-from-claude-desktop -s user # Add with current user scopeCursor:
circleci mcp cursor enableVS Code:
circleci mcp vscode enableThis repository makes use Task which can be installed (on MacOS) with:
$ brew install go-task/tap/go-task
Most other tools referenced in the Taskfile.yml are managed by the go.mod tool section.
See the full list of available tasks by running task -l, or, see the Taskfile.yml script.
# Run all static checks
task check
# Auto-fix static checks
task fix
# Run all the tests
task test
# Run the quick tests
task test -- -short ./...
# Run the quick tests for one package
task test -- -short ./internal/...
# Format all the code
task fmt
# Apply license headers
task license
# Tidy go.mod
task mod-tidy