Install and configure the CircleCI local CLI
The CircleCI command line interface (CLI) brings CircleCI’s advanced and powerful tools to your terminal.
Some of the things you can do with the CLI include:
- Debug and validate your CircleCI configuration
- Run jobs locally
- Query CircleCI’s API
- Create, publish, view, and manage orbs
- Manage contexts
- Split your tests to run across parallel environments to reduce pipeline duration
This page covers the installation and usage of the CircleCI CLI. The expectation is you have basic knowledge of CI/CD, CircleCI’s concepts. You should already have a CircleCI account, an account with a supported VCS, and have your terminal open and ready to go.
There are multiple installation options for the CircleCI CLI.
For the majority of installations, we recommend one of the package managers outlined in the sections below to install the CircleCI CLI.
Linux: Install with Snap
The following commands will install the CircleCI CLI, Docker, and both the security and auto-update features that come along with Snap packages.
sudo snap install docker circleci sudo snap connect circleci:docker docker
With snap packages, the Docker command will use the Docker snap, not a version of Docker you may have previously installed. For security purposes, snap packages can only read/write files from within
macOS: Install with Homebrew
If you are using Homebrew with macOS, you can install the CLI with the following command:
brew install circleci
If you already have Docker for Mac installed, you can use this command instead:
brew install --ignore-dependencies circleci
Windows: Install with Chocolatey
For Windows users, CircleCI provides a Chocolatey package:
choco install circleci-cli -y
Alternative installation method
Mac and Linux:
curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/master/install.sh | bash
By default, the CircleCI CLI tool will be installed to the
/usr/local/bin directory. If you do not have write permissions to
/usr/local/bin, you may need to run the above command with
sudo after the pipe and before
curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/master/install.sh | sudo bash
You can also install to an alternate location by defining the
DESTDIR environment variable when invoking bash:
curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/master/install.sh | DESTDIR=/opt/bin bash
You can visit the GitHub releases page for the CLI to manually download and install. This approach is best if you would like the installed CLI to be in a specific path on your system.
Updating the CLI
If you would just like to check for updates manually (and not install them), use the command:
circleci update check
For Linux and Windows installs, you can update to the newest version of the CLI using the following command:
For macOS installations with Homebrew, you will need to run the following command to update:
brew upgrade circleci
Updating the legacy CLI
circleci update circleci switch
This command may prompt you for
sudo if your user does not have write permissions to the install directory,
Configure the CLI
Before using the CLI, you need to generate a CircleCI API token from the Personal API Token tab. After you get your token, configure the CLI by running:
The set up process will prompt you for configuration settings. If you are using the CLI with CircleCI cloud, use the default CircleCI host. If you are using CircleCI server, change the value to your installation address (for example, circleci.your-org.com).
The CircleCI CLI includes a telemetry feature that collects basic errors and feature usage data in order to help us improve the experience for everyone.
Telemetry works on an opt-in basis. When running a command for the first time, you will be asked for consent to enable telemetry. Telemetry is disabled by default for non-interactive terminals, ensuring that scripts that leverage the CLI run smoothly.
You can disable or enable telemetry any time in one of the following ways:
Run one of the following commands:
circleci telemetry enableor
circleci telemetry disable
To disable telemetry, set the
CIRCLECI_CLI_TELEMETRY_OPTOUTenvironment variable to
The commands for uninstalling the CircleCI CLI will vary depending on your original installation method.
Linux uninstall with Snap:
sudo snap remove circleci
macOS uninstall with Homebrew:
brew uninstall circleci
Windows uninstall with Chocolatey:
choco uninstall circleci-cli -y --remove dependencies
Alternative curl uninstall: Remove the
circleci executable from
- How to validate your CircleCI configuration
- How to run a job in a container on your local machine
- How to create, publish, view, and manage orbs
- How to manage contexts
- How to split your tests to run across parallel environments to reduce pipeline duration
CLI articles in the support centre
If you wish to suggest ways we could improve the CLI please share your suggestion on the GitHub repo
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.