Search Results for ""

Using the CircleCI Local CLI

This document provides instructions for installing and using the CircleCI CLI.


The circleci command-line interface enables you to reproduce the CircleCI environment locally and run jobs as if they were running on the hosted application for more efficient debugging and configuration in the initial setup phase.

You can also run circleci commands in your .circleci/config.yml file for jobs that use the primary container image. This is particularly useful for globbing or splitting tests among containers.

Note: If you installed the CLI prior to October 2018 you may need to do an extra one-time step to switch to the new CLI. See upgrading and installation instructions below.


There are a few installation options.

Updating to the new CLI

The CLI upgrade provides additional functionality through a totally new CLI developed as 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 doesn’t have write permissions to the install directory, /usr/local/bin.

Installing the CircleCI CLI on macOS or Linux

If you haven’t already installed circleci on your machine, run the following command to install the CircleCI CLI:

curl -fLSs | 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. Alternatively, you can install to an alternate location by defining the DESTDIR environment variable when invoking bash:

curl -fLSs | DESTDIR=/opt/bin bash

[Alternative] Install with snap

The following commands will install the CircleCI CLI, Docker, and the security and auto-update features that come along with Snap packages.

sudo snap install docker circleci
sudo snap connect circleci:docker docker

Note: With snap packages, the docker command will use the Docker snap, not any version of Docker you may have previously installed. For security purposes, snap packages can only read/write files from within $HOME.

[Alternative] Install on macOS with Homebrew

If you’re using Homebrew with macOS, you can install the CLI with the following command:

brew install circleci

Note: If you already have Docker for Mac installed, use brew install --ignore-dependencies circleci.

[Alternative] Manual download

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.

Configuring the CLI

Before using the CLI you need to generate a CircleCI API Token from the Personal API Token tab. Once you have a token configure the CLI by running:

$ circleci setup

Setup will prompt you for configuration settings. If you are using the CLI with, use the default CircleCI Host. If you are using CircleCI Enterprise change the value to your installation address (for example,

Validate A CircleCI config

To ensure that the CLI is configured correctly you can use it to validate a CircleCI config file.

  1. Change to the root directory of your CircleCI project repository.

  2. Run the following command:

$ circleci config validate
Config file at .circleci/config.yml is valid

You can also validate your config through CircleCI’s API.

Run validate using git hooks

To catch CircleCI config errors as you build your full config.yml file, it is possible create a Git pre-commit hook to validate ~/.circleci/config.yml that, before pushing to github, will run the circleci config validate command that is available to every build.

Check out this blog post about creating the Git hook.

Run a Job in a Container on the Local Machine

The CLI allows you to run a single job from the CircleCI on your desktop using docker.

$ circleci local execute --job JOB_NAME

Note: This command will only run a single job, it does not run a workflow.

Troubleshooting Container Configurations Locally

Test locally to quickly retry configurations such as connecting on different ports or with different users. Jobs often have several containers that need to “talk” to each other. For example, you might want to locally test that a job can connect and create the relevant database with correct permissions on the correct port for a PostgreSQL container. Or you might be using a pre-built container, but you’re unsure if it has all the services you need, or if they’re running in the way you hope.

Cloning and Building an Environment Locally

If a project has been configured to run on CircleCI, you can simply clone the repo and run the circleci build command to get set up quickly with the same environment as your team.

Using a specific checkout key for a local build

You can use a specific Git checkout key for your local build with circleci build --checkout-key string. The default key is “~/.ssh/id_rsa” on your local system.


You can update the Local CLI internal engine, build agent, with circleci update. If the Local CLI was installed via cURL instead of a package manager, this will also update the CLI itself.

Checking for available options

As we update the local tool regularly, there may be options for a command that aren’t documented here. You can check for these options with circleci help <command>.


Although running jobs locally with circleci is very helpful, there are some limitations.

Machine Executor

You cannot use the machine executor in local jobs. This is because the machine executor requires an extra VM to run its jobs.


Caching is not currently supported in local jobs. When you have either a save_cache or restore_cache step in your config, circleci will skip them and display a warning.

Environment Variables

For security reasons, encrypted environment variables configured in the UI will not be exported into local builds. As an alternative, you can specify env vars to the CLI with the -e flag. See the output of circleci help build for more information. If you have multiple environment variables, you must use the flag for each variable, for example, circleci build -e VAR1=FOO -e VAR2=BAR.

Using the Local CLI Within CircleCI Convenience Images

The Local CLI is available in CircleCI Docker convenience images, the machine executor, and the macos executor. For example, check out Merging and Splitting Tests for examples of using circleci commands in your config.yml file with a remote hosted environment.