README
¶
circleci-cli
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.
Installation
Install the CLI via one of the following package managers:
Homebrew
brew install circleci
WinGet
winget install --id CircleCI.CLI
Snap
sudo snap install circleci
sudo snap connect circleci:password-manager-service
Debian
Debian 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 bash
or 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 update
Note: 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 circleci
RedHat
RPM 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 bash
or 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 circleci
or:
yum install circleci
Setup
Login
Run the following command to login to the CircleCI CLI:
circleci auth login
Model Context Protocol (MCP)
The 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 scope
Cursor:
circleci mcp cursor enable
VS Code:
circleci mcp vscode enable
Development
Local
This 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
Directories
¶
| Path | Synopsis |
|---|---|
|
clikit
module
|
|
|
cmd
|
|
|
circleci
command
|
|
|
cloudsmith
command
Command cloudsmith publishes Linux packages (.deb and .rpm) to a Cloudsmith repository via the public REST API.
|
Command cloudsmith publishes Linux packages (.deb and .rpm) to a Cloudsmith repository via the public REST API. |
|
packagecloud
command
Command packagecloud talks to the packagecloud.io REST API: it publishes Linux nfpm packages (.rpm/.deb) and lists, shows, and creates repositories.
|
Command packagecloud talks to the packagecloud.io REST API: it publishes Linux nfpm packages (.rpm/.deb) and lists, shows, and creates repositories. |
|
virustotal
command
Command virustotal submits release artifacts to VirusTotal via the public v3 API so every published binary has an antivirus scan on record.
|
Command virustotal submits release artifacts to VirusTotal via the public v3 API so every published binary has an antivirus scan on record. |
|
internal
|
|
|
apiclient
Package apiclient provides a thin HTTP client for the CircleCI REST API.
|
Package apiclient provides a thin HTTP client for the CircleCI REST API. |
|
artifacts
Package artifacts implements the business logic for fetching and downloading CircleCI job artifacts.
|
Package artifacts implements the business logic for fetching and downloading CircleCI job artifacts. |
|
bulkhead
Package bulkhead runs a slice of work with bounded parallelism.
|
Package bulkhead runs a slice of work with bounded parallelism. |
|
cmd/api
Package api implements the "circleci api" escape-hatch command for making raw authenticated requests to the CircleCI REST API.
|
Package api implements the "circleci api" escape-hatch command for making raw authenticated requests to the CircleCI REST API. |
|
cmd/artifacts
Package artifacts implements the "circleci artifacts" command.
|
Package artifacts implements the "circleci artifacts" command. |
|
cmd/certificate
Package certificate implements the "circleci certificate" command group for managing iOS code signing certificates (.p12 files).
|
Package certificate implements the "circleci certificate" command group for managing iOS code signing certificates (.p12 files). |
|
cmd/completion
Package completion implements the "circleci completion" command group.
|
Package completion implements the "circleci completion" command group. |
|
cmd/componentversion
Package componentversion implements the "circleci component-version" command group.
|
Package componentversion implements the "circleci component-version" command group. |
|
cmd/config
Package cmdconfig implements the "circleci config" command group, which works with the pipeline configuration file (.circleci/config.yml).
|
Package cmdconfig implements the "circleci config" command group, which works with the pipeline configuration file (.circleci/config.yml). |
|
cmd/context
Package context implements the "circleci context" command group.
|
Package context implements the "circleci context" command group. |
|
cmd/dlc
Package dlc implements the "circleci dlc" command group.
|
Package dlc implements the "circleci dlc" command group. |
|
cmd/env
Package cmdenv implements the "circleci env" command group.
|
Package cmdenv implements the "circleci env" command group. |
|
cmd/envvar
Package envvar implements the "circleci envvar" top-level command, which is the primary user-facing alias for "circleci project envvar".
|
Package envvar implements the "circleci envvar" top-level command, which is the primary user-facing alias for "circleci project envvar". |
|
cmd/extension
Package extension implements the circleci plugin mechanism.
|
Package extension implements the circleci plugin mechanism. |
|
cmd/namespace
Package namespace implements the "circleci namespace" command group.
|
Package namespace implements the "circleci namespace" command group. |
|
cmd/onboard
Package cmdonboard implements the "circleci onboard" command.
|
Package cmdonboard implements the "circleci onboard" command. |
|
cmd/orb
Package orb implements the "circleci orb" command group.
|
Package orb implements the "circleci orb" command group. |
|
cmd/org
Package org implements the "circleci org" command group.
|
Package org implements the "circleci org" command group. |
|
cmd/pipeline
Package pipeline implements the "circleci pipeline" command group.
|
Package pipeline implements the "circleci pipeline" command group. |
|
cmd/policy
Package policy implements the "circleci policy" command group.
|
Package policy implements the "circleci policy" command group. |
|
cmd/project
Package project implements the "circleci project" command group.
|
Package project implements the "circleci project" command group. |
|
cmd/runner
Package runner implements the "circleci runner" command group.
|
Package runner implements the "circleci runner" command group. |
|
cmd/setup
Package setup provides the hidden "circleci setup" command.
|
Package setup provides the hidden "circleci setup" command. |
|
cmd/signingconfig
Package signingconfig implements the "circleci signing-config" command group for managing iOS signing configs (a certificate paired with provisioning profiles).
|
Package signingconfig implements the "circleci signing-config" command group for managing iOS signing configs (a certificate paired with provisioning profiles). |
|
cmd/step
Package step implements the "circleci step" command group.
|
Package step implements the "circleci step" command group. |
|
cmd/testresult
Package testresult implements the "circleci testresult" command group.
|
Package testresult implements the "circleci testresult" command group. |
|
cmd/version
Package version implements the "circleci version" command.
|
Package version implements the "circleci version" command. |
|
cmd/workflow
Package workflow implements the "circleci workflow" command group.
|
Package workflow implements the "circleci workflow" command group. |
|
cmdutil
Package cmdutil provides shared helpers used by command packages.
|
Package cmdutil provides shared helpers used by command packages. |
|
config
Package config manages the CLI's user-level configuration file.
|
Package config manages the CLI's user-level configuration file. |
|
configcmd
Package configcmd contains the business logic for circleci config subcommands.
|
Package configcmd contains the business logic for circleci config subcommands. |
|
configgen
Package configgen renders a CircleCI pipeline YAML from a reposcan.Result and writes it to disk.
|
Package configgen renders a CircleCI pipeline YAML from a reposcan.Result and writes it to disk. |
|
conventions
Package conventions holds tests that enforce the repository's own conventions — the ones that are house rules rather than compiler or linter rules, and that would otherwise be enforced only by whoever happens to review a diff.
|
Package conventions holds tests that enforce the repository's own conventions — the ones that are house rules rather than compiler or linter rules, and that would otherwise be enforced only by whoever happens to review a diff. |
|
deployinit
Package deployinit implements scanning and patching of .circleci/config.yml to add deploy marker steps for circleci deploy init.
|
Package deployinit implements scanning and patching of .circleci/config.yml to add deploy marker steps for circleci deploy init. |
|
githubapp
Package githubapp drives the CircleCI GitHub App onboarding steps: checking whether the app is installed for an organization, walking the user through a browser-based install, and resolving a repository's external ID.
|
Package githubapp drives the CircleCI GitHub App onboarding steps: checking whether the app is installed for an organization, walking the user through a browser-based install, and resolving a repository's external ID. |
|
gitremote
Package gitremote resolves the CircleCI project slug for the current working directory.
|
Package gitremote resolves the CircleCI project slug for the current working directory. |
|
httpcl
Package httpcl provides a minimal HTTP client with JSON defaults and retries.
|
Package httpcl provides a minimal HTTP client with JSON defaults and retries. |
|
iossigning
Package iossigning provides helpers for the iOS code signing commands — reading certificate / provisioning-profile files from disk and base64 encoding them for transmission to the CircleCI API.
|
Package iossigning provides helpers for the iOS code signing commands — reading certificate / provisioning-profile files from disk and base64 encoding them for transmission to the CircleCI API. |
|
oauth
Package oauth implements the client side of the CircleCI OAuth 2.0 Authorization Code + PKCE flow (RFC 6749 + RFC 7636 + RFC 8252) with Pushed Authorization Requests (RFC 9126).
|
Package oauth implements the client side of the CircleCI OAuth 2.0 Authorization Code + PKCE flow (RFC 6749 + RFC 7636 + RFC 8252) with Pushed Authorization Requests (RFC 9126). |
|
onboarder
Package onboarder orchestrates the local onboarding flow.
|
Package onboarder orchestrates the local onboarding flow. |
|
orbinit
Package orbinit scaffolds a new orb project for "circleci orb init".
|
Package orbinit scaffolds a new orb project for "circleci orb init". |
|
org
Package org provides shared logic for CircleCI organization operations.
|
Package org provides shared logic for CircleCI organization operations. |
|
pack
Package pack merges a directory tree of YAML files into a single YAML document.
|
Package pack merges a directory tree of YAML files into a single YAML document. |
|
projectref
Package projectref reads and writes .circleci/info.yml — the per-checkout file that records which CircleCI project this directory is bound to.
|
Package projectref reads and writes .circleci/info.yml — the per-checkout file that records which CircleCI project this directory is bound to. |
|
reposcan
Package reposcan detects the language stack, container image, and setup commands for a local repository.
|
Package reposcan detects the language stack, container image, and setup commands for a local repository. |
|
run
Package run contains business logic for run-level operations.
|
Package run contains business logic for run-level operations. |
|
termrender
Package termrender replays captured terminal output and writes the resulting text, line by line, to an output writer.
|
Package termrender replays captured terminal output and writes the resulting text, line by line, to an output writer. |
|
testing/binary
Package binary builds the circleci CLI binary once per test run and provides helpers for running it in tests.
|
Package binary builds the circleci CLI binary once per test run and provides helpers for running it in tests. |
|
testing/env
Package env provides a test environment builder for acceptance tests.
|
Package env provides a test environment builder for acceptance tests. |
|
testing/fakes
Package fakes provides fake HTTP servers for acceptance testing.
|
Package fakes provides fake HTTP servers for acceptance testing. |
|
testing/httprecorder
Package httprecorder provides a simple way of recording and later retrieving all requests that are sent to an HTTP handler.
|
Package httprecorder provides a simple way of recording and later retrieving all requests that are sent to an HTTP handler. |
|
testing/httprecorder/chirecorder
Package chirecorder provides a middleware to wire a httprecorder into Chi routers used in test fakes.
|
Package chirecorder provides a middleware to wire a httprecorder into Chi routers used in test fakes. |
|
testing/httprecorder/httpnetrecorder
Package httpnetrecorder provides a middleware to wire a httprecorder into test fakes.
|
Package httpnetrecorder provides a middleware to wire a httprecorder into test fakes. |
|
update
Package update discovers whether a newer circleci release exists and, when so, hands the caller a notice to print after a successful command.
|
Package update discovers whether a newer circleci release exists and, when so, hands the caller a notice to print after a successful command. |
Click to show internal directories.
Click to hide internal directories.