Docs
Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Install and configure the CircleCI local CLI

7 months ago3 min read
Cloud
Server v4.x
Server v3.x
On This Page

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:

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.

Installation

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 $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/main/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/main/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/main/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

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:

  circleci update

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.

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:

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).

Telemetry

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 enable or circleci telemetry disable

  • To disable telemetry, set the CIRCLECI_CLI_TELEMETRY_OPTOUT environment variable to 1 or true

Uninstall

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

Next steps

If you wish to suggest ways we could improve the CLI share your suggestion on the GitHub repository.

Troubleshooting

Suggest an edit to this page

Make a contribution
Learn how to contribute

Still need help?

Ask the CircleCI community
Join the research community
Visit our Support site