Use CircleCI from the command line
Clone or download
zzak Merge pull request #224 from CircleCI-Public/pre-fetch-modules
[CIRCLE-15262]: Pre-fetch and cache go modules
Latest commit 8bee1e6 Dec 10, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Disable gomod on lint job since it runs inside $GOPATH Dec 10, 2018
.github Update code owners Jul 9, 2018
api Use standard funcs for stdout / stderr instead of our own logger Dec 1, 2018
client Use standard funcs for stdout / stderr instead of our own logger Dec 1, 2018
cmd Add newline to validation output Dec 7, 2018
filetree Collapse looks for yaml files that start with "@" for specialCase Jun 22, 2018
md_docs Ensure LICENSE files are added to the archive Oct 4, 2018
proxy Improve errors when circleci-agent binary is unavailable Aug 14, 2018
references Allow slashes in dev labels Nov 28, 2018
settings Add file storage for update check settings Nov 9, 2018
snap Fix snap package permissions. Sep 3, 2018
ui Use standard funcs for stdout / stderr instead of our own logger Dec 1, 2018
update Automatically check for updates once every 28 hours Nov 14, 2018
version Enable snapcraft deploys Aug 14, 2018
.gitattributes Add command to validate config Jun 15, 2018
.gitignore Turn off go1.11 modules for gometalinter since it's unsupported Dec 3, 2018
.gometalinter.json Move nolint of md_docs to .gometalinter.json config Aug 31, 2018
.goreleaser.yml Treat binary releases similar to source for update checks Nov 10, 2018 Create Aug 16, 2018 s/contributed/sent a patch Nov 17, 2018 Add @SamChapler to [ci skip] Dec 7, 2018
Dockerfile Use goreleaser binaries when making docker image Jun 26, 2018
Dockerfile.alpine Add Alpine Docker image (#166) Oct 18, 2018 Upgrade Go to v1.11 and use modules instead of godep Dec 3, 2018
LICENSE Create LICENSE Aug 16, 2018
Makefile Make all orb commands take a reference to an orb. Sep 25, 2018 Fix link to API token page and add @antzshrek to Nov 16, 2018
circleci_cli_suite_test.go Move existing integration test to cmd package Jun 13, 2018
go.mod Upgrade Go to v1.11 and use modules instead of godep Dec 3, 2018
go.sum Upgrade Go to v1.11 and use modules instead of godep Dec 3, 2018 Document the new URL Oct 25, 2018
main.go Update references to project after switching organizations to public Jun 22, 2018


This project is the seed for CircleCI's new command-line application.

Documentation | Code of Conduct | Contribution Guidelines | Hacking

CircleCI GitHub release GoDoc Codecov License

Getting Started

From Scratch

Install script

If you're installing the new circleci CLI for the first time, run the following command:

curl -fLSs | bash

By default, the circleci app 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


brew install circleci


sudo snap install circleci

Upgrade from existing CLI

If you installed the old CLI before, and you're on version less than 0.1.6, you need to run the following commands:

circleci update
circleci switch

This command may require sudo if your user doesn't have write permissions to the install directory, /usr/local/bin. Otherwise, you may see the following error:

mv: cannot move 'circleci' to '/usr/local/bin/circleci': Permission denied

Updating after install

The CLI comes with a built in version managment system. You can check if there any updates pending and update if so using the following commands:

circleci update check
circleci update install

Configure the CLI

After installing the latest version of our CLI, you must run setup to configure the tool.

$ circleci setup

You should be prompted to enter the CircleCI API Token you generated from the Personal API Token tab

✔ CircleCI API Token: 

API token has been set.

✔ CircleCI Host:

CircleCI host has been set.

Setup complete. Your configuration has been saved.

If you are using this tool on accept the provided default CircleCI Host.

Server users will have to change the default value to your custom address (i.e.

Note: Server does not yet support config processing and orbs, you will only be able to use circleci local execute (previously circleci build) for now.

Validate A Build Config

To ensure that the tool is installed, you can use it to validate a build config file.

$ circleci config validate

Config file at .circleci/config.yml is valid


The CLI may also be used without installation by using Docker.

docker run --rm -v $(pwd):/data circleci/circleci-cli:alpine config validate /data/.circleci/config.yml --token $TOKEN


Development instructions for the CircleCI CLI can be found in


Please see the documentation or circleci help for more.