Docs
circleci.com
Start Building for Free

Installing the CircleCI Local CLI

2 weeks ago3 min read
Cloud
Server v2.x
Server v3.x
Helpful Resources
On This Page

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.

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/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:

  1. Install and configure Docker by using the docker installation instructions.
  2. 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.

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.