Documentation structure for LLMs (llms.txt)
CircleCI Logo

The CircleCI CLI

9 hours ago
Cloud Server

The CircleCI command line interface (CLI) brings CircleCI’s tooling to your terminal.

CLI v1 is not supported for CircleCI Server. Install CLI v0 instead. See Install CLI v0 for CircleCI Server.

Explaining CircleCI’s CLI offerings

The CircleCI CLI

The development tool used on your local machine for day-to-day development tasks. It handles testing and local workflow management.

The CircleCI environment CLI

A specialized command-line interface that retrieves and configures a task. It manages the execution of the job within a chosen compute environment.

Install CLI v0 for CircleCI Server

Install CLI v0 using one of the following methods.

What you can do with CLI v0

The following table summarizes the top-level commands available in CLI v0.

Command What it does

config

Validate, pack, and process build config files.

context

Secure and share environment variables across projects.

diagnostic

Check the status of your CircleCI CLI.

info

Check information associated with your user account.

local

Debug and run jobs on your local machine.

namespace

Operate on orb namespaces.

orb

Create, publish, validate, and manage orbs.

pipeline

Operate on pipelines.

policy

Manage security policies.

project

Operate on projects.

runner

Operate on self-hosted runners.

setup

Set up the CLI with your credentials.

telemetry

Configure telemetry preferences.

trigger

Operate on triggers.

version

Display version information.

The table does not cover every command. Run circleci-v0 --help to see the full command list.

Install with Homebrew

If you use Homebrew on macOS or Linux, install CLI v0 with the following command:

brew install circleci-public/circleci/circleci@v0

This installs a circleci-v0 binary, so it can coexist with a CLI v1 circleci installation.

Install with the install script

On macOS and Linux, set the VERSION environment variable to pin the install script to the latest v0 release:

VERSION=0.1.47860 curl -fsSL https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/main/install.sh | bash

This installs a circleci-v0 binary to /usr/local/bin by default.

Manual install

Download the archive for your platform, including Windows, from the v0.1.47860 release page on GitHub.

Set up CLI v0 for your Server host

After installing CLI v0, point it at your Server installation.

  1. Run the setup command:

    circleci-v0 setup

  2. When prompted, provide the following:

    • A personal API token from your Server web app. Go to User Settings  Personal API Tokens to create one.

    • Your Server host URL, for example https://circleci.example.com. Do not use https://circleci.com.

      CLI v0 saves this configuration to ~/.circleci/cli.yml.

  3. Confirm the CLI can reach your Server host:

    circleci-v0 diagnostic
To run setup without interactive prompts, for example from a script, use circleci-v0 setup --no-prompt --host <your-server-url> --token <your-token>.

If you also use the CircleCI CLI for Cloud, keep the two separate. Run circleci auth login to authenticate CLI v1 with Cloud, and circleci-v0 setup to authenticate CLI v0 with Server.

Troubleshoot CLI v1 replacing your CLI v0 install

Homebrew or the CLI’s own update check can upgrade a circleci binary to CLI v1 without you asking for it. If circleci used to be your CLI v0 install, that upgrade breaks Server access, because CLI v1 does not work against a Server host. A typical sign is a Server command that used to work but now fails. The error is often a missing API route, or an authentication method that only exists for Cloud.

You do not need to uninstall CLI v1 to fix this. Install CLI v0 alongside it using the Homebrew or install script method described earlier on this page. This adds a separate circleci-v0 binary without touching your existing circleci install. From then on, run Server commands with circleci-v0 instead of circleci.

If a machine only ever connects to Server and you would rather run a single CLI, you can uninstall CLI v1 once CLI v0 is working. For example, brew uninstall circleci or brew uninstall --cask circleci@next, depending on how CLI v1 was installed.

Reference documentation for CLI v0

CLI v0 does not have a hosted reference site. Add --help to any circleci-v0 command at any depth to see its description, flags, and examples:

circleci-v0 --help
circleci-v0 config --help

Next steps

Using the CLI to complete common tasks is described across the docs. Some examples are:

  • Managing Contexts and environment variables.