Installing the CircleCI Local CLI
Cloud Server v2.x Server v3.x Overview
The CircleCI command line interface (CLI) brings CircleCI’s advanced and powerful tools to your terminal. The CLI is supported on cloud and server v3.x+ installations. If you are using server v2.x, please see the legacy CLI installation section.
Some of the things you can do with the CLI include:
- Debug and validate your CI config
- Run jobs locally
- Query CircleCI’s API
- Create, publish, view, and manage orbs
- Manage contexts
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.
- Overview
- Installation
- Updating the CLI
- Configuring the CLI
- Validate a CircleCI config
- Uninstallation
- Using the CLI on CircleCI server v2.x
- Next steps
Installation
There are multiple installation options for the CircleCI CLI.
If you have previously installed CLI prior to October 2018, you may need to do an extra one-time step to switch to the new CLI. See the upgrade instructions.
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 $HOME.
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 bash:
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
Manual install
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
For Linux and Windows installs, you can update to the newest version of the CLI using the following command:
circleci update
If you would just like to check for updates manually (and not install them), use the command:
circleci update check
For macOS installations with Homebrew, you will need to run the following command to update:
brew upgrade circleci
Updating the legacy CLI
The newest version of the CLI is a CircleCI-Public open source project. If you have the old CLI installed, run the following commands to update and switch to the new CLI:
circleci update
circleci switch
This command may prompt you for sudo if your user does not have write permissions to the install directory, /usr/local/bin.
Configuring 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:
circleci setup
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).
Validate a CircleCI config
You can avoid pushing additional commits to test your .circleci/config.yml by using the CLI to validate your configuration locally.
To validate your configuration, navigate to a directory with a .circleci/config.yml file and run:
circleci config validate
# Config file at .circleci/config.yml is valid
Uninstallation
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 usr/local/bin
Using the CLI on CircleCI server v2.x
Currently, only the legacy CircleCI CLI is available to run on server v2.x installations of CircleCI on macOS and Linux distributions. To install the legacy CLI:
- Install and configure Docker by using the docker installation instructions.
- To install the CLI, run the following command:
$ curl -o /usr/local/bin/circleci https://circle-downloads.s3.amazonaws.com/releases/build_agent_wrapper/circleci && chmod +x /usr/local/bin/circleci
The CLI, circleci, is downloaded to the /usr/local/bin directory. If you do not have write permissions for /usr/local/bin, you might need to run the above commands with sudo. The CLI automatically checks for updates and will prompt you if one is available.
Next steps
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.
Need support?
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.
