Getting started

circleci is a command-line interface to CircleCI for use in your terminal or your scripts.

Installation

Installation instructions are in the README

Configuration

Run circleci auth login to authenticate with your CircleCI account. You can also set the CIRCLE_TOKEN environment variable.

Model Context Protocol

The CLI supports the MCP protocol. To enable it, run:

Claude:

circleci mcp claude enable # Enable in Claude desktop
claude mcp add-from-claude-desktop -s user # Add with current user scope

Cursor:

circleci mcp cursor enable

VS Code:

circleci mcp vscode enable

Support

Report bugs or search for existing feature requests in our issue tracker

Reference

Work with CircleCI from the command line.

Global Flags

CI Commands

circleci artifact <job-id> [flags]

List and download a job’s artifact files

Arguments:

is the UUID of the job whose artifacts you want to list or download, e.g. 5034460f-c7c4-4c43-9457-de07e2029e7b.

circleci config <command>

Generate, validate, process and pack config YAML

circleci config generate [path]

Generate .circleci/config.yml from a repository scan

circleci config pack <path>

Bundle split config files into a single YAML document

Arguments:

is the path to a split config directory to pack, e.g. “.circleci” or “src/ci”. The directory structure is mapped to YAML keys in the merged document.

circleci config process <path> [flags]

Compile and expand a pipeline config file

Arguments:

is the path to a pipeline config file to compile, e.g. “.circleci/config.yml”. Pass “-” to read the config from stdin.

circleci config validate [flags]

Validate a pipeline config file

circleci job <command>

Inspect a job’s details, output and artifacts

circleci job artifact <job-id> [flags]

List or download artifacts for a job

Arguments:

is the UUID of the job whose artifacts to list or download. Job UUIDs are shown in the output of “circleci workflow get” and “circleci run get –json”.

circleci job get <job-id> [flags]

Get job details

Arguments:

is the UUID of the job to look up. Job UUIDs are shown in the output of “circleci workflow get” and “circleci run get –json”.

circleci job output <command>

Work with job step output

circleci job output get <job-id> [flags]

Get the output of a job step

Arguments:

is the UUID of the job whose step output to fetch. Job UUIDs are shown in the output of “circleci workflow get” and “circleci job get”. Use –step-num to select which step’s output to read.

circleci job output list <job-id> [flags]

List a job’s steps with their output

Arguments:

is the UUID of the job whose steps and output to list. Job UUIDs are shown in the output of “circleci workflow get” and “circleci job get”.

circleci pipeline <command>

Define what will happen in a run

circleci pipeline create [flags]

Create a pipeline definition

circleci pipeline list [flags]

List pipeline definitions for a project

Aliases:

circleci pipeline ls

circleci pipeline run [flags]

Trigger a new pipeline run

circleci run <command>

Trigger, watch and cancel CI runs

circleci run cancel <run-number-or-id> [flags]

Cancel a run

Arguments:

identifies the run to cancel. It can be:

• a run UUID (shown in “circleci run list –json”)
• a run number (shown in “circleci run list”); the project is inferred from the git remote unless overridden with –project

circleci run get [<run-id>] [flags]

Get a run’s status

Arguments:

is optional and is the UUID of the run to look up. When omitted, the latest run is resolved from the project and branch inferred from the current git repository’s remote and checked-out branch (override with –project and –branch).

circleci run list [flags]

List recent runs for a project

Aliases:

circleci run ls

circleci run open [flags]

Open the current project’s runs page in the browser

circleci run trigger [flags]

Trigger a new run

circleci run watch [<run-id>] [flags]

Watch a run until it completes

Arguments:

is optional and selects the run to watch. It can be:

• a run UUID (shown in “circleci run list –json”)
• a run number (shown in “circleci run list”); the project is inferred from the git remote unless overridden with –project

When omitted, the latest run for the current branch is watched (override the branch with –branch, or match a commit with –sha).

circleci workflow <command>

Inspect, rerun and cancel workflows (job graphs)

circleci workflow cancel <workflow-id> [flags]

Cancel a running workflow

Arguments:

is the UUID of the workflow to cancel. Workflow IDs are shown in the output of “circleci run get”.

circleci workflow get <workflow-id> [flags]

Get workflow details

Arguments:

is the UUID of the workflow to look up. Workflow IDs are shown in the output of “circleci run get”.

circleci workflow list [<run-id>] [flags]

List workflows for a run or recent runs

Arguments:

is optional and selects a single run. It can be:

• a run UUID (shown in “circleci run list –json”)
• a run number (shown in “circleci run list”); the project is inferred from the git remote unless overridden with –project

When omitted, workflows for recent runs in the current project are listed, grouped by run.

Aliases:

circleci workflow ls

circleci workflow rerun <workflow-id> [flags]

Rerun a workflow

Arguments:

is the UUID of the workflow to rerun. Workflow IDs are shown in the output of “circleci run get”.

Management Commands

circleci certificate <command>

Manage iOS code signing certificates

circleci certificate delete <cert-id> [flags]

Delete an iOS certificate

Arguments:

is the ID of the certificate to delete (see: circleci certificate list).

Aliases:

circleci certificate rm

circleci certificate list [flags]

List uploaded iOS certificates

Aliases:

circleci certificate ls

circleci certificate upload [flags]

Upload a .p12 certificate

circleci context <command>

Manage secret env vars shared across pipelines

circleci context create <name> [flags]

Create a new context

Arguments:

The name for the new context, e.g. “build-secrets”.

circleci context delete <context-id|context-name> [flags]

Delete a context

Arguments:

A context can be specified in the form:

• “context-name”
• by ID, e.g. 849e7902-802f-4082-8a70-da77dcd084e3

Aliases:

circleci context rm

circleci context get <context-id|context-name> [flags]

Get details of a context

Arguments:

A context can be specified in the form:

• “context-name”
• by ID, e.g. 849e7902-802f-4082-8a70-da77dcd084e3

circleci context list [flags]

List contexts for an organization

Aliases:

circleci context ls

circleci context open [flags]

Open the contexts settings page in the browser

circleci context restriction <command>

Manage context restrictions

circleci context restriction create <context-id|context-name> [flags]

Add a restriction to a context

Arguments:

A context can be specified in the form:

• “context-name”
• by ID, e.g. 849e7902-802f-4082-8a70-da77dcd084e3

circleci context restriction delete <context-id|context-name> [flags]

Delete a restriction from a context

Arguments:

A context can be specified in the form:

• “context-name”
• by ID, e.g. 849e7902-802f-4082-8a70-da77dcd084e3

Aliases:

circleci context restriction rm

circleci context secret <command>

Manage context environment variables

circleci context secret delete <context-id|context-name> [flags]

Delete an environment variable from a context

Arguments:

A context can be specified in the form:

• “context-name”
• by ID, e.g. 849e7902-802f-4082-8a70-da77dcd084e3

Aliases:

circleci context secret rm

circleci context secret list <context-id|context-name> [flags]

List environment variables in a context

Arguments:

A context can be specified in the form:

• “context-name”
• by ID, e.g. 849e7902-802f-4082-8a70-da77dcd084e3

Aliases:

circleci context secret ls

circleci context secret set <context-id|context-name> [flags]

Set an environment variable in a context

Arguments:

A context can be specified in the form:

• “context-name”
• by ID, e.g. 849e7902-802f-4082-8a70-da77dcd084e3

circleci deploy <command>

Track released components and versions

circleci deploy init [flags]

Instrument your config for deploy tracking

circleci deploy list [flags]

List recent deploys

Aliases:

circleci deploy ls

circleci deploy open [flags]

Open the deploys page in the browser

circleci dlc <command>

Purge a project’s Docker layer cache (DLC)

circleci dlc purge --project <slug> [flags]

Purge the Docker Layer Cache for a project

circleci envvar <command>

List, set and delete a project’s environment variables

circleci envvar delete <name> [flags]

Delete a project environment variable

Arguments:

is the name of the environment variable to delete from the project. This action is irreversible.

Aliases:

circleci envvar rm

circleci envvar list [flags]

List project environment variables

Aliases:

circleci envvar ls

circleci envvar set <name> <value> [flags]

Set a project environment variable

Arguments:

is the name of the environment variable to create or update. is the value to store; it is never retrievable after being set and is masked in all subsequent list output.

circleci namespace <command>

Manage the org namespace orbs publish under

circleci namespace create <name> --org <org> [flags]

Create a namespace

Arguments:

is the namespace name to create. It must be globally unique across CircleCI, e.g. “myorg”.

circleci namespace delete <name> [flags]

Delete a namespace and all its orbs

Arguments:

is the name of the namespace to delete, e.g. “myorg”.

Aliases:

circleci namespace rm

circleci namespace get <name> [flags]

Get details of a namespace

Arguments:

is the name of the namespace to look up, e.g. “myorg”.

circleci namespace rename <name> <new-name> [flags]

Rename a namespace

Arguments:

• is the current name of the namespace, e.g. “oldname”.
• is the new name to assign, e.g. “newname”.

circleci orb <command>

Create, publish and inspect orbs (reusable config)

circleci orb add-to-category <ns>/<orb> <category>

Add an orb to a registry category

Arguments:

• /: the orb to add, as “namespace/orb-name”
• : the registry category name, e.g. “Testing”

circleci orb create <namespace>/<orb> [flags]

Reserve an orb name in a namespace

Arguments:

• /: the orb name to reserve, as “namespace/orb-name”. The namespace must already exist.

circleci orb diff <ns>/<orb> --from <v1> --to <v2> [flags]

Show a unified diff between two orb versions

Arguments:

• /: the orb to diff, as “namespace/orb-name”

circleci orb get <ns>/<orb>[@<version>]/<orb-id> [flags]

Get orb metadata and statistics

Arguments:

An orb can be specified in the form:

• “namespace/orb-name”, optionally with a version, e.g. “namespace/orb-name@1.2.3”
• by orb ID (UUID), e.g. 849e7902-802f-4082-8a70-da77dcd084e3

circleci orb list [<namespace>] [flags]

List orbs in the registry

Arguments:

• : optional. When given, lists all orbs in that namespace. When omitted, lists certified orbs globally.

Aliases:

circleci orb ls

circleci orb list-categories [flags]

List orb registry categories

circleci orb pack <path>

Pack a multi-file orb directory into a single YAML

Arguments:

• : path to an orb source directory or a single orb YAML file.

circleci orb process <path> [flags]

Validate and print expanded orb YAML

Arguments:

• : path to an orb YAML file. Pass ‘-’ to read from stdin.

circleci orb publish <command>

Publish orb versions

circleci orb publish increment <path> <ns>/<orb> --bump major|minor|patch [flags]

Increment and publish a new orb version

Arguments:

• : path to the orb YAML to publish. Pass ‘-’ to read from stdin.
• /: the orb to publish, as “namespace/orb-name”

circleci orb publish promote <ns>/<orb>@dev:<label> --bump major|minor|patch [flags]

Promote a dev orb version to a stable semver

Arguments:

• /@dev:: the dev version to promote, e.g. “namespace/orb-name@dev:my-branch”

circleci orb remove-from-category <ns>/<orb> <category>

Remove an orb from a registry category

Arguments:

• /: the orb to remove, as “namespace/orb-name”
• : the registry category name, e.g. “Testing”

circleci orb source <ns>/<orb>[@<version>]

Print the YAML source of an orb version

Arguments:

• /[@]: the orb to print, as “namespace/orb-name”. Optionally append @ (e.g. @1.2.3, @volatile, or @dev:my-branch). When omitted, the latest published version is shown.

circleci orb unlist <ns>/<orb> [flags]

Hide or restore an orb in the registry

Arguments:

• /: the orb to update, as “namespace/orb-name”

circleci orb validate <path> [flags]

Validate an orb YAML file

Arguments:

• : path to an orb YAML file. Pass ‘-’ to read from stdin.

circleci policy <command>

Govern config with Rego security policies

circleci policy decide [flags]

Evaluate a config against remote policies

circleci policy diff <path> [flags]

Show diff between local and remote policy bundles

Arguments:

is the path to a local directory of .rego policy files, e.g. “./policies”. Its contents are compared against the remote policy bundle.

circleci policy fetch [policy-name] [flags]

Download the remote policy bundle

circleci policy logs [decision-id] [flags]

Get policy decision logs

circleci policy push <path> [flags]

Push a policy bundle to CircleCI

Arguments:

is the path to a local directory of .rego policy files, e.g. “./policies”. Its contents are uploaded as the policy bundle, replacing the existing bundle.

circleci policy settings <command>

Manage policy enforcement settings

circleci policy settings get [flags]

Get policy enforcement settings

circleci policy settings set [flags]

Update policy enforcement settings

circleci project <command>

List, follow and configure CircleCI projects

circleci project create [project-name] --org <vcs/org-slug> [flags]

Create a new project

Arguments:

[project-name] is the name for the new project and is optional. When omitted, the current git repository’s name is used: in a terminal you are prompted with it as the default, and in non-interactive mode it is used automatically.

circleci project dlc <command>

Purge a project’s Docker layer cache (DLC)

circleci project dlc purge --project <slug> [flags]

Purge the Docker Layer Cache for a project

circleci project envvar <command>

List, set and delete a project’s environment variables

circleci project envvar delete <name> [flags]

Delete a project environment variable

Arguments:

is the name of the environment variable to delete from the project. This action is irreversible.

Aliases:

circleci project envvar rm

circleci project envvar list [flags]

List project environment variables

Aliases:

circleci project envvar ls

circleci project envvar set <name> <value> [flags]

Set a project environment variable

Arguments:

is the name of the environment variable to create or update. is the value to store; it is never retrievable after being set and is masked in all subsequent list output.

circleci project follow [flags]

Follow a project

circleci project get [flags]

Show project details

circleci project link [flags]

Bind this checkout to a CircleCI project

circleci project list [flags]

List followed projects

Aliases:

circleci project ls

circleci project open [flags]

Open the project page in the browser

circleci project trigger <command>

Manage project triggers

circleci project trigger create [flags]

Create a new project trigger

circleci project trigger list [flags]

List triggers for a pipeline definition

Aliases:

circleci project trigger ls

circleci runner <command>

Manage self-hosted runners

circleci runner config <resource-class> [flags]

Generate a runner agent configuration file

Arguments:

is the runner resource class to generate config for, in the form “namespace/name” (e.g. my-org/my-runner).

circleci runner instance <command>

Manage runner instances

circleci runner instance list [flags]

List connected runner instances

Aliases:

circleci runner instance ls

circleci runner open [flags]

Open the runners inventory page in the browser

circleci runner resource-class <command>

Manage runner resource classes

circleci runner resource-class create <namespace>/<name> [flags]

Create a runner resource class

Arguments:

The resource class name must be given in the form “namespace/name”, where namespace is your organization name (e.g. my-org/my-runner).

circleci runner resource-class delete <namespace>/<name> [flags]

Delete a runner resource class

Arguments:

The resource class to delete, given in the form “namespace/name”, where namespace is your organization name (e.g. my-org/my-runner).

Aliases:

circleci runner resource-class rm

circleci runner resource-class list [flags]

List runner resource classes

Aliases:

circleci runner resource-class ls

circleci runner task [flags]

Show task counts for a runner resource class

circleci runner token <command>

Manage runner tokens

circleci runner token create <resource-class> [flags]

Create a token for a resource class

Arguments:

is the runner resource class to create a token for, in the form “namespace/name” (e.g. my-org/my-runner).

circleci runner token delete <token-id> [flags]

Delete a runner token

Arguments:

is the ID of the token to delete (a UUID). Find token IDs with: circleci runner token list –resource-class <namespace/name>

Aliases:

circleci runner token rm

circleci runner token list [flags]

List tokens for a resource class

Aliases:

circleci runner token ls

circleci signing-config <command>

Manage iOS signing configs

circleci signing-config create [flags]

Create an iOS signing config

circleci signing-config delete <signing-config-id> [flags]

Delete an iOS signing config

Arguments:

is the ID of the signing config to delete (see: circleci signing-config list).

Aliases:

circleci signing-config rm

circleci signing-config list [flags]

List iOS signing configs

Aliases:

circleci signing-config ls

User Commands

circleci auth <command>

Log in, sign up and check your CircleCI identity

circleci auth id [flags]

Show the device ID for this CLI installation

circleci auth login [flags]

Log in to a CircleCI account

circleci auth logout [flags]

Log out of a CircleCI account

circleci auth me [flags]

Display active account information

circleci auth signup [flags]

Sign-up for a new CircleCI account

circleci completion <command>

Install, remove or print shell completions

circleci completion install

Install shell completion into your shell profile

circleci completion uninstall

Remove shell completion from your shell profile

circleci mcp

Run the CLI as an MCP server for AI tools

circleci mcp claude

Manage Claude Desktop MCP servers

circleci mcp claude disable [flags]

Remove server from Claude config

circleci mcp claude enable [flags]

Add server to Claude config

circleci mcp claude list [flags]

Show Claude MCP servers

circleci mcp cursor

Manage Cursor MCP servers

circleci mcp cursor disable [flags]

Remove server from Cursor config

circleci mcp cursor enable [flags]

Add server to Cursor config

circleci mcp cursor list [flags]

Show Cursor MCP servers

circleci mcp start [flags]

Start the MCP server

circleci mcp stream [flags]

Stream the MCP server over HTTP

circleci mcp tools [flags]

Export tools as JSON

circleci mcp vscode

Manage VSCode MCP servers

circleci mcp vscode disable [flags]

Remove server from VSCode config

circleci mcp vscode enable [flags]

Add server to VSCode config

circleci mcp vscode list [flags]

Show VSCode MCP servers

circleci my <command>

Show resources for the authenticated user

circleci my runs [flags]

List your recent runs grouped by project

Aliases:

circleci my run

circleci onboard [path] [flags]

Guided onboarding: scan, test, generate config, sign up

circleci setting <command>

Configure the CLI itself (token, host, defaults)

circleci setting list [flags]

List current CLI settings

Aliases:

circleci setting ls

circleci setting set <key> <value>

Set a CLI setting

Arguments:

• is the setting to change: token, host, telemetry, or theme.
• is the value to store. Pass “-” to read it from stdin. May be omitted for “theme” to pick interactively.

circleci setting unset <key>

Remove a stored CLI setting

Arguments:

is the setting to remove. Currently only “token” is supported.

Extension Commands

circleci agent

Extension (circleci-agent)

Additional Commands

circleci api <path> [flags]

Call the CircleCI REST API directly

Arguments:

is the request path. It is relative to /api/v3 by default (e.g. “projects/{project-id}”). To target a different version prefix, include it explicitly, e.g. “api/v2/me”.

circleci version [flags]

Print version information