---
title: "The CircleCI CLI"
description: "A guide to the CircleCI CLI with links to setup guides, a ful reference and how-to guides for common tasks."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-26"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# The CircleCI CLI

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](#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](https://brew.sh/) on macOS or Linux, install CLI v0 with the following command:

```shell
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:

```shell
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](https://github.com/CircleCI-Public/circleci-cli/releases/tag/v0.1.47860) 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:
    
    ```shell
    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:
    
    ```shell
    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:

```shell
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](https://circleci.com/docs/guides/server/security/contexts/) and environment variables.