# CircleCI CLI
> Command-line interface to CircleCI for use in your terminal or scripts. This is the full command reference, generated from the live command tree.
# 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](https://github.com/CircleCI-Public/circleci-cli#readme)
## Configuration
Run `circleci auth login` to authenticate with your CircleCI account. You can also set the
`CIRCLE_TOKEN` environment variable.
## Get Running
Run `circleci run get` to view the runs for the current project in an interactive terminal UI (TUI).
## Model Context Protocol
The CLI supports the MCP protocol. To enable it, run:
Claude:
```shell
circleci mcp claude enable # Enable in Claude desktop
claude mcp add-from-claude-desktop -s user # Add with current user scope
```
Cursor:
```shell
circleci mcp cursor enable
```
VS Code:
```shell
circleci mcp vscode enable
```
## Support
Report bugs or search for existing feature requests in our
[issue tracker](https://github.com/CircleCI-Public/circleci-cli/issues)
# Environment
`circleci` reads the following environment variables to configure authentication, output, and
behavior. Each takes precedence over the corresponding stored setting, so they are useful for
scripting and CI where you want explicit, per-invocation control.
`CIRCLE_TOKEN`: an authentication token that will be used for API requests. Setting this avoids
being prompted to authenticate and takes precedence over previously stored credentials.
`CIRCLE_HOST`: specify the CircleCI hostname.
`NO_COLOR`: set to any value to avoid printing ANSI escape sequences for color output.
The `--no-color` flag has the same effect.
`CIRCLE_NO_COLOR`: set to any value to disable ANSI color output, same as `NO_COLOR`.
`CIRCLE_NO_INTERACTIVE`: set to any value to suppress all interactive prompts.
`CI`: when set (as CI systems do), interactive prompts, the animated spinner, and update
notifications are all disabled automatically.
`CIRCLE_SPINNER_DISABLED`: set to any value to replace the animated spinner with plain text.
`CIRCLE_NO_UPDATE_CHECK`: set to any value to disable checking for newer CLI and
extension releases. Same effect as `circleci setting set update-check off`.
`CIRCLE_NO_PAGER`: set to any value to print long output directly instead of through a pager.
`PAGER`: names the pager program to send long output through (for example `less` or `more`).
When unset, a built-in scrollable viewer is used. Set it to `cat` or an empty value to disable
paging entirely.
`CIRCLE_NO_TELEMETRY`: set to any value to disable telemetry.
`NO_ANALYTICS`: set to any value to disable telemetry.
`DO_NOT_TRACK`: set to any value to disable telemetry.
# Formatting
By default, the result of `circleci` commands are output in markdown text format.
Some commands support passing the `--json` flag, which converts the output to JSON format.
Once in JSON, the output can be further formatted according to a required formatting string by
adding either the `--jq` or `--template` flag. This is useful for selecting a subset of data,
creating new data structures, displaying the data in a different format, or as input to another
command line script.
The `--json` flag requires a comma separated list of fields to fetch. To view the possible JSON
field names for a command omit the string argument to the `--json` flag when you run the command.
Note that you must pass the `--json` flag and field names to use the `--jq` flag.
The `--jq` flag requires a string argument in jq query syntax, and will only print
those JSON values which match the query. jq queries can be used to select elements from an
array, fields from an object, create a new array, and more. The `jq` utility does not need
to be installed on the system to use this formatting directive. When connected to a terminal,
the output is automatically pretty-printed. To learn about jq query syntax, see:
## Examples
### Default output format
`circleci auth me`
```text
# User
- ID: `c257a143-1fde-4dfe-8cf9-2a85a955f1f7`
- Name: Your Name
- Login: username
- Avatar URL: https://avatars.githubusercontent.com/u/9812739817239?v=4
```
### Adding the --json flag with a list of field names
`circleci auth me --json`
```json
{
"name": "Your Name",
"login": "username",
"id": "c257a143-1fde-4dfe-8cf9-2a85a955f1f7",
"avatar_url": "https://avatars.githubusercontent.com/u/9812739817239?v=4"
}
```
### Adding the --jq flag and selecting a field
`circleci auth me --json --jq '.login'`
```text
username
```
# Reference
Work with CircleCI from the command line.
## Global Flags
| Flag | Description |
| --------------------- | ------------------------------------------------------------ |
| `-c, --config string` | Path to config file (default: ~/.config/circleci/config.yml) |
| `--debug` | Enable debug logging |
| `--no-color` | Disable ANSI color output (same as setting NO_COLOR) |
| `-q, --quiet` | Suppress informational output. Data on stdout is unaffected |
## CI Commands
### `circleci artifact [flags]`
List and download a job's artifact files
List or download artifacts produced by a CircleCI job.
Pass the job UUID to list its artifacts. Use --output to save
them to a local directory.
JSON fields: path, url, execution
| Flag | Description |
| --------------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `-o, --output string` | Download artifacts into this directory |
**Arguments:**
`` is the UUID of the job whose artifacts you want to
list or download,
for example. `5034460f-c7c4-4c43-9457-de07e2029e7b`.
**Examples:**
- List artifacts for a job:
`circleci artifact 5034460f-c7c4-4c43-9457-de07e2029e7b`
- Download all artifacts into ./artifacts:
`circleci artifact 5034460f-c7c4-4c43-9457-de07e2029e7b --output ./artifacts`
- Output as JSON for scripting:
`circleci artifact 5034460f-c7c4-4c43-9457-de07e2029e7b --json`
### `circleci config `
Generate, validate, process and pack config YAML
Work with the pipeline configuration file at .circleci/config.yml.
This group manages the pipeline YAML that CircleCI executes. For CLI
tool settings (API token, host, defaults), use 'circleci setting'.
#### `circleci config generate [path]`
Generate .circleci/config.yml from a repository scan
Detect the language stack, container image, and setup commands for a
repository, then write a starter pipeline to `/.circleci/config.yml`.
If no supported stack is detected, a minimal cimg/base:stable template
with a placeholder build step is written instead so you have something
to iterate on.
If a config file already exists at that path, generate does not overwrite
it; it prints a confirmation and exits successfully. The .circleci/
directory is created if needed, and the file is written atomically.
**Arguments:**
`` is optional and is the directory to scan. Defaults to
the current directory.
**Examples:**
- Generate a config for the current directory:
`circleci config generate`
- Generate a config for a specific project path:
`circleci config generate ./my-app`
- Re-run is a no-op when a config already exists:
`circleci config generate`
- ✓ Using existing config at .circleci/config.yml
#### `circleci config pack `
Bundle split config files into a single YAML document
Merge a split CircleCI config directory into the single YAML document CircleCI
accepts, printed to stdout.
The directory structure maps to YAML keys: .circleci/config.yml merges at the
top level, and .circleci/jobs/build.yml becomes jobs.build. Files whose names
begin with "@" merge at the current level instead of nesting under a key.
**Arguments:**
`` is the path to a split config directory to pack,
for example, `.circleci` or `src/ci`. The directory structure is
mapped to YAML keys in the merged document.
**Examples:**
- Pack the default config directory:
`circleci config pack .circleci`
- Pack and pipe to validate:
`circleci config pack .circleci | circleci config validate --config -`
- Pack a custom directory:
`circleci config pack src/ci`
#### `circleci config process [flags]`
Compile and expand a pipeline config file
Compile a CircleCI pipeline config and print the fully expanded YAML —
orbs inlined, matrices expanded, parameters resolved.
No API token is required; without one, only public orbs resolve.
Private and namespaced orbs need a token and resolve against your org, taken
from --org, a 'circleci project link' binding, or the git remote, in that order.
| Flag | Description |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| `-n, --next` | Enable config next which previews upcoming potentially breaking config changes |
| `--org string` | Organization slug (e.g. gh/myorg) or UUID for private orb resolution; defaults to git remote |
| `--pipeline-parameters string` | Pipeline parameters as a YAML map or path to a YAML file |
**Arguments:**
`` is the path to a pipeline config file to compile,
for example, `.circleci/config.yml`. Pass `-` to read the config
from stdin.
**Examples:**
- Process the default config:
`circleci config process .circleci/config.yml`
- Process with pipeline parameters:
`circleci config process .circleci/config.yml --pipeline-parameters 'env: staging'`
- Process against a specific org (otherwise inferred from the git remote):
`circleci config process .circleci/config.yml --org gh/myorg`
- Read from stdin:
`cat .circleci/config.yml | circleci config process -`
#### `circleci config validate [] [flags]`
Validate a pipeline config file
No API token is required; without one, only public orbs resolve.
Private and namespaced orbs need a token and resolve against your org, taken
from --org, a 'circleci project link' binding, or the git remote, in that order.
JSON fields (--json): valid (bool), compiled_yaml (string, when valid), errors (array of compilation messages, when invalid)
| Flag | Description |
| --------------------- | -------------------------------------------------------------------------------------------- |
| `-c, --config string` | Path to config file (use "-" for stdin) (default ".circleci/config.yml") |
| `--json` | Output as JSON |
| `-n, --next` | Enable config next which previews upcoming potentially breaking config changes |
| `--org string` | Organization slug (e.g. gh/myorg) or UUID for private orb resolution; defaults to git remote |
**Arguments:**
`` is the pipeline config file to validate, by default
`.circleci/config.yml`. Pass `-` to read the config from stdin.
**Examples:**
- Validate the default config file:
`circleci config validate`
- Validate a specific file:
`circleci config validate path/to/config.yml`
- Validate against a specific org (otherwise inferred from the git remote):
`circleci config validate --org gh/myorg`
- Validate and output as JSON:
`circleci config validate --json`
### `circleci job `
Inspect a job's details, output and artifacts
Work with CircleCI jobs.
Jobs are the individual units of work within a workflow.
#### `circleci job artifact [flags]`
List or download artifacts for a job
List or download artifacts produced by a specific job.
Pass the job UUID to list its artifacts. Use --output to save
them to a local directory.
JSON fields: path, url, execution
| Flag | Description |
| --------------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `-o, --output string` | Download artifacts into this directory |
**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`.
**Examples:**
- List artifacts for a job:
`circleci job artifact 5034460f-c7c4-4c43-9457-de07e2029e7b`
- Download artifacts into ./artifacts:
`circleci job artifact 5034460f-c7c4-4c43-9457-de07e2029e7b --output ./artifacts`
- Output as JSON:
`circleci job artifact 5034460f-c7c4-4c43-9457-de07e2029e7b --json`
#### `circleci job get [flags]`
Get job details
Display the status and steps of a CircleCI job.
Job IDs are shown in the output of 'circleci workflow get' and
'circleci run get --json'.
JSON fields: id, name, type, status, started_at, stopped_at, project_id, pipeline_id, workflow_id, executions[].index/steps[].name/type/status/duration/exit_code
| Flag | Description |
| ------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
**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`.
**Examples:**
- Get job details by UUID:
`circleci job get 8e50c384-0083-43d0-bc8f-93f0db589d6b`
- Output as JSON:
`circleci job get 8e50c384-0083-43d0-bc8f-93f0db589d6b --json`
- Get a specific field with jq:
`circleci job get 8e50c384-0083-43d0-bc8f-93f0db589d6b --json | jq '.status'`
#### `circleci job open `
Open job in browser
**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`.
**Examples:**
- Open job by UUID:
`circleci job open 8e50c384-0083-43d0-bc8f-93f0db589d6b`
#### `circleci job output `
Work with job step output
Fetch the raw stdout and stderr produced by a job's steps.
Steps are identified by their step number within a job; for parallel
jobs, an execution index selects which executor's output to fetch.
##### `circleci job output get [flags]`
Get the output of a job step
Fetch the raw stdout and stderr of a single step within a job. Both streams
are fetched in parallel and printed together, stdout first.
Output passes through unchanged on a terminal and is rendered to plain text
when redirected (ANSI stripped, progress redraws collapsed). --strip-ansi
forces either behaviour.
| Flag | Description |
| ----------------- | ---------------------------------------------------------------------------------------------- |
| `--condensed` | Fetch error-relevant lines only, filtered server-side (experimental) |
| `--execution int` | Parallel execution index to read output from |
| `--step-num int` | Step number whose output to fetch (required) |
| `--strip-ansi` | Force (or with =false, disable) ANSI stripping; defaults to stripping only when not a terminal |
**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.
**Examples:**
- Get the output of step 3 in a job:
`circleci job output get 8e50c384-0083-43d0-bc8f-93f0db589d6b --step-num 3`
- Get the output of step 3 from the second parallel execution:
`circleci job output get 8e50c384-0083-43d0-bc8f-93f0db589d6b --step-num 3 --execution 1`
- Pipe the output to a file:
`circleci job output get 8e50c384-0083-43d0-bc8f-93f0db589d6b --step-num 3 > step.log`
- Pipe condensed output to an AI CLI tool:
`circleci job output get 8e50c384-0083-43d0-bc8f-93f0db589d6b --step-num 3 --condensed | llm "Why did this fail?"`
##### `circleci job output list [flags]`
List a job's steps with their output
List every step in a job alongside its terminal-processed output.
Each step's output is replayed through a virtual terminal, so progress
redraws collapse to the final state a human would have seen. --tail limits
the rendered view only; --json always carries each step's full output.
JSON fields: id, name, execution, steps[].num/name/type/phase/outcome/started_at/stopped_at/exit_code/command/output
| Flag | Description |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `--execution int` | Parallel execution index to list output from |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--tail int` | Show only the last N lines of each step's output in the rendered view (0 for all) (default 200) |
**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`.
**Examples:**
- List the steps and output of a job:
`circleci job output list 8e50c384-0083-43d0-bc8f-93f0db589d6b`
- List output for the second parallel execution:
`circleci job output list 8e50c384-0083-43d0-bc8f-93f0db589d6b --execution 1`
- As JSON, with the output of the failing step:
`circleci job output list 8e50c384-0083-43d0-bc8f-93f0db589d6b --json | jq '.steps[] | select(.exit_code != 0) | .output'`
- Show every line of every step in the rendered view:
`circleci job output list 8e50c384-0083-43d0-bc8f-93f0db589d6b --tail 0`
#### `circleci job resource-usage `
Work with a job's CPU and memory usage
Inspect how much of its executor a job actually used.
CPU and memory are sampled at a fixed interval for the length of each
parallel execution, and reported against the limits of the resource class
the job ran on — so a job that needs a smaller (or larger) executor shows
it.
##### `circleci job resource-usage get [flags]`
Chart a job's CPU and memory usage
Chart how much CPU and memory a job used against its resource class limits.
Peak of limit sizes the executor: under 50% on both means a smaller class fits.
Parallel executions are overlaid in color, or charted apart past 5 (--chart).
JSON fields: id, resource_class.name/cpu_count/memory_limit_bytes, executions[].execution/interval_ms/samples/duration_seconds/cpu_cores/memory_bytes/network_rx_bytes/network_tx_bytes/cpu.min/mean/max/peak_percent_of_limit (and memory.*)
| Flag | Description |
| ----------------- | ------------------------------------------------------------------------------------- |
| `--chart string` | Plot parallel executions together or apart: auto\|combined\|separate (default "auto") |
| `--execution int` | Parallel execution index to report on (default all) (default -1) |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
**Arguments:**
`` is the UUID of the job whose usage to fetch. Job UUIDs are
shown in the output of `circleci workflow get` and `circleci job get`.
**Examples:**
- Chart a job's CPU and memory usage:
`circleci job resource-usage get 0dc4d8df-8f7e-41b0-a3ef-88066a5465c1`
- One chart per execution, however few there are:
`circleci job resource-usage get 0dc4d8df-8f7e-41b0-a3ef-88066a5465c1 --chart separate`
- Only the third parallel execution:
`circleci job resource-usage get 0dc4d8df-8f7e-41b0-a3ef-88066a5465c1 --execution 2`
- How close each execution came to its memory limit:
`circleci job resource-usage get 0dc4d8df-8f7e-41b0-a3ef-88066a5465c1 --json | jq '.executions[].memory.peak_percent_of_limit'`
### `circleci pipeline `
Define what will happen in a run
Create and list pipeline definitions for a CircleCI project.
A pipeline definition decides what happens when a run is triggered:
which repository to check out and where to find the config YAML that
CircleCI compiles into workflows. Attach triggers to a definition with
'circleci project trigger create'.
#### `circleci pipeline create [flags]`
Create a pipeline definition
Create a new pipeline definition for a CircleCI project: where CircleCI finds
the config YAML, and which repository to check out. Attach triggers to it
afterwards with `circleci project trigger create`.
Required flags must be given in non-interactive mode; a terminal prompts.
JSON fields: id, name, description, created_at, config_source.provider, config_source.file_path, config_source.repo.external_id, config_source.repo.full_name, checkout_source.provider, checkout_source.repo.external_id, checkout_source.repo.full_name
| Flag | Description |
| ---------------------------- | --------------------------------------------------------------------------------- |
| `--checkout-provider string` | Checkout source provider (one of: github_app, github_server) |
| `--checkout-repo-id string` | Checkout source repo external ID |
| `--config-file string` | Config file path (e.g. .circleci/config.yml) |
| `--config-provider string` | Config source provider (one of: github_app, github_server, circleci) |
| `--config-repo-id string` | Config source repo external ID (required for github_app, github_server) |
| `--description string` | Pipeline definition description |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--name string` | Pipeline definition name (required) |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
| `--project-id string` | Project UUID (overrides --project) |
**Examples:**
- Create a pipeline definition using GitHub App:
`circleci pipeline create --project gh/myorg/myrepo --name "my-pipeline" --config-provider github_app --config-repo-id 123456789 --config-file .circleci/config.yml --checkout-provider github_app --checkout-repo-id 123456789`
- Create with a description and output as JSON:
`circleci pipeline create --name "release-pipeline" --description "Runs on tagged releases" --config-provider github_app --config-repo-id 123456789 --config-file .circleci/release.yml --checkout-provider github_app --checkout-repo-id 123456789 --json`
- Create using a direct project UUID (skips project info lookup):
`circleci pipeline create --project-id a1b2c3d4-... --name "nightly" --config-provider github_app --config-repo-id 123456789 --config-file .circleci/nightly.yml --checkout-provider github_app --checkout-repo-id 123456789`
#### `circleci pipeline list [flags]`
List pipeline definitions for a project
List all pipeline definitions for a CircleCI project.
JSON fields: id, name, description, created_at, config_source.provider, config_source.file_path, config_source.repo.external_id, config_source.repo.full_name, checkout_source.provider, checkout_source.repo.external_id, checkout_source.repo.full_name
| Flag | Description |
| --------------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
| `--project-id string` | Project UUID (overrides --project) |
**Aliases:**
`circleci pipeline ls`
**Examples:**
- List pipeline definitions for the current repository's project:
`circleci pipeline list`
- List pipeline definitions for a specific project:
`circleci pipeline list --project gh/myorg/myrepo`
- Output as JSON for scripting:
`circleci pipeline list --json`
- Filter by config provider:
`circleci pipeline list --json --jq '.[] | select(.config_source.provider == "github_app")'`
#### `circleci pipeline run [flags]`
Trigger a new pipeline run
Trigger a new pipeline run using the recommended CircleCI v2 API.
In a terminal, a missing --definition-id or --branch/--tag is prompted for; in
non-interactive mode both are optional. --branch and --tag are mutually
exclusive and each sets both the config-fetch and checkout revision.
A skipped pipeline (e.g. a [ci skip] commit message) exits 0 and prints why.
JSON fields: id, state, number, created_at, triggered — or triggered, message when skipped.
| Flag | Description |
| ------------------------ | --------------------------------------------------------------------------------- |
| `-b, --branch string` | Branch for config fetch and checkout (mutually exclusive with --tag) |
| `--definition-id string` | Pipeline definition UUID to run (prompted interactively if omitted) |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--param stringArray` | Pipeline parameter as key=value (repeatable) |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
| `-t, --tag string` | Tag for config fetch and checkout (mutually exclusive with --branch) |
**Examples:**
- Trigger a pipeline interactively — pick definition and branch from menus:
`circleci pipeline run --project gh/myorg/myrepo`
- Trigger a specific definition on a branch non-interactively:
`circleci pipeline run --project gh/myorg/myrepo --definition-id 2338d0ae-5541-4bbf-88a2-55e9f7281f80 --branch main`
- Trigger on a tag with parameters:
`circleci pipeline run --project gh/myorg/myrepo --definition-id 2338d0ae-5541-4bbf-88a2-55e9f7281f80 --tag v1.2.3 --param deploy_env=staging`
- Output as JSON for scripting:
`circleci pipeline run --project gh/myorg/myrepo --definition-id 2338d0ae-5541-4bbf-88a2-55e9f7281f80 --branch main --json`
### `circleci run `
Trigger, watch and cancel CI runs
Work with CircleCI runs.
A run is created each time a trigger fires for a pipeline. It carries
the VCS context for that firing and groups the workflows it produced;
each workflow in turn contains jobs.
#### `circleci run cancel [flags]`
Cancel a run
Cancel a running CircleCI run by number or UUID.
Cancelling a run stops all in-progress workflows and jobs within it.
Workflows that have already completed are unaffected.
| Flag | Description |
| ------------------ | --------------------------------------------------------------- |
| `-f, --force` | skip confirmation prompt |
| `--project string` | Project slug (e.g. gh/org/repo); used when cancelling by number |
**Arguments:**
`` identifies the run to cancel. A run can be specified by its UUID or number:
- A run UUID, as shown in `circleci run list --json`
- A run number, as shown in `circleci run list`.
The project is inferred from the git remote unless overridden with `--project`.
**Examples:**
- Cancel a run by number (with confirmation):
`circleci run cancel 75`
- Cancel a run by UUID without confirmation:
`circleci run cancel 5034460f-c7c4-4c43-9457-de07e2029e7b --force`
- Cancel the latest run on a branch:
`circleci run list --branch main --json --jq '.[0].id' | xargs circleci run cancel --force`
#### `circleci run get [] [flags]`
Get a run's status
Display the status of a CircleCI run and its workflows.
With no run UUID in an interactive terminal, a picker walks you through the
recent runs; --no-interactive, --json, or a non-interactive session skips it
and resolves the latest run directly.
JSON fields: id, phase, outcome, current_outcome, branch, tag, revision,
repository_url, commit.subject/url/author_name/author_login, created_at,
errors[].type/message, workflows[].id/name/phase/outcome/current_outcome/duration/
jobs[].id/name/phase/outcome/current_outcome/type
| Flag | Description |
| --------------------- | --------------------------------------------------------------------------------- |
| `-b, --branch string` | Branch name (defaults to the current branch, or main when --project is set) |
| `--failure-report` | Print condensed output for every failed step; intended for agent consumption |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `-m, --mine` | Filter to runs owned by you. |
| `--no-interactive` | Skip the interactive picker and resolve the latest run directly |
| `--project string` | Project slug (e.g. gh/org/repo); used for latest-run lookup |
**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`). With
`--project` set, the branch defaults to main unless `--branch` is given.
**Examples:**
- Get the latest run for the current branch:
`circleci run get`
- Get a run by UUID:
`circleci run get 5034460f-c7c4-4c43-9457-de07e2029e7b`
- Output as JSON for scripting:
`circleci run get --json`
- Get only your runs:
`circleci run get --mine`
- Skip the picker and resolve the latest run directly:
`circleci run get --no-interactive`
#### `circleci run list [flags]`
List recent runs for a project
List recent runs for a CircleCI project.
The project is inferred from the current git repository's remote
unless overridden with --project. Use --branch to filter results
to a single branch, or --current-branch (-B) to automatically use
the branch you have checked out.
The markdown table includes the commit subject; the JSON adds the full
commit and repository detail.
JSON fields: id, phase, outcome, current_outcome, branch, tag, revision, repository_url, commit.subject/url/author_name/author_login, created_at
| Flag | Description |
| ---------------------- | --------------------------------------------------------------------------------- |
| `-b, --branch string` | Filter by branch |
| `-B, --current-branch` | Filter by the currently checked-out branch |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--limit int` | Maximum number of runs to show [default: 10] (default 10) |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
**Aliases:**
`circleci run ls`
**Examples:**
- List recent runs for the current project:
`circleci run list`
- Filter to the branch you have checked out:
`circleci run list --current-branch`
- Filter to a specific branch:
`circleci run list --branch main`
- List runs for an explicit project:
`circleci run list --project gh/org/repo`
- Show more results:
`circleci run list --limit 25`
- Output as JSON for scripting:
`circleci run list --json`
#### `circleci run open [flags]`
Open the current project's runs page in the browser
Open the CircleCI runs page for the current project in your
default web browser.
The project is inferred from the current git repository's remote.
Supports GitHub, Bitbucket, and GitLab remotes.
Use --current-branch or --branch/-b to filter runs to a specific branch.
| Flag | Description |
| --------------------- | ----------------------------------------------------------- |
| `-b, --branch string` | Branch name (defaults to current branch) |
| `--project string` | Project slug (e.g. gh/org/repo); used for latest-run lookup |
**Examples:**
- Open runs for the current repo:
`circleci run open`
- Open runs filtered to the current git branch:
`circleci run open --current-branch`
- Open runs filtered to a specific branch:
`circleci run open --branch my-feature`
- Open runs filtered to a specific branch (short flag):
`circleci run open -b main`
- Open when your remote is on CircleCI server:
`circleci run open --host https://circleci.example.com`
#### `circleci run trigger [flags]`
Trigger a new run
Trigger a new run for a CircleCI project.
The project and branch are inferred from the current git repository
unless overridden with --project or --branch.
Pass run parameters with --parameter. Values are parsed as
booleans (true/false), integers, or strings.
JSON fields: id, number, state, created_at
| Flag | Description |
| ------------------------- | --------------------------------------------------------------------------------- |
| `-b, --branch string` | Branch to trigger (defaults to current branch) |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--parameter stringArray` | Run parameter as key=value (repeatable) |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
**Examples:**
- Trigger a run on the current branch:
`circleci run trigger`
- Trigger on a specific branch:
`circleci run trigger --branch main`
- Trigger with run parameters:
`circleci run trigger --parameter deploy_env=staging --parameter run_e2e=true`
- Output the triggered run as JSON:
`circleci run trigger --json`
#### `circleci run watch [] [flags]`
Watch a run until it completes
Monitor a CircleCI run and block until it reaches a terminal state. Without
arguments, watches the latest run for the current branch.
Exit code reflects the result: 0 all workflows succeeded, 1 one or more
failed, 6 cancelled, 8 timed out.
With --sha, polls for up to 2 minutes for a run matching that commit to
appear — useful immediately after git push.
| Flag | Description |
| --------------------- | ---------------------------------------------------------------------- |
| `-b, --branch string` | Branch to watch (defaults to current branch) |
| `--failfast` | Exit as soon as any job fails, without waiting for the rest of the run |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
| `--sha string` | Watch run for this commit SHA; polls up to 2m if not yet created |
| `--timeout duration` | Maximum time to wait for run completion (default 30m0s) |
**Arguments:**
`` is optional: a run UUID (as shown by `circleci run list --json`)
or a run number (as shown by `circleci run list`).
When omitted, the latest run for the current branch is watched.
**Examples:**
- Watch the latest run on the current branch:
`circleci run watch`
- Push and watch in one step:
`git push && circleci run watch --sha $(git rev-parse HEAD)`
- Watch by UUID (e.g. from 'run list --json'):
`circleci run watch 5034460f-c7c4-4c43-9457-de07e2029e7b`
- Watch with a longer timeout:
`circleci run watch --timeout 30m`
- Exit as soon as any job fails:
`circleci run watch --failfast`
### `circleci testresult `
Inspect test results for a job
Work with the test metadata CircleCI collects for a job.
When a job stores test results (via the 'store_test_results' step),
CircleCI parses them into per-test records. Use these commands to
review which tests failed, passed or were skipped without opening the
web UI.
#### `circleci testresult get [flags]`
Get a single test result by name
Get a single test result from a job by its exact name.
When several tests share a name the lookup is ambiguous and fails; narrow it
with `--filter classname=`, or browse with `circleci testresult list`.
JSON fields: classname, name, result, run_time, message
| Flag | Description |
| ------------------ | --------------------------------------------------------------------------------- |
| `--filter ` | Disambiguate by classname= when a name is shared; repeatable |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--plain` | Print only the raw test message, verbatim and unformatted |
**Arguments:**
`` is the UUID of the job whose test results to search. Job
UUIDs are shown in `circleci job get` and `circleci run get --json`.
`` is the exact test name to look up. If more than one test
shares that name, use `--filter classname=` to disambiguate.
**Examples:**
- Get a test by name:
`circleci testresult get 8e50c384-0083-43d0-bc8f-93f0db589d6b TestLogin`
- Disambiguate when the name appears in multiple suites:
`circleci testresult get TestLogin --filter classname=api`
- Print only the raw test message:
`circleci testresult get TestLogin --plain`
- Output as JSON:
`circleci testresult get TestLogin --json`
#### `circleci testresult list [flags]`
List test results for a job
Show the test results recorded for a CircleCI job. Only failed tests are
shown unless --all or a result= filter selects otherwise.
JSON fields: classname, name, result, run_time, message — emitted as one
object per line (JSONL), so --jq runs once per record. See
`circleci help formatting` for aggregating across the stream.
| Flag | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--all` | Show all results (passing, failed and skipped), not just failures |
| `--filter stringArray` | Filter by key=value; repeatable. Keys: result (success\|failure\|skipped, exact), name and classname (case-insensitive substring). Same key repeated is OR, different keys AND. Cannot combine result= with --all |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--limit int` | Maximum number of results to show (0 = no limit) |
| `--sort string` | Sort by name, classname, result or run_time |
**Arguments:**
`` is the UUID of the job whose test results to list. Job
UUIDs are shown in `circleci job get` and `circleci run get --json`.
**Aliases:**
`circleci testresult ls`
**Examples:**
- List failed tests for a job (the default):
`circleci testresult list 8e50c384-0083-43d0-bc8f-93f0db589d6b`
- Show every result: passing, failed and skipped:
`circleci testresult list --all`
- Show skipped tests instead:
`circleci testresult list --filter result=skipped`
- Failed tests in one suite, slowest last:
`circleci testresult list --filter classname=api --sort run_time`
- Count failed tests by aggregating the JSONL stream with jq:
`circleci testresult list --json --jq '[.,inputs] | length'`
### `circleci workflow `
Inspect, rerun and cancel workflows (job graphs)
Work with CircleCI workflows.
Workflows orchestrate jobs within a run. Use these commands to
inspect workflow status, rerun failed jobs, or cancel a running workflow.
Workflow IDs are shown in the output of 'circleci run get'.
#### `circleci workflow cancel [flags]`
Cancel a running workflow
Cancel a running CircleCI workflow.
Any in-progress jobs will be stopped. Jobs that have already
completed are not affected.
Workflow IDs are shown in the output of 'circleci run get'.
| Flag | Description |
| ------------- | ------------------------ |
| `-f, --force` | skip confirmation prompt |
**Arguments:**
`` is the UUID of the workflow to cancel. Workflow IDs are
shown in the output of `circleci run get`.
**Examples:**
- Cancel a running workflow (with confirmation):
`circleci workflow cancel 5034460f-c7c4-4c43-9457-de07e2029e7b`
- Cancel without confirmation:
`circleci workflow cancel 5034460f-c7c4-4c43-9457-de07e2029e7b --force`
- Find a running workflow ID from the latest run and cancel it:
`circleci run get --json --jq '.workflows[] | select(.status=="running") | .id' | xargs circleci workflow cancel --force`
#### `circleci workflow get [flags]`
Get workflow details
Display the status and jobs of a CircleCI workflow.
Workflow IDs are shown in the output of 'circleci run get'.
JSON fields: id, name, phase, outcome, current_outcome, run_id, created_at, ended_at, jobs[].id/name/phase/outcome/current_outcome/type
| Flag | Description |
| ------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
**Arguments:**
`` is the UUID of the workflow to look up. Workflow IDs are
shown in the output of `circleci run get`.
**Examples:**
- Get workflow details:
`circleci workflow get 5034460f-c7c4-4c43-9457-de07e2029e7b`
- Output as JSON:
`circleci workflow get 5034460f-c7c4-4c43-9457-de07e2029e7b --json`
- Get workflow ID from a run:
`circleci run get | grep -A1 "Workflows"`
#### `circleci workflow list [] [flags]`
List workflows for a run or recent runs
List workflows for a CircleCI run, or for recent runs in the project when
no run is given.
JSON fields (single run): id, name, phase, outcome, current_outcome.
Recent-runs mode adds run_id.
| Flag | Description |
| --------------------- | --------------------------------------------------------------------------------- |
| `-b, --branch string` | Filter by branch (recent-runs mode) |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--limit int` | Number of recent runs to show (recent-runs mode) (default 10) |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
**Arguments:**
`` is optional: a run UUID (as shown by `circleci run list --json`)
or a run number (as shown by `circleci run list`).
When omitted, workflows for recent runs in the current project are listed,
grouped by run.
**Aliases:**
`circleci workflow ls`
**Examples:**
- List workflows for recent runs in the current project:
`circleci workflow list`
- Filter to a specific branch:
`circleci workflow list --branch main`
- List workflows by run number:
`circleci workflow list 75`
- List workflows by run UUID:
`circleci workflow list 9e0c9d52-3b7e-4cd6-b5f7-bfc5e4a07e81`
- Output as JSON:
`circleci workflow list --json`
#### `circleci workflow open `
Open workflow in browser
**Arguments:**
`` is the UUID of the workflow to look up. Workflow IDs are
shown in the output of `circleci run get`.
**Examples:**
- Open workflow details:
`circleci workflow open 5034460f-c7c4-4c43-9457-de07e2029e7b`
#### `circleci workflow rerun [flags]`
Rerun a workflow
All jobs rerun from scratch unless --from-failed is given, which reruns
only the jobs that failed. Either way a new workflow is created, and its
ID is reported so you can follow the run.
JSON fields: workflow_id, rerun_from, from_failed
| Flag | Description |
| --------------- | ---------------------- |
| `--from-failed` | Rerun only failed jobs |
| `--json` | Output as JSON |
**Arguments:**
`` is the UUID of the workflow to rerun. Workflow IDs are
shown in the output of `circleci run get`.
**Examples:**
- Rerun all jobs in a workflow from scratch:
`circleci workflow rerun 5034460f-c7c4-4c43-9457-de07e2029e7b`
- Rerun only the failed jobs:
`circleci workflow rerun 5034460f-c7c4-4c43-9457-de07e2029e7b --from-failed`
- Find a workflow ID from the latest run:
`circleci run get --json --jq '.workflows[].id'`
- Rerun and capture the new workflow's ID:
`circleci workflow rerun --from-failed --json --jq .workflow_id`
## Management Commands
### `circleci certificate `
Manage iOS code signing certificates
Upload, list, and delete Apple .p12 code signing certificates stored in
your CircleCI organization's secure storage.
Certificates are referenced by ID from a signing config. Deleting a
certificate that is referenced by a signing config will invalidate that
signing config.
#### `circleci certificate delete [flags]`
Delete an iOS certificate
Remove an Apple certificate from your organization's secure storage.
This action is irreversible. The server rejects the delete with an
error if the certificate is referenced by any signing config; delete
those signing configs first.
| Flag | Description |
| ------------- | ------------------------ |
| `-f, --force` | skip confirmation prompt |
**Arguments:**
`` is the ID of the certificate to delete.
Find the certificate ID with `circleci certificate list`.
**Aliases:**
`circleci certificate rm`
**Examples:**
- Delete a certificate (with confirmation):
`circleci certificate delete `
- Delete without confirmation:
`circleci certificate delete --force`
#### `circleci certificate list [flags]`
List uploaded iOS certificates
List Apple .p12 certificates currently stored in your organization's
secure storage.
JSON fields: id, file_name, org_id, created_at
| Flag | Description |
| -------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--org string` | Organization slug (e.g. gh/myorg) or UUID; defaults to git remote |
**Aliases:**
`circleci certificate ls`
**Examples:**
- List certificates (org inferred from git remote):
`circleci certificate list`
- List for a specific org:
`circleci certificate list --org gh/acme`
- Output as JSON:
`circleci certificate list --json`
- Get cert IDs only:
`circleci certificate list --json --jq '.[].id'`
#### `circleci certificate upload [flags]`
Upload a .p12 certificate
Upload an Apple .p12 code signing certificate to your CircleCI
organization's secure storage.
The certificate file is read from disk and base64-encoded locally
before being sent. In a terminal, --password may be omitted and you
will be prompted with input masking.
Pass --password - to read the password from stdin, keeping it out of
shell history and process listings.
JSON fields: id, file_name
| Flag | Description |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `--cert-file string` | Path to the .p12 certificate file |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--org string` | Organization slug (e.g. gh/myorg) or UUID; defaults to git remote |
| `--password string` | Password for the .p12 file. Pass - to read from stdin. Prompted if omitted in a terminal. |
**Examples:**
- Upload a certificate (org inferred from git remote, password prompted):
`circleci certificate upload --cert-file ./Certificates.p12`
- Read the password from stdin (no shell history exposure):
`echo "$P12_PASSWORD" | circleci certificate upload --cert-file ./Certificates.p12 --password -`
- Explicit org and capture the new cert id for scripting:
`echo "$P12_PASSWORD" | circleci certificate upload --org gh/acme --cert-file ./Certificates.p12 --password - --json --jq -r '.id'`
### `circleci component-version `
Manage deploy component versions
List and inspect CircleCI deploy component versions.
Deploy component versions represent specific released versions
of a component across environments.
Also available as: circleci deploy version
#### `circleci component-version list [flags]`
List versions of a deploy component
List versions of a CircleCI deploy component.
Optionally filter by deploy environment with --environment.
JSON fields: name, component_id, created_at
| Flag | Description |
| ---------------------- | --------------------------------------------------------------------------------- |
| `--environment string` | Filter by deploy environment ID |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
**Arguments:**
`` is the UUID of the deploy component whose
versions you want to list. Component IDs are shown in the output of
`circleci deploy component list`.
**Aliases:**
`circleci component-version ls`
**Examples:**
- List versions of a component:
`circleci component-version list a0000000-0000-4000-8000-000000c00001`
- Filter by environment:
`circleci component-version list a0000000-0000-4000-8000-000000c00001 --environment a0000000-0000-4000-8000-000000e00001`
- Output as JSON:
`circleci component-version list a0000000-0000-4000-8000-000000c00001 --json`
### `circleci context `
Manage secret env vars shared across pipelines
Work with CircleCI contexts.
Contexts are named collections of secret environment variables that
can be shared across runs within an organization. Jobs can
reference a context to inject its variables into the build environment.
#### `circleci context create [flags]`
Create a new context
Create a new CircleCI context for an organization.
JSON fields: id, name, created_at
| Flag | Description |
| -------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--org string` | Organization slug (e.g. gh/myorg); defaults to git remote |
**Arguments:**
`` is the name for the new context, for example, `build-secrets`.
**Examples:**
- Create a context for the org inferred from git remote:
`circleci context create my-context`
- Create a context for a specific organization:
`circleci context create my-context --org gh/myorg`
- Create and capture the ID:
`circleci context create my-context --org gh/myorg --json --jq '.id'`
#### `circleci context delete [flags]`
Delete a context
Delete a CircleCI context by UUID or name.
Deleting a context removes all environment variables stored in it.
Jobs that reference this context will fail until they are updated.
| Flag | Description |
| -------------- | ----------------------------------------------------------------- |
| `-f, --force` | skip confirmation prompt |
| `--org string` | Organization slug (e.g. gh/myorg); used when resolving name to ID |
**Arguments:**
A context can be specified by name or ID:
- By name, for example, `context-name`
- By ID, for example, `849e7902-802f-4082-8a70-da77dcd084e3`
**Aliases:**
`circleci context rm`
**Examples:**
- Delete a context by UUID (with confirmation):
`circleci context delete ctx-uuid-here`
- Delete a context by name (org inferred from git remote):
`circleci context delete my-context`
- Delete a context by name in a specific org, without confirmation:
`circleci context delete my-context --org gh/myorg --force`
#### `circleci context get [flags]`
Get details of a context
Display details of a CircleCI context, including its environment
variable names and metadata.
Variable values are never returned by the API once set.
JSON fields: id, name, org_id, created_at, environment_variables, restrictions
| Flag | Description |
| -------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--org string` | Organization slug (e.g. gh/myorg); used when resolving name to ID |
**Arguments:**
A context can be specified by name or ID:
- By name, for example, `context-name`
- By ID, for example, `849e7902-802f-4082-8a70-da77dcd084e3`
**Examples:**
- Get a context by UUID:
`circleci context get ctx-uuid-here`
- Get a context by name (org inferred from git remote):
`circleci context get my-context`
- Get a context by name in a specific org:
`circleci context get my-context --org gh/myorg`
- Output as JSON:
`circleci context get my-context --json`
- Get just the org ID:
`circleci context get ctx-uuid-here --json --jq '.org_id'`
#### `circleci context list [flags]`
List contexts for an organization
List all contexts for a CircleCI organization.
JSON fields: id, name, created_at
| Flag | Description |
| --------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--name string` | Find contexts by name (partial match) |
| `--org string` | Organization slug (e.g. gh/myorg); defaults to git remote |
**Aliases:**
`circleci context ls`
**Examples:**
- List contexts for the org inferred from git remote:
`circleci context list`
- List contexts containing the given name:
`circleci context list --name substring`
- List contexts for a specific organization:
`circleci context list --org gh/myorg`
- Output as JSON for scripting:
`circleci context list --json`
- Get just context names:
`circleci context list --json --jq '.[].name'`
#### `circleci context open [flags]`
Open the contexts settings page in the browser
Open the CircleCI contexts settings page for an organization in your
default web browser.
The organization is inferred from the current git repository's remote
unless overridden with --org. Supports GitHub, Bitbucket, and GitLab
remotes.
| Flag | Description |
| -------------- | --------------------------------------------------------- |
| `--org string` | Organization slug (e.g. gh/myorg); defaults to git remote |
**Examples:**
- Open contexts for the org inferred from git remote:
`circleci context open`
- Open contexts for a specific organization:
`circleci context open --org gh/myorg`
- Open when your remote is on CircleCI server:
`circleci context open --host https://circleci.example.com`
#### `circleci context restriction `
Manage context restrictions
Add and remove restrictions that control which projects and groups
can use a CircleCI context.
Restrictions scope context access to specific projects, pipeline
expressions, or VCS groups. A context with no restrictions is
accessible to all members of the organization.
##### `circleci context restriction create [flags]`
Add a restriction to a context
Add a restriction to a CircleCI context.
JSON fields: id, name, restriction_type, restriction_value
| Flag | Description |
| ---------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--org string` | Organization slug (e.g. gh/myorg); used when resolving name to ID |
| `--type string` | Restriction type: project, expression, or group |
| `--value string` | Value of the restriction |
**Arguments:**
A context can be specified by name or ID:
- By name, for example, `context-name`
- By ID, for example, `849e7902-802f-4082-8a70-da77dcd084e3`
**Examples:**
- Restrict context to a specific project:
`circleci context restriction create ctx-uuid --type project --value proj-uuid`
- Restrict context to a specific group:
`circleci context restriction create ctx-uuid --type group --value group-uuid`
- Restrict context using a pipeline expression:
`circleci context restriction create ctx-uuid --type expression --value 'pipeline.git.branch == "main"'`
- Capture the restriction ID:
`circleci context restriction create ctx-uuid --type project --value proj-uuid --json --jq '.id'`
##### `circleci context restriction delete [flags]`
Delete a restriction from a context
Remove a restriction from a CircleCI context.
This action is irreversible. Once removed, the context will be
accessible to any project or group that was previously blocked.
| Flag | Description |
| ------------------------- | ----------------------------------------------------------------- |
| `-f, --force` | Skip confirmation prompt |
| `--org string` | Organization slug (e.g. gh/myorg); used when resolving name to ID |
| `--restriction-id string` | UUID of the restriction to delete |
**Arguments:**
A context can be specified by name or ID:
- By name, for example, `context-name`
- By ID, for example, `849e7902-802f-4082-8a70-da77dcd084e3`
**Aliases:**
`circleci context restriction rm`
**Examples:**
- Delete a restriction (with confirmation):
`circleci context restriction delete ctx-uuid --restriction-id r-uuid`
- Delete without confirmation:
`circleci context restriction delete ctx-uuid --restriction-id r-uuid --force`
#### `circleci context secret `
Manage context environment variables
List, set, and delete environment variables stored in a CircleCI context.
Context environment variables are injected into jobs that reference the
context. Variable values are never returned by the API after being set.
##### `circleci context secret delete [flags]`
Delete an environment variable from a context
Remove an environment variable from a CircleCI context.
This action is irreversible. Jobs that depend on this variable will
fail until a new value is set.
| Flag | Description |
| --------------- | ----------------------------------------------------------------- |
| `-f, --force` | skip confirmation prompt |
| `--name string` | Name of the environment variable to delete |
| `--org string` | Organization slug (e.g. gh/myorg); used when resolving name to ID |
**Arguments:**
A context can be specified by name or ID:
- By name, for example, `context-name`
- By ID, for example, `849e7902-802f-4082-8a70-da77dcd084e3`
**Aliases:**
`circleci context secret rm`
**Examples:**
- Delete a variable (with confirmation):
`circleci context secret delete ctx-uuid-here --name MY_SECRET`
- Delete without confirmation:
`circleci context secret delete ctx-uuid-here --name MY_SECRET --force`
##### `circleci context secret list [flags]`
List environment variables in a context
List the environment variable names stored in a CircleCI context.
Variable values are never returned by the API once set.
JSON fields: variable, truncated_value, context_id, created_at, updated_at
| Flag | Description |
| -------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--org string` | Organization slug (e.g. gh/myorg); used when resolving name to ID |
**Arguments:**
A context can be specified by name or ID:
- By name, for example, `context-name`
- By ID, for example, `849e7902-802f-4082-8a70-da77dcd084e3`
**Aliases:**
`circleci context secret ls`
**Examples:**
- List env vars in a context by UUID:
`circleci context secret list ctx-uuid-here`
- List env vars by context name (org inferred from git remote):
`circleci context secret list my-context`
- List env vars by context name in a specific org:
`circleci context secret list my-context --org gh/myorg`
- Get variable names only:
`circleci context secret list ctx-uuid-here --json --jq '.[].variable'`
##### `circleci context secret set [flags]`
Set an environment variable in a context
Add or update an environment variable in a CircleCI context.
An existing variable is overwritten. The value is never retrievable once
set, and in a terminal --value may be omitted to be prompted with masking.
| Flag | Description |
| ---------------- | --------------------------------------------------------------------- |
| `--name string` | Name of the environment variable |
| `--org string` | Organization slug (e.g. gh/myorg); used when resolving name to ID |
| `--value string` | Value of the environment variable (prompted if omitted in a terminal) |
**Arguments:**
A context can be specified by name or ID:
- By name, for example, `context-name`
- By ID, for example, `849e7902-802f-4082-8a70-da77dcd084e3`
**Examples:**
- Set an environment variable by context UUID (value prompted):
`circleci context secret set ctx-uuid-here --name MY_SECRET`
- Set an environment variable by context name:
`circleci context secret set my-context --org gh/myorg --name MY_SECRET --value s3cr3t`
- Read a value from a file:
`circleci context secret set ctx-uuid-here --name MY_SECRET --value "$(cat secret.txt)"`
- Read a value from stdin:
`circleci context secret set ctx-uuid-here --name MY_SECRET --value "$(cat)"`
### `circleci deploy `
Track released components and versions
Work with CircleCI Deploys.
View deployed components and their versions across environments.
#### `circleci deploy component `
Manage deploy components
List and inspect CircleCI deploy components.
Deploy components represent the deployable units of a project,
such as a service, application, or library.
##### `circleci deploy component get [flags]`
Get a deploy component
Get details about a CircleCI deploy component by ID.
JSON fields: id, name, project_id
| Flag | Description |
| ------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
**Examples:**
- Get a deploy component by ID:
`circleci deploy component get a0000000-0000-4000-8000-000000c00001`
- Output as JSON:
`circleci deploy component get a0000000-0000-4000-8000-000000c00001 --json`
- Filter JSON output with jq:
`circleci deploy component get a0000000-0000-4000-8000-000000c00001 --json --jq '.name'`
##### `circleci deploy component list [flags]`
List deploy components
List deploy components for a CircleCI project.
The project is inferred from the current git repository's remote
unless overridden with --project.
JSON fields: id, name, project_id
| Flag | Description |
| ------------------ | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
**Aliases:**
`circleci deploy component ls`
**Examples:**
- List components for the current git remote's project:
`circleci deploy component list`
- List components for a specific project:
`circleci deploy component list --project gh/myorg/myrepo`
- Output as JSON:
`circleci deploy component list --json`
#### `circleci deploy environment `
Manage deploy environments
List and inspect CircleCI deploy environments.
Deploy environments represent targets such as production or staging
where components are deployed.
##### `circleci deploy environment get [flags]`
Get a deploy environment
Get details about a CircleCI deploy environment by ID.
JSON fields: id, name, org_id
| Flag | Description |
| ------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
**Examples:**
- Get a deploy environment by ID:
`circleci deploy environment get a0000000-0000-4000-8000-000000e00001`
- Output as JSON:
`circleci deploy environment get a0000000-0000-4000-8000-000000e00001 --json`
- Filter JSON output with jq:
`circleci deploy environment get a0000000-0000-4000-8000-000000e00001 --json --jq '.name'`
##### `circleci deploy environment list [flags]`
List deploy environments
List deploy environments for a CircleCI organization.
The organization is inferred from the current git repository's remote
unless overridden with --org.
JSON fields: id, name, org_id
| Flag | Description |
| -------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--org string` | Organization slug (e.g. gh/myorg); defaults to git remote |
**Aliases:**
`circleci deploy environment ls`
**Examples:**
- List environments for the current git remote's org:
`circleci deploy environment list`
- List environments for a specific org:
`circleci deploy environment list --org gh/myorg`
- Output as JSON:
`circleci deploy environment list --json`
#### `circleci deploy init [flags]`
Instrument your config for deploy tracking
Set up deploy markers in .circleci/config.yml.
Scans the config for deploy-like jobs (names containing deploy,
release, publish, or ship), prompts for your service name and
target environment, then adds a log step to each deploy job.
The command is idempotent: running it twice on the same config
makes no duplicate changes.
Works offline — no API calls required.
| Flag | Description |
| -------------------------- | -------------------------------------------------------------------------- |
| `--component string` | Service/component name (skips prompt) |
| `--environment string` | Default environment for jobs whose target can't be inferred (skips prompt) |
| `--pipeline-config string` | Path to CircleCI pipeline config file (default ".circleci/config.yml") |
**Examples:**
- Interactive setup in the current repo:
`circleci deploy init`
- Skip the service-name prompt:
`circleci deploy init --component api`
- Fully non-interactive (supply both answers as flags):
`circleci deploy init --component api --environment production`
- Use a non-default config location:
`circleci deploy init --pipeline-config path/to/config.yml`
#### `circleci deploy list [flags]`
List recent deploys
List deploys for a CircleCI project.
The project is inferred from the current git repository's remote
unless overridden with --project. Each deploy shows the component,
version, status, type, and when it was created.
JSON fields: id, component_name, version, type, status, is_rollback, pipeline_id, workflow_id, created_at, ended_at
| Flag | Description |
| ------------------ | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
**Aliases:**
`circleci deploy ls`
**Examples:**
- List the 10 most recent deploys (auto-detect project from git remote):
`circleci deploy list`
- List for a specific project:
`circleci deploy list --project gh/myorg/myrepo`
- Output as JSON for scripting:
`circleci deploy list --json`
#### `circleci deploy open [flags]`
Open the deploys page in the browser
Open the CircleCI deploys page for the current project in your
default web browser.
The project is inferred from the current git repository's remote
unless overridden with --project. Supports GitHub, Bitbucket, and
GitLab remotes.
| Flag | Description |
| ------------------ | ------------------------------------------------------- |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
**Examples:**
- Open the deploys page for the current project:
`circleci deploy open`
- Open the deploys page for a specific project:
`circleci deploy open --project gh/myorg/myrepo`
#### `circleci deploy rollback [flags]`
Roll back a deployed component to an earlier version
Roll back a deployed component to an earlier version. --from must name
the version currently deployed; omit it to use the latest deployed one.
JSON fields: id, rollback_type, project_id, component_id, environment_id
| Flag | Description |
| ----------------------- | --------------------------------------------------------------------------------- |
| `--checkout-ref string` | Git ref the rollback pipeline checks out |
| `--component string` | Deploy component name or ID (required) |
| `--config-ref string` | Git ref the rollback pipeline's config is read from |
| `--environment string` | Deploy environment name or ID (required) |
| `-f, --force` | skip confirmation prompt |
| `--from string` | Version being replaced; defaults to the latest deployed |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--namespace string` | Namespace scoping the component (default "default") |
| `--param stringArray` | Rollback pipeline parameter as key=value (repeatable) |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
| `--reason string` | Why the rollback was requested; recorded in the audit log |
**Examples:**
- Roll production back to 1.2.0 (with confirmation):
`circleci deploy rollback 1.2.0 --component web-frontend --environment production`
- Assert the version being replaced, and skip the prompt:
`circleci deploy rollback 1.2.0 --component web-frontend --environment production --from 1.3.0 --force`
- Roll back with a reason and a rollback-pipeline parameter:
`circleci deploy rollback 1.2.0 --component web-frontend --environment production --reason "bad release" --param notify=true`
#### `circleci deploy settings [flags]`
Get deploy settings for a project
Get deploy settings for a CircleCI project.
The project is inferred from the current git repository's remote
unless overridden with --project.
JSON fields: id, project_id
| Flag | Description |
| ------------------ | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
**Examples:**
- Get deploy settings for the current git remote's project:
`circleci deploy settings`
- Get settings for a specific project:
`circleci deploy settings --project gh/myorg/myrepo`
- Output as JSON:
`circleci deploy settings --json`
#### `circleci deploy version `
Manage deploy component versions
List and inspect CircleCI deploy component versions.
Deploy component versions represent specific released versions
of a component across environments.
##### `circleci deploy version list [flags]`
List versions of a deploy component
List versions of a CircleCI deploy component.
Optionally filter by deploy environment with --environment.
JSON fields: name, component_id, created_at
Primary alias: circleci component-version list
| Flag | Description |
| ---------------------- | --------------------------------------------------------------------------------- |
| `--environment string` | Filter by deploy environment ID |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
**Aliases:**
`circleci deploy version ls`
**Examples:**
- List versions of a component:
`circleci deploy version list a0000000-0000-4000-8000-000000c00001`
- Filter by environment:
`circleci deploy version list a0000000-0000-4000-8000-000000c00001 --environment a0000000-0000-4000-8000-000000e00001`
- Output as JSON:
`circleci deploy version list a0000000-0000-4000-8000-000000c00001 --json`
### `circleci dlc `
Purge a project's Docker layer cache (DLC)
Manage docker layer caching (DLC) for projects.
Docker layer caching allows CircleCI to cache individual Docker image
layers between pipeline runs. Use 'circleci dlc purge' to invalidate
the cache for a project and force a fresh image build on the next run.
These commands are also available under 'circleci project dlc'.
**Examples:**
- Purge DLC for the current git repository's project:
`circleci dlc purge`
- Purge DLC for a specific project:
`circleci dlc purge --project gh/myorg/myrepo`
- Purge DLC and output result as JSON:
`circleci dlc purge --project gh/myorg/myrepo --json`
#### `circleci dlc purge [flags]`
Purge the Docker Layer Cache for a project
Purge the docker layer cache (DLC) for a project.
Docker layer caching stores individual Docker image layers between
pipeline runs to speed up builds. Purging the cache forces CircleCI
to rebuild all layers from scratch on the next run, which is useful
when a cached layer contains stale or corrupt data.
JSON fields (--json): project_id, project_slug
| Flag | Description |
| ------------------ | ------------------------------------------------------- |
| `-f, --force` | Skip confirmation prompt |
| `--json` | Output as JSON |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
**Examples:**
- Purge DLC for the current git repository's project:
`circleci dlc purge`
- Purge DLC for a specific project:
`circleci dlc purge --project gh/myorg/myrepo`
- Skip the confirmation prompt (for scripting):
`circleci dlc purge --project gh/myorg/myrepo --force`
- Purge DLC and output result as JSON:
`circleci dlc purge --project gh/myorg/myrepo --force --json`
- Purge DLC for a Bitbucket project:
`circleci dlc purge --project bb/myorg/myrepo`
### `circleci envvar `
List, set and delete a project's environment variables
List, set, and delete environment variables for a CircleCI project.
Environment variable values are masked in list output (shown as "xxxx").
The full value is never retrievable after it has been set.
Also available as: circleci project envvar ``
**Examples:**
- List all environment variables for the current project:
`circleci envvar list`
- Set an environment variable:
`circleci envvar set MY_SECRET s3cr3t --project gh/myorg/myrepo`
- Delete an environment variable:
`circleci envvar delete MY_SECRET`
#### `circleci envvar delete [flags]`
Delete a project environment variable
Delete an environment variable from a CircleCI project.
This action is irreversible. The variable will be removed and any
jobs that reference it will fail until a new value is set.
| Flag | Description |
| ------------------ | ------------------------------------------------------- |
| `-f, --force` | skip confirmation prompt |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
**Arguments:**
`` is the name of the environment variable to delete from
the project. This action is irreversible.
**Aliases:**
`circleci envvar rm`
**Examples:**
- Delete an env var from the current project (with confirmation):
`circleci envvar delete MY_SECRET`
- Delete without confirmation:
`circleci envvar delete MY_SECRET --force`
- Delete an env var from a specific project:
`circleci envvar delete MY_SECRET --project gh/myorg/myrepo --force`
#### `circleci envvar list [flags]`
List project environment variables
List the environment variables defined for a CircleCI project.
Values are always masked in the response (shown as "xxxx") — CircleCI
does not expose secret values after they are set.
JSON fields: name, value
| Flag | Description |
| ------------------ | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
**Aliases:**
`circleci envvar ls`
**Examples:**
- List env vars for the current project:
`circleci envvar list`
- List env vars for a specific project:
`circleci envvar list --project gh/myorg/myrepo`
- Output as JSON:
`circleci envvar list --json`
#### `circleci envvar set [flags]`
Set a project environment variable
Create or update an environment variable for a CircleCI project.
If the variable already exists it will be overwritten. The value
is never retrievable after being set — CircleCI masks it in all
subsequent list responses.
| Flag | Description |
| ------------------ | ------------------------------------------------------- |
| `--project string` | Project slug (e.g. gh/org/repo); defaults to git remote |
**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.
**Examples:**
- Set an env var for the current project:
`circleci envvar set MY_SECRET s3cr3t`
- Set an env var for a specific project:
`circleci envvar set MY_SECRET s3cr3t --project gh/myorg/myrepo`
- Read a value from a file:
`circleci envvar set MY_SECRET "$(cat secret.txt)"`
### `circleci namespace `
Manage the org namespace orbs publish under
Work with CircleCI orb namespaces.
Namespaces are unique identifiers used to publish orbs.
Each organization may claim one namespace. Orbs are published
and referenced as `/`. All published orbs are world-readable.
#### `circleci namespace create --org [flags]`
Create a namespace
Create a CircleCI orb namespace for an organization.
Each organization may claim one namespace. Namespace names must
be globally unique across CircleCI. All orbs published in a
namespace are world-readable.
JSON fields: id, name
| Flag | Description |
| -------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--org string` | Organization slug (e.g. gh/myorg) or UUID to claim the namespace for (required) |
**Arguments:**
`` is the namespace name to create. It must be globally unique
across CircleCI, for example, `myorg`.
**Examples:**
- Create a namespace for an organization:
`circleci namespace create myorg --org gh/acme`
- Create a namespace and output JSON:
`circleci namespace create myorg --org gh/acme --json`
- Capture just the namespace ID:
`circleci namespace create myorg --org gh/acme --json --jq '.id'`
#### `circleci namespace delete [flags]`
Delete a namespace and all its orbs
Delete a CircleCI orb namespace and all orbs published under it.
This operation is irreversible. Any pipelines referencing orbs in
this namespace will fail after deletion.
| Flag | Description |
| --------------- | -------------------------------------------- |
| `-n, --dry-run` | print what would be deleted without deleting |
| `-f, --force` | skip confirmation prompt |
**Arguments:**
`` is the name of the namespace to delete, for example, "myorg".
**Aliases:**
`circleci namespace rm`
**Examples:**
- Delete a namespace (with confirmation prompt):
`circleci namespace delete myorg`
- Preview what would be deleted without deleting:
`circleci namespace delete myorg --dry-run`
- Delete without a confirmation prompt:
`circleci namespace delete myorg --force`
- Delete in a CI environment (non-interactive; --force required):
`circleci namespace delete myorg -f`
#### `circleci namespace get [flags]`
Get details of a namespace
Display details of a CircleCI orb namespace.
JSON fields: id, name
| Flag | Description |
| ------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
**Arguments:**
`` is the name of the namespace to look up, for example, `myorg`.
**Examples:**
- Get a namespace by name:
`circleci namespace get myorg`
- Output as JSON:
`circleci namespace get myorg --json`
- Extract just the namespace ID:
`circleci namespace get myorg --json --jq '.id'`
#### `circleci namespace rename [flags]`
Rename a namespace
Rename a CircleCI orb namespace.
Any orbs already published under the old name will continue to be
accessible — renaming creates an alias. Ensure that any configs
and orbs still referencing the old name are updated.
JSON fields: id, name
| Flag | Description |
| ------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
**Arguments:**
- `` is the current name of the namespace, for example, `oldname`.
- `` is the new name to assign, for example, `newname`.
**Examples:**
- Rename a namespace:
`circleci namespace rename oldname newname`
- Rename and output the result as JSON:
`circleci namespace rename oldname newname --json`
- Confirm the new ID after rename:
`circleci namespace rename oldname newname --json --jq '.id'`
### `circleci orb `
Create, publish and inspect orbs (reusable config)
Manage orbs in the orb registry.
Orbs are reusable packages of CircleCI configuration, published to a
namespace and either shared publicly or kept private. Manage the namespace
itself with 'circleci namespace'.
#### `circleci orb add-to-category /`
Add an orb to a registry category
Add an orb to an orb registry category.
Categories help users discover orbs. Use 'circleci orb list-categories'
to see available categories.
**Arguments:**
- `/` is the orb to add, for example, `namespace/orb-name`.
- `` is the registry category name, for example, `Testing`.
**Examples:**
- Add an orb to the Testing category:
`circleci orb add-to-category myorg/my-orb "Testing"`
- Add an orb to the Deployment category:
`circleci orb add-to-category myorg/my-orb "Deployment"`
- List available categories first:
`circleci orb list-categories`
#### `circleci orb create / [flags]`
Reserve an orb name in a namespace
Reserve an orb name in the given namespace.
This registers the name without publishing any versions; publish them with
'circleci orb publish'. The namespace must already exist.
JSON fields: id, name, namespace, is_private
| Flag | Description |
| ------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--private` | create as a private orb |
**Arguments:**
- `/` is the orb name to reserve, for example, `namespace/orb-name`.
The namespace must already exist.
**Examples:**
- Create a public orb:
`circleci orb create myorg/my-orb`
- Create a private orb:
`circleci orb create myorg/my-orb --private`
- Create and output as JSON:
`circleci orb create myorg/my-orb --json`
#### `circleci orb diff / --from --to [flags]`
Show a unified diff between two orb versions
Show a unified diff between two versions of an orb.
The --from and --to versions can be semver (e.g. 1.0.0) or dev labels
(e.g. dev:my-branch).
Exit code is 0 regardless of whether the versions differ.
| Flag | Description |
| --------------- | ------------------------------------------------------------------------ |
| `--from string` | the first version (semver e.g. 1.0.0, or a dev label e.g. dev:my-branch) |
| `--to string` | the second version, in the same form as --from |
**Arguments:**
- `/` is the orb to diff, for example, `namespace/orb-name`.
**Examples:**
- Diff two semver versions:
`circleci orb diff myorg/my-orb --from 1.0.0 --to 1.1.0`
- Diff a semver and a dev version:
`circleci orb diff myorg/my-orb --from 1.0.0 --to dev:my-branch`
- Diff two dev versions:
`circleci orb diff myorg/my-orb --from dev:branch-a --to dev:branch-b`
#### `circleci orb get /[@]/ [flags]`
Get orb metadata and statistics
Get metadata and statistics for an orb.
Displays the orb name, namespace, privacy status, latest version,
usage statistics for the past 30 days, associated categories, and
all published versions.
JSON fields: id, name, namespace, is_private, is_listed, created_at, latest_version, categories, versions, stats
| Flag | Description |
| ------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
**Arguments:**
An orb can be specified by name or ID:
- By name, for example, `namespace/orb-name`, optionally with a version, for example, `namespace/orb-name@1.2.3`
- By ID, the orb ID (UUID), for example, `849e7902-802f-4082-8a70-da77dcd084e3`
**Examples:**
- Get info for an orb:
`circleci orb get myorg/my-orb`
- Get info for a specific version:
`circleci orb get myorg/my-orb@1.2.3`
- Output as JSON:
`circleci orb get myorg/my-orb --json`
#### `circleci orb init [flags]`
Initialize a new orb project
Scaffold a new orb project from CircleCI-Public/Orb-Template into .
It then walks you through setup: reserving the namespace and orb, assigning
categories, creating an 'orb-publishing' context, initializing git, enabling
dynamic config, and publishing a dev:alpha version.
Note: once published, orbs cannot be deleted.
| Flag | Description |
| ----------------- | ----------------------------------------------------------------------------------------- |
| `--branch string` | primary git branch to track (default "main") |
| `--org string` | Organization slug (e.g. gh/myorg) or UUID to own the orb namespace and publishing context |
| `--private` | initialize a private orb |
| `--remote string` | remote git repository URL (required for git setup when non-interactive) |
| `--skip-git` | skip local git repository setup |
| `--template-only` | download the template only; skip all setup |
**Arguments:**
- `` is the directory to scaffold the orb project into. It is
created if it does not exist.
**Examples:**
- Interactive setup:
`circleci orb init ./my-orb`
- Just download the template, no setup:
`circleci orb init ./my-orb --template-only`
- Non-interactive: create a private orb under an org, skip git:
`circleci orb init ./my-orb --private --org gh/acme --skip-git`
#### `circleci orb list [] [flags]`
List orbs in the registry
List orbs in the CircleCI orb registry.
Without a namespace argument, lists certified orbs globally.
Pass a namespace to list all orbs in that namespace.
Use --uncertified to include orbs that are not certified by CircleCI.
Use --private to list only private orbs (requires namespace).
JSON fields: id, name, is_private, is_listed, latest_version
| Flag | Description |
| --------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
| `--private` | only list private orbs (requires namespace) |
| `--uncertified` | include uncertified orbs |
**Arguments:**
- `` is optional. When given, lists all orbs in that namespace.
When omitted, lists certified orbs globally.
**Aliases:**
`circleci orb ls`
**Examples:**
- List certified orbs globally:
`circleci orb list`
- List all orbs in a namespace:
`circleci orb list myorg`
- Include uncertified orbs:
`circleci orb list --uncertified`
- List orbs as JSON:
`circleci orb list --json`
- List private orbs in a namespace:
`circleci orb list myorg --private`
#### `circleci orb list-categories [flags]`
List orb registry categories
List all categories available in the CircleCI orb registry.
Categories are used to organize and discover orbs. Use
'circleci orb add-to-category' to categorize your orbs.
JSON fields: id, name
| Flag | Description |
| ------------- | --------------------------------------------------------------------------------- |
| `--jq string` | Process values from the response using jq syntax (see `circleci help formatting`) |
| `--json` | Output as JSON |
**Examples:**
- List all orb categories:
`circleci orb list-categories`
- Output as JSON:
`circleci orb list-categories --json`
- Capture category names only:
`circleci orb list-categories --json --jq '.[].name'`
#### `circleci orb pack `
Pack a multi-file orb directory into a single YAML
Pack an orb source directory into a single YAML file.
If the path is a directory, the '@orb.yml' (or 'orb.yml') file at the
root is merged with any 'commands/', 'jobs/', 'executors/', and 'examples/'
subdirectories. Each .yml file in those directories is added as a named
entry under the corresponding top-level key.
If the path is a single file it is parsed and written to stdout.
Any '<< include(path) >>' directive, alone or embedded in a larger
value, is replaced with that file's contents, relative to the orb root.
The merged YAML is written to stdout.
**Arguments:**
- `` is the path to an orb source directory or a single orb YAML file.
**Examples:**
- Pack a single orb file:
`circleci orb pack orb.yml`
- Pack a multi-file orb directory:
`circleci orb pack ./src`
- Pack and save to a file:
`circleci orb pack ./src > orb.yml`
- Pack and immediately validate:
`circleci orb pack ./src | circleci orb validate -`
#### `circleci orb process [flags]`
Validate and print expanded orb YAML
Validate an orb YAML file and print the expanded (processed) YAML.
The processed output resolves all orb references and expands inline
configurations. Useful to verify what CircleCI will see when the orb
is published.
Pass '-' as the path to read from stdin.
| Flag | Description |
| -------------- | ---------------------------------------------------------------------- |
| `--org string` | Organization slug (e.g. gh/myorg) or UUID for private orb dependencies |
**Arguments:**
- `` is the path to an orb YAML file. Pass `-` to read from stdin.
**Examples:**
- Process an orb file and print expanded YAML:
`circleci orb process orb.yml`
- Process from stdin:
`cat orb.yml | circleci orb process -`
- Process with a specific org for private deps:
`circleci orb process orb.yml --org gh/acme`
#### `circleci orb publish `
Publish orb versions
Publish orb versions to the CircleCI orb registry.
To publish a specific version:
circleci orb publish `/@`
To promote a dev version to a stable semver:
circleci orb publish promote `/@dev: