CIRCLECI(1)
💅 CIRCLECI(1) — The CircleCI CLI 🎀
okay bestie, welcome to the manual page for circleci — literally The CircleCI CLI 👑. we're keeping every flag, every example, every file path. no cap.
🌸 NAME 🌸
circleci — The CircleCI CLI 💖
🌈 SYNOPSIS 🌈
circleci [options...] [argument...]✨ DESCRIPTION ✨
Work with CircleCI from the command line. that's the whole vibe, and it's honestly iconic 🦋
💅 OPTIONS 💅
these are the top-level options, bestie — the main-character flags ✨
-c,--config— Path to config file (default:~/.config/circleci/config.yml)--debug— turn on debug logging 🔍--insecure-storage— do not use the system's secure storage for storing tokens 🙈--no-color— Disable ANSI color output (same as settingNO_COLOR) 🎨-q,--quiet— Suppress informational output. Data on stdout is unaffected 🤫--skip-update-check— skip checking for CLI and extension updates ⏭️--theme— Set the color theme (default:auto) 🌈
🚀 COMMANDS 🚀
💖 api <path> 💖
Call the CircleCI REST API directly — yes, you can just hit the API from here, slay 💅
🧸 OPTIONS 🧸
-d,--data— Raw request body sent verbatim;@filereads from a file,@-from stdin-f,--field— Add a field:key=value(query param for GET/DELETE, JSON body for POST/PUT/PATCH)-H,--header— Add a request header:"Key: Value"--jq— Process values from the response using jq syntax-X,--method— HTTP method (default: GET, or POST when-for-dis used)
🎀 EXAMPLES 🎀
# Get your user profile
$ circleci api me
# List runs for a project
$ circleci api projects/{project-id}/runs
# Trigger a pipeline on a branch
$ circleci api projects/{project-id}/run -f definition_id=<id> -f "config[branch]=main"
# Send a body read from a file (@- reads from stdin)
$ circleci api projects/{project-id}/run -d @payload.json
# Send a custom header
$ circleci api 'runs?filter[user_id]=me' -H "X-Custom: value"🦋 artifact <job-id> 🦋
List and download a job's artifact files — come get your files, bestie 🍓
🧸 OPTIONS 🧸
--jq— Process values from the response using jq syntax--json— Output as JSON-o,--output— Download artifacts into this directory
🎀 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🌟 auth <command> 🌟
Log in, sign up and check your CircleCI identity — it's giving account-management main character energy 👑
💌 COMMANDS 💌
id — Show the device ID for this CLI installation
OPTIONS
--json— Output as JSON
EXAMPLES
# Print the device ID
$ circleci auth id
# Output as JSON
$ circleci auth id --json
# Use in a script
$ DEVICE=$(circleci auth id)login — Log in to a CircleCI account
OPTIONS
--no-browser— Print the authorize URL instead of opening a browser
EXAMPLES
# Open the browser and authorize the CLI
$ circleci auth login
# Print the authorize URL instead of opening a browser
$ circleci auth login --no-browser
# Authenticate against a non-default host
$ CIRCLE_HOST=https://example.circleci.com circleci auth loginlogout — Log out of a CircleCI account
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON
EXAMPLES
# Log out of the current account
$ circleci auth logout
# Log out, then sign in as a different account
$ circleci auth logout && circleci auth login
# Log out without printing the confirmation line
$ circleci auth logout --quiet
# Report where the token was removed from, for scripting
$ circleci auth logout --json --jq '.storage'me — Display active account information
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON
signup — Sign-up for a new CircleCI account
OPTIONS
--no-browser— Print the authorize URL instead of opening a browser
EXAMPLES
# Open the signup page in your browser
$ circleci auth signup
# Print the authorize URL instead of opening a browser
$ circleci auth signup --no-browser
# Authenticate against a non-default host
$ CIRCLE_HOST=https://example.circleci.com circleci auth signup🧚 certificate <command> 🧚
Manage iOS code signing certificates — iconic iOS signing business 🎀
💌 COMMANDS 💌
delete <cert-id> — Delete an iOS certificate
OPTIONS
-f,--force— skip confirmation prompt
EXAMPLES
# Delete a certificate (with confirmation)
$ circleci certificate delete <cert-id>
# Delete without confirmation
$ circleci certificate delete <cert-id> --forcelist — List uploaded iOS certificates
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON--org— Organization slug (e.g.gh/myorg) or UUID; defaults to git remote
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'upload — Upload a .p12 certificate
OPTIONS
--cert-file— Path to the.p12certificate file--jq— Process values from the response using jq syntax--json— Output as JSON--org— Organization slug (e.g.gh/myorg) or UUID; defaults to git remote--password— Password for the.p12file. 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'🐚 completion <command> 🐚
Install, remove or print shell completions — tab-completion bestie behavior, honestly essential 🫶
💌 COMMANDS 💌
install — Install shell completion into your shell profile
EXAMPLES
# Install completion (detects shell from $SHELL)
$ circleci completion install
# Then reload your shell
$ source ~/.zshrc
# To install manually instead, source the output directly
$ source <(circleci completion bash)uninstall — Remove shell completion from your shell profile
EXAMPLES
# Remove completion
$ circleci completion uninstall
# Then reload your shell
$ source ~/.zshrc
# Check whether completion is currently installed
$ grep -l "circleci shell completion" ~/.zshrc ~/.bashrc 2>/dev/null⭐ component-version <command> ⭐
Manage deploy component versions — version management, but make it cute 💜
💌 COMMANDS 💌
list <component-id> — List versions of a deploy component
OPTIONS
--environment— Filter by deploy environment ID--jq— Process values from the response using jq syntax--json— Output as JSON
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🌈 config <command> 🌈
Generate, validate, process and pack config YAML — config YAML is the moment, periodt ✨
💌 COMMANDS 💌
generate [path] — Generate .circleci/config.yml from a repository scan
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.ymlpack <path> — Bundle split config files into a single YAML 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/ciprocess <path> — Compile and expand a pipeline config file
OPTIONS
-n,--next— Enable config next which previews upcoming potentially breaking config changes--org— Organization slug (e.g.gh/myorg) or UUID for private orb resolution; defaults to git remote--pipeline-parameters— Pipeline parameters as a YAML map or path to a YAML file
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 -validate [<path>] — Validate a pipeline config file
OPTIONS
-c,--config— Path to config file (use"-"for stdin)--json— Output as JSON-n,--next— Enable config next which previews upcoming potentially breaking config changes--org— Organization slug (e.g.gh/myorg) or UUID for private orb resolution; defaults to git remote
✨ EXAMPLES ✨
Ok so these are the config validate examples, and honestly they're giving "quick sanity check before you push" energy 💅 Run these before your pipeline yells at you, bestie.
# 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🎀 context <command> 🎀
Manage secret env vars shared across pipelines — like, the group chat of secrets, but for your whole org 🔐✨
COMMANDS 👇
🍓 create <name> 🍓
Create a new context — brand new little vault, freshly spawned 🫶
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON--org— Organization slug (e.g.gh/myorg) or UUID; defaults to git remote
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'🦋 delete <context-id|context-name> 🦋
Delete a context — yeah this one's a goodbye forever situation, so read the confirmation prompt fr fr 😭
OPTIONS
-f,--force— skip confirmation prompt--org— Organization slug (e.g.gh/myorg) or UUID; used when resolving name to ID
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🌸 get <context-id|context-name> 🌸
Get details of a context — the little info dump, no cap 🧚
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON--org— Organization slug (e.g.gh/myorg) or UUID; used when resolving name to ID
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'💜 list 💜
List contexts for an organization — the full roster, main character lineup energy 👑
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON--name— Find contexts by name (partial match)--org— Organization slug (e.g.gh/myorg) or UUID; defaults to git remote
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'🌈 open 🌈
Open the contexts settings page in the browser — yes, it will literally pop a browser window, slay 🖥️✨
OPTIONS
--org— 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🧚 restriction <command> 🧚
Manage context restrictions — aka who's allowed in the secret vault 🔒
COMMANDS 👇
create <context-id|context-name> — Add a restriction to a context
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON--org— Organization slug (e.g.gh/myorg) or UUID; used when resolving name to ID--type— Restriction type:project,expression, orgroup--value— Project ID, pipeline expression, or group ID, matching--type
EXAMPLES
# Restrict context to a specific project
$ circleci context restriction create ctx-uuid --type project --value proj-uuid
# Restrict context using a pipeline expression
$ circleci context restriction create ctx-uuid --type expression --value 'pipeline.git.branch == "main"'
# Restrict context to a security group (--value is the group ID)
$ circleci context restriction create ctx-uuid --type group --value group-uuid
# Capture the restriction ID
$ circleci context restriction create ctx-uuid --type project --value proj-uuid --json --jq '.id'delete <context-id|context-name> — Delete a restriction from a context
OPTIONS
-f,--force— Skip confirmation prompt--org— Organization slug (e.g.gh/myorg) or UUID; used when resolving name to ID--restriction-id— UUID of the restriction to delete
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🎀 secret <command> 🎀
Manage context environment variables — the actual passwords and tokens, handle with care bestie 🙈
COMMANDS 👇
delete <context-id|context-name> — Delete an environment variable from a context
OPTIONS
-f,--force— skip confirmation prompt--name— Name of the environment variable to delete--org— Organization slug (e.g.gh/myorg) or UUID; used when resolving name to ID
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 --forcelist <context-id|context-name> — List environment variables in a context
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON--org— Organization slug (e.g.gh/myorg) or UUID; used when resolving name to ID
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'set <context-id|context-name> — Set an environment variable in a context
OPTIONS
--name— Name of the environment variable--org— Organization slug (e.g.gh/myorg) or UUID; used when resolving name to ID--value— Value of the environment variable (prompted if omitted in a terminal)
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)"Ok but fr, piping secrets around with "$(cat)" is iconic — just don't echo them into your shell history, bestie 😭
🔥 deploy <command> 🔥
Track released components and versions — your deployment lore, archived 📚✨
COMMANDS 👇
🫶 component <command> 🫶
Manage deploy components
COMMANDS 👇
get <component-id> — Get a deploy component
OPTIONS
--jq— Process values from the response using jq syntax--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'list — List deploy components
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON--project— Project slug (e.g.gh/org/repo); defaults to git remote
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💜 environment <command> 💜
Manage deploy environments
COMMANDS 👇
get <environment-id> — Get a deploy environment
OPTIONS
--jq— Process values from the response using jq syntax--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'✨ list ✨
Okay so this one just lists out your deploy environments. That's it. That's the whole vibe. 💅
🌸 OPTIONS 🌸
--jq— run whatever's in the response through jq syntax so you can pluck out exactly the little value you came for ✨--json— gimme the output as JSON, bestie. machine-readable and all that 🫶--org— organization slug (likegh/myorg); defaults to the git remote. so if you don't say anything, it just sniffs out your remote and goes with it 😌
🎀 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🧚 init 🧚
Instrument your config for deploy tracking — like, it goes into your config and sprinkles the deploy-tracking magic in there ✨ lowkey the most main-character setup step ngl
💜 OPTIONS 💜
--component— service/component name</c> — and yeah, passing it skips the prompt so you don't gotta sit there answering questions 💅--environment— the default environment for jobs whose target can't be inferred — also skips the prompt 🙈--pipeline-config— path to your CircleCI pipeline config file 🦋
⭐ 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🌈 list 🌈
The deploy highlights reel 💖 — this lists your recent deploys so you can see what's been going out lately 👑
🍓 OPTIONS 🍓
--jq— process values from the response using jq syntax ✨--json— output as JSON, for all your scripting girlies 🫶--limit— max number of deploys to return, and yes0= all of them 😭 (careful, bestie)--org-wide— list deploys across all projects in the org — zoom out energy 🔥--project— project slug (likegh/org/repo); defaults to git remote 😌
🎀 EXAMPLES 🎀
# List the 10 most recent deploys (auto-detect project from git remote)
$ circleci deploy list# List 50 most recent deploys across the entire org
$ circleci deploy list --org-wide --limit 50# List org-wide deploys for a specific org (via any project in it)
$ circleci deploy list --org-wide --project gh/myorg/myrepo# Output as JSON for scripting
$ circleci deploy list --json👑 open 👑
Just opens the deploys page in your browser. Iconic, effortless, zero notes. 💅✨
🦋 OPTIONS 🦋
--project— 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🔥 rollback <target-version> 🔥
Roll back a deployed component to an earlier version. Big-deal energy, bestie — this is the "undo the oops" button 🙈 Use it with intention 💀
🌸 OPTIONS 🌸
--checkout-ref— the git ref that the rollback pipeline checks out 🧚--component— deploy component name or ID — required, no skipping 💅--config-ref— the git ref the rollback pipeline's config is read from 🦋--environment— deploy environment name or ID — required too 👑-f,--force— skip the confirmation prompt — for the brave or the scripted 😭--from— the version being replaced; defaults to the latest deployed ⭐--jq— process values from the response using jq syntax ✨--json— output as JSON 🫶--namespace— namespace scoping the component (default"default") 🌈--param— rollback pipeline parameter as key=value — and it's repeatable, so stack 'em if you got 'em 💅--project— project slug (e.g.gh/org/repo); defaults to git remote 😌--reason— why the rollback was requested; it gets recorded in the audit log 📝 so, like, be honest bestie
💜 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🎀 settings 🎀
Get the deploy settings for a project — a little peek behind the curtain 🧚♀️
⭐ OPTIONS ⭐
--jq— process values from the response using jq syntax ✨--json— output as JSON 🫶--project— 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🦋 version <command> 🦋
Manage deploy component versions — the whole version-history situation, handled 💅
📦 COMMANDS 📦
🍓 list <component-id> 🍓
List the versions of a deploy component ✨
💖 OPTIONS 💖
--environment— filter by deploy environment ID 🧚--jq— process values from the response using jq syntax 🫶--json— output as JSON ⭐
👑 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💀 dlc <command> 💀
Purge a project's Docker layer cache (DLC) — yes, the Docker Layer Cache. yes, purging it. yes, it's as dramatic as it sounds 🔥
📦 COMMANDS 📦
🧚 purge 🧚
Purge the Docker Layer Cache for a project 💅
🌸 OPTIONS 🌸
-f,--force— skip the confirmation prompt 🙈--json— output as JSON 🫶--project— 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🎀 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🌱 env <command> 🌱
Work with environment variables — the little key-value besties that run everything 🫶
📦 COMMANDS 📦
✨ subst [string] ✨
Substitute environment variables in a string — it's giving "find and replace but make it ✨env vars✨" 💅
🌈 EXAMPLES 🌈
# Substitute a single variable
$ export API_URL=https://circleci.com
$ circleci env subst "Base URL: $API_URL"# Substitute variables in a JSON payload via stdin
$ export TOKEN=abc123
$ echo '{"token": "$TOKEN"}' | circleci env subst# Substitute into a config file before uploading
$ circleci env subst < .circleci/config.template.yml > .circleci/config.yml🔐 envvar <command> 🔐
List, set and delete a project's environment variables — full custody of your secrets, bestie 💅
📦 COMMANDS 📦
💀 delete <name> 💀
Delete a project environment variable. Gone. Poof. No take-backs. 😭
🦋 OPTIONS 🦋
-f,--force— skip confirmation prompt 🙈--project— project slug (e.g.gh/org/repo); defaults to git remote 😌
💖 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🍓 list 🍓
List project environment variables — the whole roster 👑
⭐ OPTIONS ⭐
--jq— process values from the response using jq syntax ✨--json— output as JSON 🫶--project— project slug (e.g.gh/org/repo); defaults to git remote 😌
🌸 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🧚 set <name> <value> 🧚
Set a project environment variable ✨ new key, new value, new you 💅
🎀 OPTIONS 🎀
--project— project slug (e.g.gh/org/repo); defaults to git remote 😌
🔥 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)"🦋 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🧩 extension <command> 🧩
Manage CLI extensions — plug-ins for your fave CLI, iykyk 💅
📦 COMMANDS 📦
⭐ install <extension> ⭐
Install an extension ✨
💜 EXAMPLES 💜
# Install the testsuite extension
$ circleci extension install testsuite🍓 remove <extension> 🍓
Remove an installed extension 👋
🌈 OPTIONS 🌈
-f,--force— skip confirmation prompt 🙈
👑 EXAMPLES 👑
# Remove using the name of the extension
$ circleci extension remove <name># Remove using the full binary name
$ circleci extension remove circleci-<name># Remove without confirmation prompt
$ circleci extension remove <name> --force💌 feedback <message> 💌
Send feedback about the CLI to CircleCI — tell them how you feel, bestie, they literally want to know 🫶✨
🌸 OPTIONS 🌸
--jq— process values from the response using jq syntax ✨--json— output as JSON 🫶--tool— the CLI command or MCP tool this feedback is actually about (like"run get") 👈
✨ EXAMPLES ✨
# Report a missing capability
$ circleci feedback "I wanted to compare job timings between two runs but found no command for it"
# Report confusing output from a command
$ circleci feedback "run get shows no jobs for a run that has three" --tool "run get"
# Capture just the report ID
$ circleci feedback "context list printed nothing for an org with contexts" --json --jq '.id'🌸 help [command]
Bestie. It gives you help about any command. That's it, that's the whole vibe. Whenever you're lost, just ask for help 🫶 (no shade, we've all been there).
🔥 job <command>
This is the whole job-inspection situation — details, output, artifacts, all of it. Main character energy for your build jobs 💅
artifact <job-id>
List or download artifacts for a job. Your files! The things your build made! 🎀
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON-o,--output— download artifacts into this directory
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 --jsonget <job-id>
Get job details.</purl> Just, like, the whole run-down on one job ✨
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as 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'open <job-id>
Open job in browser.</purl> One command and boom, you're in the UI looking at it with your own two eyes 👀💻
EXAMPLES
# Open job by UUID
$ circleci job open 8e50c384-0083-43d0-bc8f-93f0db589d6boutput <command>
Work with job step output.</purl> This is where the receipts live, bestie 😭 the actual logs, step by step.
COMMANDS
get <job-id>
Get the output of a job step. One step, one big ol' blob of text 🫠
OPTIONS
--condensed— fetch error-relevant lines only, filtered server-side (this one is experimental ⚠️)--execution— parallel execution index to read output from--step-num— step number whose output to fetch (required — like, you gotta give it one, no cap)--strip-ansi— force ANSI stripping (or with=false, disable it); defaults to stripping only when it's not a terminal
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?"list <job-id>
List a job's steps with their output — the full tour, every step, all the drama 💀
OPTIONS
--execution— parallel execution index to list output from--jq— process values from the response usingjqsyntax--json— output as JSON--tail— show only the last N lines of each step's output in the rendered view (0for all of them)
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 0resource-usage <command>
Work with a job's CPU and memory usage.</purl> For when your build is being a lil resource-hungry gremlin and you need to know exactly how hungry 🍓📈
COMMANDS
get <job-id>
Chart a job's CPU and memory usage. Pretty little graphs, bestie 🌈✨
OPTIONS
--chart— plot parallel executions together or apart, one ofauto|combined|separate--execution— parallel execution index to report on (default is all of them)--jq— process values from the response usingjqsyntax--json— output as JSON
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'🦋 mcp
Run the CLI as an MCP server for AI tools 🤖💜 lowkey the coolest part ngl.
COMMANDS
claude
Manage Claude Desktop MCP servers. Yes, that Claude. Your AI bestie deserves config too 🫶
COMMANDS
disable — remove server from Claude config
OPTIONS
--config-path— path to Claude config file--server-name— name of the MCP server to remove
enable — add server to Claude config
OPTIONS
--config-path— path to Claude config file-e,--env— environment variables (like--env KEY1=value1 --env KEY2=value2)--log-level— log level (debug,info,warn,error)--server-name— name for the MCP server
list — show Claude MCP servers
OPTIONS
--config-path— path to Claude config file
cursor
Manage Cursor MCP servers 🖱️✨
COMMANDS
disable — remove server from Cursor config
OPTIONS
--config-path— path to Cursor config file--server-name— name of the MCP server to remove--workspace— remove from workspace settings (.cursor/mcp.json) instead of user settings
enable — add server to Cursor config
OPTIONS
--config-path— path to Cursor config file-e,--env— environment variables (like--env KEY1=value1 --env KEY2=value2)--log-level— log level (debug,info,warn,error)--server-name— name for the MCP server--workspace— add to workspace settings (.cursor/mcp.json) instead of user settings
list — show Cursor MCP servers
OPTIONS
--config-path— path to Cursor config file--workspace— list from workspace settings (.cursor/mcp.json) instead of user settings
start
Start the MCP server 🔥 like, actually run it.
OPTIONS
--log-level— log level (debug,info,warn,error)
stream
Stream the MCP server over HTTP 🌊 serving it up, but like, continuously.
OPTIONS
--host— host to listen on--log-level— log level (debug,info,warn,error)--port— port number to listen on
tools
Export tools as JSON 🧰 everything laid out in nice machine-readable form.
OPTIONS
--log-level— log level (debug,info,warn,error)
vscode
Manage VSCode MCP servers 💻🎀
COMMANDS
disable — remove server from VSCode config
OPTIONS
--config-path— path to VSCode config file--server-name— name of the MCP server to remove--workspace— remove from workspace settings (.vscode/mcp.json) instead of user settings
enable — add server to VSCode config
OPTIONS
--config-path— path to VSCode config file-e,--env— environment variables (like--env KEY1=value1 --env KEY2=value2)--log-level— log level (debug,info,warn,error)--server-name— name for the MCP server--workspace— add to workspace settings (.vscode/mcp.json) instead of user settings
list — show VSCode MCP servers
OPTIONS
--config-path— path to VSCode config file--workspace— list from workspace settings (.vscode/mcp.json) instead of user settings
🧚 migrate <command>
Migrate workflows from other CI platforms to CircleCI. Come to the good side, we have cookies 🍓✨
COMMANDS
actions <workflow-file>
Copy a GitHub Actions workflow into .circleci/workflows/ — snatch it right out of .github and make it ours 💅
OPTIONS
--force— overwrite the destination file if it already exists (yes, it will clobber it, that's the whole point ⚠️)
EXAMPLES
# Migrate a single workflow file
$ circleci migrate actions .github/workflows/run_tests.yml
# Migrate a workflow stored at a non-standard path
$ circleci migrate actions ci/build.yml
# Overwrite an existing destination file
$ circleci migrate actions --force .github/workflows/run_tests.yml👑 my <command>
Show resources for the authenticated user. It's giving main character — this is your stuff, and only yours 🪞💖
COMMANDS
runs
List your recent runs grouped by project 🗂️ everything you've been up to, nicely sorted.
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON--limit— the max number of runs we're pulling down [default:20] — no, we are not scrolling forever, bestie 💅
✨ EXAMPLES ✨
# List your recent runs across all projects
$ circleci my runs# Show more results
$ circleci my runs --limit 50# Output as JSON for scripting
$ circleci my runs --json# Pull out just the run IDs with jq
$ circleci my runs --json --jq '.[].id'🎀 namespace <command> 🎀
Okay so this is the whole vibe behind the org namespace that your orbs publish under — managing it, claiming it, renaming it, yeeting it. It's giving "behind the scenes but make it iconic" ✨
create <name> --org <org>
Claim a namespace, bestie — this is how you stake your claim 👑
OPTIONS
--jq— process values from the response using jq syntax 🪄--json— output as JSON--org— Organization slug (e.g.gh/myorg) or UUID to claim the namespace for (required) — like, non-negotiable, you must pass this 🫶
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'delete <name>
Deletes a namespace — and like, all its orbs too. Not a drill 😭 Everything goes. Periodt.
OPTIONS
-n,--dry-run— print what would be deleted without actually deleting — the responsible queen move 👑-f,--force— skip confirmation prompt
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🚨 Heads up: in a CI environment it's non-interactive, so --force is required. No prompt to save you there, bestie.
get <name>
Get the deets on a namespace — the little info pull 🔍
OPTIONS
--jq— process values from the response using jq syntax--json— output as JSON
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'rename <name> <new-name>
Rename a namespace — glow-up era 💫 (takes the old name, then the new name, in that order, iykyk)
OPTIONS
--jq— process values from the response using jq syntax--json— output as JSON
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'🔔 notification <command> 🔔
Configure where CircleCI sends your notifications. Like deciding who gets the texts 📲
slack <command>
Send a project's notifications straight into a Slack channel 🫶
delete
Remove a project's Slack channel — unsubscribing, but make it official 💀
OPTIONS
-n,--dry-run— show what would be removed without removing it-f,--force— skip confirmation prompt--project— project slug (e.g.gh/org/repo); defaults to git remote — so if you don't say anything, it sniffs your remote, cute right?
EXAMPLES
# Remove the current project's Slack channel (with confirmation)
$ circleci notification slack delete# Preview what would be removed
$ circleci notification slack delete --dry-run# Remove it from a specific project without confirmation
$ circleci notification slack delete --project gh/myorg/myrepo --forceget
Show a project's Slack channel and its Slack preferences — the full vibe check 👀
OPTIONS
--jq— process values from the response using jq syntax--json— output as JSON--project— project slug (e.g.gh/org/repo); defaults to git remote
EXAMPLES
# Show the current project's Slack channel
$ circleci notification slack get# Show it for a specific project
$ circleci notification slack get --project gh/myorg/myrepo# Print only the channel ID
$ circleci notification slack get --json --jq .channel_idset (--channel <name|ID> | --enable | --disable)
Set, enable or disable a project's Slack channel — the main character of this whole notification situation 🌟 You pick ONE of those modes, okay?
OPTIONS
--channel— Slack channel name (e.g.#ci-alerts) or ID to send notifications to--disable— pause Slack notifications, keeping the configured channel — like muting, not blocking 🙈--enable— resume Slack notifications for the configured channel--jq— process values from the response using jq syntax--json— output as JSON--project— project slug (e.g.gh/org/repo); defaults to git remote
EXAMPLES
# Send the current project's notifications to #ci-alerts
$ circleci notification slack set --channel '#ci-alerts'# Use a channel ID (required for private channels)
$ circleci notification slack set --channel C0123ABCD --project gh/myorg/myrepo# Pause Slack notifications, keeping the channel
$ circleci notification slack set --disable# Resume them and print the result as JSON
$ circleci notification slack set --enable --json💡 Fr fr:--channeltakes a name like#ci-alertsor an ID — but for private channels you need the ID. No cap.
🚀 onboard [path] 🚀
Guided onboarding, bestie — it generates config, signs you up, and connects your project. The whole starter-pack arc 🎀
OPTIONS
--no-browser— print the signup URL instead of opening a browser--org— Organization slug (e.g.gh/myorg) or UUID to set the project up in--repo-id— Repository ID, if it can't be resolved from the git remote--scan— Skip prompt: set up this repo on CircleCI--signup— Skip prompt: sign up for CircleCI
EXAMPLES
# Interactive mode: choose repo setup or signup
$ circleci onboard# Set up the current directory (skip the choice prompt)
$ circleci onboard --scan# Set up in a named org (required when you belong to several)
$ circleci onboard --scan --org gh/acme# Sign up for CircleCI (no repo needed)
$ circleci onboard --signup⚠️ If you belong to several orgs,--orgis required with--scan. It can't read your mind, sadly 😭
🧚 orb <command> 🧚
Create, publish and inspect orbs — aka reusable config, aka the moment everything gets iconic ✨
OPTIONS
--host— CircleCI host (deprecated: setCIRCLE_HOST) — yeah she's deprecated, use the env var 💅--token— CircleCI API token (deprecated: setCIRCLE_TOKEN) — same story, env var it is
add-to-category <namespace>/<orb> <category>
Add an orb to a registry category — filing it under the right aesthetic 🗂️
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-categoriescreate <namespace>/<orb>
Reserve an orb name in a namespace — calling dibs, but legally 🫶
OPTIONS
--jq— process values from the response using jq syntax--json— output as JSON--private— create as a private orb
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 --jsondiff <namespace>/<orb> --from <v1> --to <v2>
Show a unified diff between two orb versions — the "what changed" reveal 🔍
OPTIONS
--from— the first version (semver e.g.1.0.0, or a dev label e.g.dev:my-branch)--to— the second version, in the same form as--from
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-bget <namespace>/<orb>[@<version>]/<orb-id>
Get orb metadata and statistics — the full dossier 📊
OPTIONS
--jq— process values from the response using jq syntax--json— output as JSON
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 --jsoninit <path>
Initialize a brand new orb project — fresh start energy 🌱
OPTIONS
--branch— primary git branch to track--org— Organization slug (e.g.gh/myorg) or UUID to own the orb namespace and publishing context--private— initialize a private orb--remote— 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 — the "just give me the files" mode 🙈
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-gitlist [<namespace>]
List orbs in the registry — window shopping but for config 👑 (takes an optional namespace)
OPTIONS
--jq— process values from the response using jq syntax--json— output as JSON--private— only list private orbs (requires namespace)--uncertified— include uncertified orbs
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 --privatelist-categories
List orb registry categories — every bucket your orb could live in 🗂️✨
OPTIONS
--jq— process values from the response using jq syntax--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'pack <path>
Bestie, this one packs a whole multi-file orb directory into a single YAML file. It's giving "cleanup era" 💅
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 -process <path>
Validate and print the expanded orb YAML ✨ (yes, it validates and shows you the fully-expanded glow-up).
OPTIONS
--org— organization slug (e.g.gh/myorg) or UUID for private orb dependencies
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/acmepublish <command>
Publish orb versions 🚀 the moment where your orb goes public, no cap.
COMMANDS
increment <path> <namespace>/<orb> --bump major|minor|patch
Increment and publish a brand-new orb version. Two birds, one iconique command 🦋
OPTIONS
--bump— which version segment to increment:major,minor, orpatch
EXAMPLES
# Increment patch version and publish
$ circleci orb publish increment orb.yml myorg/my-orb --bump patch# Increment minor version
$ circleci orb publish increment orb.yml myorg/my-orb --bump minor# Read orb from stdin, increment major
$ cat orb.yml | circleci orb publish increment - myorg/my-orb --bump majorpromote <namespace>/<orb>@dev:<label> --bump major|minor|patch
Promote a dev orb version into a stable semver 🎀 like, your dev version got its main character moment.
OPTIONS
--bump— which version segment to increment:major,minor, orpatch
EXAMPLES
# Promote dev:my-branch to a patch release
$ circleci orb publish promote myorg/my-orb@dev:my-branch --bump patch# Promote to a minor release
$ circleci orb publish promote myorg/my-orb@dev:my-branch --bump minor# Promote to a major release
$ circleci orb publish promote myorg/my-orb@dev:my-branch --bump majorEXAMPLES
# Publish a specific version
$ circleci orb publish orb.yml myorg/my-orb@1.0.0# Publish a dev version
$ circleci orb publish orb.yml myorg/my-orb@dev:my-branch# Promote a dev version to a patch release
$ circleci orb publish promote myorg/my-orb@dev:my-branch --bump patch# Increment major version and publish
$ circleci orb publish increment orb.yml myorg/my-orb --bump majorremove-from-category <namespace>/<orb> <category>
Remove an orb from a registry category 🫶 sometimes you just gotta un-tag yourself from the vibe.
EXAMPLES
# Remove an orb from the Testing category
$ circleci orb remove-from-category myorg/my-orb "Testing"# Remove an orb from the Deployment category
$ circleci orb remove-from-category myorg/my-orb "Deployment"# See current categories
$ circleci orb get myorg/my-orbsource <namespace>/<orb>[@<version>]
Print the YAML source of an orb version 👑 straight-up receipts, no filter.
EXAMPLES
# Print source of the latest version
$ circleci orb source myorg/my-orb# Print source of a specific version
$ circleci orb source myorg/my-orb@1.2.3# Print source of a dev version
$ circleci orb source myorg/my-orb@dev:my-branch# Save the source to a file
$ circleci orb source myorg/my-orb@1.0.0 > orb.ymlunlist <namespace>/<orb>
Hide or restore an orb in the registry 🙈 lowkey stealth mode for your orb.
OPTIONS
--restore— restore the orb's visibility instead of hiding it
EXAMPLES
# Hide an orb from the registry
$ circleci orb unlist myorg/my-orb# Restore an orb's visibility
$ circleci orb unlist myorg/my-orb --restorevalidate <path>
Validate an orb YAML file ✅ vibe check for your orb, fr fr.
OPTIONS
--org— organization slug (e.g.gh/myorg) or UUID for private orb dependencies--org-id— organization slug or UUID (deprecated: use--org) 💀--org-slug— organization slug or UUID (deprecated: use--org) 💀
EXAMPLES
# Validate an orb file
$ circleci orb validate orb.yml# Validate from stdin
$ cat orb.yml | circleci orb validate -# Validate with a specific org for private deps
$ circleci orb validate orb.yml --org gh/acmeorg <command>
Manage CircleCI organizations 🏢✨ your whole org situation, handled.
COMMANDS
create <name>
Create an organization 🌱 new org, who dis.
OPTIONS
--jq— process values from the response using jq syntax--json— output as JSON
EXAMPLES
# Create an organization
$ circleci org create acme# Create one and output as JSON for scripting
$ circleci org create acme --json# Capture the slug to pass to --org
$ circleci org create acme --json --jq '.slug'list
List organizations you belong to 💖 your org family tree.
OPTIONS
--jq— process values from the response using jq syntax--json— output as JSON
EXAMPLES
# List all your organizations
$ circleci org list# Output as JSON for scripting
$ circleci org list --json# Extract just the IDs
$ circleci org list --json --jq '.[].id'setting <command>
View and update org advanced settings ⚙️ the deep-lore switches.
COMMANDS
get <setting>
Get the current value of an org setting 🔍
OPTIONS
--jq— process values from the response using jq syntax--json— output as JSON--org— organization slug (e.g.gh/myorg) or UUID; defaults to git remote
EXAMPLES
# Get a setting for the current org
$ circleci org setting get private-orbs# Get a setting for a specific org
$ circleci org setting get private-orbs --org gh/myorg# Output as JSON
$ circleci org setting get private-orbs --jsonlist
List all advanced settings for an org 📋 the full settings haul.
OPTIONS
--jq— process values from the response using jq syntax--json— output as JSON--org— organization slug (e.g.gh/myorg) or UUID; defaults to git remote
EXAMPLES
# List settings for the current org
$ circleci org setting list# List settings for a specific org
$ circleci org setting list --org gh/myorg# Output as JSON
$ circleci org setting list --jsonset <setting> <true|false>
Set an org setting 🎚️ flip the switch, queen.
OPTIONS
--jq— process values from the response using jq syntax--json— output as JSON--org— organization slug (e.g.gh/myorg) or UUID; defaults to git remote
EXAMPLES
# Enable a setting for the current org
$ circleci org setting set private-orbs true# Disable a setting for a specific org
$ circleci org setting set private-orbs false --org gh/myorg# Output the updated value as JSON
$ circleci org setting set ai-error-summarization true --jsonpipeline <command>
Manage the pipeline definitions a run executes 🌈 this is the stuff that decides what actually runs, iykyk.
COMMANDS
create
Create a pipeline definition ✨
OPTIONS
--checkout-provider— checkout source provider (one of:github_app,github_server,origin)--checkout-repo-full-name— checkout source repo owner/name (required fororigin)--checkout-repo-id— checkout source repo external ID--config-file— config file path (e.g..circleci/config.yml)--config-file-type— config file type, omit for standard CircleCI YAML (one of:github-actions)--config-provider— config source provider (one of:github_app,github_server,circleci,origin)--config-repo-full-name— config source repo owner/name (required fororigin)--config-repo-id— config source repo external ID (required forgithub_app,github_server,origin)--description— pipeline definition description--jq— process values from the response using jq syntax--json— output as JSON--name— pipeline definition name (required)--project— project slug (e.g.gh/org/repo); defaults to git remote--project-id— 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 for a Cursor repository (Origin needs the owner/name too)$ circleci pipeline create \
--project-id a1b2c3d4-... \
--name "my-pipeline" \
--config-provider origin \
--config-repo-id repo_01abc \
--config-repo-full-name myorg/myrepo \
--config-file .circleci/config.yml \
--checkout-provider origin \
--checkout-repo-id repo_01abc \
--checkout-repo-full-name myorg/myrepolist — pipeline definitions, but make it a list ✨
Okay so list does exactly what it says: list pipeline definitions for a project. Lowkey the most chill subcommand here, no cap.
OPTIONS 💅
--jq— process values from the response usingjqsyntax--json— output as JSON--project— project slug (e.g.gh/org/repo); defaults to git remote--project-id— project UUID (overrides--project)
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")'run — trigger a new pipeline run 🔥
This one triggers a brand-new pipeline run. It's giving main character energy, fr fr.
OPTIONS 💅
-b,--branch— branch for config fetch and checkout (mutually exclusive with--tag)--definition-id— pipeline definition UUID to run (prompted interactively if omitted)--jq— process values from the response usingjqsyntax--json— output as JSON--param— pipeline parameter askey=value(repeatable)--project— project slug (e.g.gh/org/repo); defaults to git remote-t,--tag— 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 --jsonpolicy <command> — govern config with Rego security policies 🛡️
This is the security-guard era of your config: Rego security policies. It's giving locked door, but make it YAML.
COMMANDS 🛡️
decide — evaluate a config against remote policies
This is the vibe check for your config, bestie. It evaluates a config against remote policies.
OPTIONS 💅
--input— path to input file (e.g..circleci/config.yml) (required)--jq— process values from the response usingjqsyntax--json— output as JSON--meta— decision metadata as a JSON string--metafile— path to decision metadata file (YAML or JSON)--org— organization slug (e.g.gh/myorg) or UUID (required)--policy-context— policy context--strict— exit non-zero forHARD_FAILorERRORdecisions
EXAMPLES 🎀
# Evaluate a config against remote policies
$ circleci policy decide --org gh/acme --input .circleci/config.yml
# Exit non-zero on hard failures
$ circleci policy decide --org gh/acme --input .circleci/config.yml --strict
# Pass metadata alongside the decision
$ circleci policy decide --org gh/acme --input .circleci/config.yml --meta '{"project_id":"abc"}'
# Output decision as JSON
$ circleci policy decide --org gh/acme --input .circleci/config.yml --jsondiff <path> — show diff between local and remote policy bundles
Show the diff between your local policy bundle and the remote one. Spot the difference, but make it security.
OPTIONS 💅
--jq— process values from the response usingjqsyntax--json— output as JSON--org— organization slug (e.g.gh/myorg) or UUID (required)--policy-context— policy context
EXAMPLES 🎀
# Diff policies in ./policies against the remote bundle
$ circleci policy diff ./policies --org gh/acme
# Diff against a custom policy context
$ circleci policy diff ./policies --org gh/acme --policy-context config
# Output diff as JSON for scripting
$ circleci policy diff ./policies --org gh/acme --jsoneval <policy-path> — evaluate a raw OPA query against policies locally
This one evaluates a raw OPA query against policies locally. No remote trip needed — it's giving local icon.
OPTIONS 💅
--context— policy context (config compilation only runs when this is"config")--input— path to input file (e.g..circleci/config.yml) (required)--jq— process values from the response usingjqsyntax--json— output as JSON--meta— decision metadata as a JSON string--metafile— path to decision metadata file (YAML or JSON)--no-compile— evaluate the raw config without compiling it first--org— organization slug (e.g.gh/myorg) or UUID for private orb resolution; defaults to git remote--pipeline-parameters— pipeline parameters as a YAML map or path to a YAML file--query— the OPA query to evaluate
EXAMPLES 🎀
# Evaluate a policy directory against a compiled config
$ circleci policy eval ./policies --input .circleci/config.yml
# Evaluate a specific query
$ circleci policy eval ./policies --input .circleci/config.yml --query 'data.org.enable_rule'
# Evaluate the raw (uncompiled) config
$ circleci policy eval ./policies --input .circleci/config.yml --no-compile
# Pass decision metadata
$ circleci policy eval ./policies --input .circleci/config.yml --meta '{"project_id":"abc"}'fetch [policy-name] — download the remote policy bundle
Grab that remote policy bundle. Optionally name one policy and fetch just that one. Obsessed with a targeted download, honestly.
OPTIONS 💅
--jq— process values from the response usingjqsyntax--json— output as JSON--org— organization slug (e.g.gh/myorg) or UUID (required)--policy-context— policy context
EXAMPLES 🎀
# Fetch the full policy bundle
$ circleci policy fetch --org gh/acme
# Fetch a single policy by name
$ circleci policy fetch my-policy --org gh/acme
# Output as JSON with jq filtering
$ circleci policy fetch --org gh/acme --json --jq 'keys'logs [decision-id] — get policy decision logs
Get policy decision logs. Yes bestie, we're reading the receipts. Receipts era.
OPTIONS 💅
--after— return logs created after this time (RFC3339 or YYYY-MM-DD)--before— return logs created before this time (RFC3339 or YYYY-MM-DD)--branch— filter by branch name--jq— process values from the response usingjqsyntax--json— output as JSON--org— organization slug (e.g.gh/myorg) or UUID (required)--out— write output to this file instead of stdout--policy-bundle— retrieve the policy bundle snapshot for the given decision ID--policy-context— policy context--project-id— filter by project ID--status— filter by decision status (PASS,SOFT_FAIL,HARD_FAIL,ERROR)
EXAMPLES 🎀
# Get all decision logs
$ circleci policy logs --org gh/acme
# Get a specific decision log
$ circleci policy logs abc123 --org gh/acme
# Filter by status and branch
$ circleci policy logs --org gh/acme --status HARD_FAIL --branch main
# Write output to a file
$ circleci policy logs --org gh/acme --out logs.jsonpush <path> — push a policy bundle to CircleCI
Push a policy bundle up to CircleCI. It's giving send it live energy.
Heads up: there's a confirmation prompt unless you pass --no-prompt. So no accidental yeet, okay?
OPTIONS 💅
--jq— process values from the response usingjqsyntax--json— output as JSON--no-prompt— skip confirmation prompt--org— organization slug (e.g.gh/myorg) or UUID (required)--policy-context— policy context
EXAMPLES 🎀
# Push policies in the ./policies directory
$ circleci policy push ./policies --org gh/acme
# Push without confirmation prompt
$ circleci policy push ./policies --org gh/acme --no-prompt
# Push to a custom policy context
$ circleci policy push ./policies --org gh/acme --policy-context config
# Output the diff as JSON
$ circleci policy push ./policies --org gh/acme --no-prompt --jsonsettings <command> — manage policy enforcement settings
Manage policy enforcement settings. This is the on/off switch corner, and yes, it has main character energy too.
COMMANDS 🎀
get — get policy enforcement settings
OPTIONS 💅
--jq— process values from the response usingjqsyntax--json— output as JSON--org— organization slug (e.g.gh/myorg) or UUID (required)--policy-context— policy context
EXAMPLES 🎀
# Get policy enforcement settings
$ circleci policy settings get --org gh/acme
# Output as JSON
$ circleci policy settings get --org gh/acme --json
# Use with jq to extract the enabled field
$ circleci policy settings get --org gh/acme --json --jq '.enabled'set — update policy enforcement settings
OPTIONS 💅
--enabled— enable policy enforcement--jq— process values from the response usingjqsyntax--json— output as JSON--org— organization slug (e.g.gh/myorg) or UUID (required)--policy-context— policy context
EXAMPLES 🎀
# Enable policy enforcement
$ circleci policy settings set --org gh/acme --enabled
# Disable policy enforcement
$ circleci policy settings set --org gh/acme --enabled=false
# Output result as JSONokay picking right back up where those settings examples left off, last one in that batch:
$ circleci policy settings set --org gh/acme --enabled --jsontest <path>
Run policy tests 🧪 like, actually run them, bestie, and see what passes.
OPTIONS
--all— show every test, not just the failures. yes, including the passing ones, we love a full picture 💅--explain— print each test's full evaluation context. heads up: this one implies--all, so you get everything whether you asked or not 🫶--jq— process values from the response usingjqsyntax. for the girlies who think in filters ✨--json— output as JSON--junit— output results as JUnit XML--org— Organization slug (e.g.gh/myorg) or UUID for private orb resolution when a test compiles; defaults to git remote 🎀--run— only run tests whose name matches this regexp. filter your faves, we gatekeep responsibly 🔥
EXAMPLES
# Run every test under ./policies and its subdirectories
$ circleci policy test ./policies/...# Run tests in a single directory, showing passing tests too
$ circleci policy test ./policies --all# Run only tests whose name matches a regexp
$ circleci policy test ./policies/... --run 'test_enforce_.*'# Emit JUnit XML for CI
$ circleci policy test ./policies/... --junitproject <command>
List, follow and configure CircleCI projects 🌸 your whole project-management era.
create [project-name] --org <vcs/org-slug>
Create a new project ✨ brand new, fresh out the box.
OPTIONS
--json— output as JSON--org— organization slug (e.g.gh/myorg)
EXAMPLES
# Create a project (prompted for name if run interactively)
$ circleci project create --org gh/myorg# Create a GitHub-hosted project
$ circleci project create my-new-repo --org gh/myorg# Create a CircleCI-native project (standalone pipelines)
$ circleci project create new-service --org circleci/9YytKzouJxzu4TjCRFqAoD# Create a project and output as JSON for scripting
$ circleci project create my-new-repo --org gh/myorg --jsondlc <command>
Purge a project's Docker layer cache (DLC) 🧼 sometimes you just gotta clear the cache, no cap.
COMMANDS
purge
Purge the Docker Layer Cache for a project.
OPTIONS
-f,--force— skip confirmation prompt, living dangerously (but efficiently) 💀--json— output as JSON--project— 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/myrepoEXAMPLES
# 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 --jsonenvvar <command>
List, set and delete a project's environment variables 🔐 secrets stay secret, iykyk.
COMMANDS
delete <name>
Delete a project environment variable. gone, girl, bye 👋
OPTIONS
-f,--force— skip confirmation prompt--project— project slug (e.g.gh/org/repo); defaults to git remote
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 --forcelist
List project environment variables 📋 a whole little roster.
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON--project— project slug (e.g.gh/org/repo); defaults to git remote
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 --jsonset <name> <value>
Set a project environment variable ✨ give it a name and a value and it's iconic now.
OPTIONS
--project— project slug (e.g.gh/org/repo); defaults to git remote
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)"okay real talk, careful with MY_SECRET s3cr3t typed directly on a command line — that's between you and your shell history 🙈
follow
Follow a project 💖 hit that follow button, become a supporter.
OPTIONS
--project— project slug (e.g.gh/org/repo); defaults to git remote
EXAMPLES
# Follow the project for the current git repository
$ circleci project follow# Follow a specific project
$ circleci project follow --project gh/myorg/myrepo# Follow a Bitbucket project
$ circleci project follow --project bb/myorg/myrepoget
Show project details 🔍 the full profile, no filter.
OPTIONS
--json— output as JSON--project— project slug (e.g.gh/org/repo); defaults to git remote
EXAMPLES
# Show details for the current git repository's project
$ circleci project get# Show details for a specific project
$ circleci project get --project gh/myorg/myrepo# Output as JSON for scripting
$ circleci project get --jsonlink
Bind this checkout to a CircleCI project 🔗 it's giving committed relationship.
OPTIONS
-f,--force— overwrite an existing.circleci/info.yml--project— project slug (e.g.gh/org/repoorcircleci/<orgID>/<projectID>)
EXAMPLES
# Auto-detect from the current git repository
$ circleci project link# Bind to a specific project (skips lookup if it exists)
$ circleci project link --project gh/myorg/myrepo# Bind to a standalone project by its CircleCI slug
$ circleci project link --project circleci/<orgID>/<projectID># Overwrite an existing .circleci/info.yml
$ circleci project link --forcelist
List projects 📚 a whole lineup.
OPTIONS
--following— only projects you follow (default when no other filter is given)--jq— process values from the response usingjqsyntax--json— output as JSON--name— only projects matching this name--org-id— only projects in this organization UUID--slug— resolve one project by slug (e.g.gh/myorg/myrepo)
EXAMPLES
# List the projects you follow
$ circleci project list# List every project in an organization
$ circleci project list --org-id 8f7c5a1e-0000-4000-8000-000000000001# Resolve a single project by slug
$ circleci project list --slug gh/myorg/myrepo# Output as JSON for scripting
$ circleci project list --jsonopen
Open the project page in the browser 🌐 literally one command and you're there.
OPTIONS
--project— project slug (e.g.gh/org/repo); defaults to git remote
EXAMPLES
# Open the project page for the current repo
$ circleci project open# Open the project page for a specific project
$ circleci project open --project gh/myorg/myrepo# Open when your remote is on CircleCI server
$ circleci project open --host https://circleci.example.comsetting <command>
View and update project advanced settings ⚙️ the deep-lore settings, bestie.
COMMANDS
get <setting>
Get the current value of a project setting.
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON--project— project slug (e.g.gh/org/repo); defaults to git remote
EXAMPLES
# Get a setting for the current project
$ circleci project setting get build-forked-pull-requests# Get a setting for a specific project
$ circleci project setting get build-forked-pull-requests --project gh/myorg/myrepo# Output as JSON
$ circleci project setting get build-forked-pull-requests --jsonlist
List all advanced settings for a project 📝 the whole settings menu, laid out.
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON--project— project slug (e.g.gh/org/repo); defaults to git remote
EXAMPLES
# List settings for the current project
$ circleci project setting list# List settings for a specific project
$ circleci project setting list --project gh/myorg/myrepo# Output as JSON
$ circleci project setting list --jsonset <setting> <true|false>
Set a project setting 🎚️ flip it on, flip it off.
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON--project— project slug (e.g.gh/org/repo); defaults to git remote
EXAMPLES
# Enable a setting for the current project
$ circleci project setting set build-forked-pull-requests true# Disable a setting for a specific project
$ circleci project setting set build-forked-pull-requests false --project gh/myorg/myrepo# Output the updated value as JSON
$ circleci project setting set auto-cancel-builds true --jsontrigger <command>
Manage project triggers ⏰ the "make it go when X happens" department.
🎀 create 🎀
Bestie, this one spins up a brand-new project trigger. Slay.
OPTIONS
--checkout-ref— the Git ref we check out code with. Only needed when the checkout repo is not the same as the event source repo, iykyk.--config-ref— the Git ref we fetch config with. Again: only needed when the config repo differs from the event source repo.--event-preset— the preset that filters which events fire this trigger. One of:all-pushes,only-tags,default-branch-pushes,only-build-prs,only-open-prs,only-labeled-prs,only-merged-prs,only-ready-for-review-prs,only-branch-delete,only-build-pushes-to-non-draft-prs,only-merged-or-closed-prs,pr-comment-equals-run-ci,non-draft-pr-opened,pushes-to-merge-queues. Yes it's a long list, no I'm not skipping any of them 💅--jq— process values from the response usingjqsyntax--json— output as JSON--pipeline-definition-id— pipeline definition ID (required ⭐)--project— project slug, likegh/org/repo; defaults to your git remote--project-id— project UUID (this overrides--project)--provider— the event source provider. One of:github_app,github_server,github_oauth,origin,webhook,schedule--repo-full-name— repositoryowner/name(required fororigin)--repo-id— repository external ID (required forgithub_app,github_server,github_oauth,origin)
EXAMPLES
# Create a GitHub App trigger (provider defaults to github_app)
$ circleci project trigger create \
--pipeline-definition-id a1b2c3d4-... \
--repo-id 123456789# Create a trigger for a Cursor repository (Origin needs the owner/name too)
$ circleci project trigger create \
--provider origin \
--pipeline-definition-id a1b2c3d4-... \
--repo-id repo_01abc \
--repo-full-name myorg/myrepo# Create a trigger with event filtering and output as JSON
$ circleci project trigger create \
--pipeline-definition-id a1b2c3d4-... \
--repo-id 123456789 \
--event-preset all-pushes \
--json🌈 list 🌈
Lists out all the triggers hanging off a pipeline definition. It's giving inventory day.
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON--pipeline-definition-id— pipeline definition ID (required ⭐)--project— project slug, likegh/org/repo; defaults to your git remote--project-id— project UUID (overrides--project)
EXAMPLES
# List triggers for the current repository's project
$ circleci project trigger list \
--pipeline-definition-id a1b2c3d4-...# List triggers for a specific project
$ circleci project trigger list \
--project gh/myorg/myrepo \
--pipeline-definition-id a1b2c3d4-...# Output as JSON for scripting
$ circleci project trigger list \
--pipeline-definition-id a1b2c3d4-... \
--json👑 run <command> 👑
The main-character command: trigger runs, watch them, approve them, cancel them. Your whole pipeline life is in here, fr fr.
🛠 COMMANDS 🛠
💜 approve <run-number-or-id> 💜
Gives the green light to an approval job that's currently sitting on hold. Go 👏 ahead 👏.
OPTIONS
-f,--force— skip the confirmation prompt--job— name or UUID of the approval job you want to approve--jq— process values from the response usingjqsyntax--json— output as JSON--project— project slug, likegh/org/repo; used when you're approving by number
EXAMPLES
# Approve the approval job on hold in run 75 (with confirmation)
$ circleci run approve 75# Approve a specific approval job by name, without confirmation
$ circleci run approve 75 --job hold-deploy --force# Approve the hold on the latest run on main, by run UUID
$ circleci run list --branch main --json --jq '.[0].id' | xargs circleci run approve --force💀 cancel <run-number-or-id> 💀
Nukes a run. Bye bestie 🫶
OPTIONS
-f,--force— skip the confirmation prompt--project— project slug, likegh/org/repo; used when you're cancelling by number
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🦋 get [<run-id>] 🦋
Fetches the status of a run. It's the vibe check for your pipeline.
OPTIONS
-b,--branch— branch name (defaults to the current branch, ormainwhen--projectis set)--failure-report— prints condensed output for every failed step; made for agent consumption 🤖--jq— process values from the response usingjqsyntax--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— project slug, likegh/org/repo; used for the latest-run lookup
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⭐ list ⭐
Recent runs for a project, all lined up like a little runway.
OPTIONS
-b,--branch— filter by branch-B,--current-branch— filter by the branch you currently have checked out--jq— process values from the response usingjqsyntax--json— output as JSON--limit— max number of runs to show [default:10]--project— project slug, likegh/org/repo; defaults to your git remote
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🌸 open 🌸
Pops open the current project's runs page in your browser. Cute, convenient, no notes.
OPTIONS
-b,--branch— branch name (defaults to the current branch)--project— project slug, likegh/org/repo; used for the 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🔥 trigger 🔥
Kicks off a brand new run. Hit send bestie 💌
OPTIONS
-b,--branch— branch to trigger (defaults to the current branch)--jq— process values from the response usingjqsyntax--json— output as JSON--parameter— run parameter askey=value(repeatable)--project— project slug, likegh/org/repo; defaults to your 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🧚 watch [<run-id>] 🧚
Sits with a run until it finishes. Emotional support watcher, basically 😭
OPTIONS
-b,--branch— branch to watch (defaults to the current branch)--failfast— bail out the second any job fails, no waiting around for the rest of the run--project— project slug, likegh/org/repo; defaults to your git remote--sha— watch the run for this commit SHA; polls up to2mif it hasn't been created yet--timeout— max time to wait for the run to complete
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🫶 runner <command> 🫶
Everything self-hosted-runner related. Your own machines, your own rules ✨
🛠 COMMANDS 🛠
🍓 config <resource-class> 🍓
Generates the config for a self-hosted runner. One resource class, one config, iconic.
OPTIONS
--name— runner name, machine only (default:hostname)--nickname— nickname for the new token-o,--output— write config to this file instead of stdout--product— runner product:machine|container|machineOrchestrator(defaultmachine, prompts when unset)--token— bestie, if you already have a token value lying around, pass it here and we'll use that instead of minting a shiny new one ✨--working-directory— the job working directory. machine only, babes — container runner doesn't wanna hear it 💅
✨ EXAMPLES ✨
Generate a machine runner 3 config, using the hostname as the runner name:
# Generate machine runner 3 config, using the hostname as the
# runner name
$ circleci runner config my-org/my-runnerWrite the machine runner config straight to the path the agent actually reads (iconic move, lowkey):
# Write machine runner config to the path the agent reads
$ circleci runner config my-org/my-runner --name prod-server-1
--output /etc/circleci-runner/circleci-runner-config.yamlGenerate Helm values for container runner 🎀
# Generate Helm values for container runner
$ circleci runner config my-org/my-runner --product container
--output values.yamlAnd if you're building config from a token you already have — no API token creation at all:
# Generate config from an existing token value (no API token
# creation)
$ circleci runner config my-org/my-runner --token
"$EXISTING_TOKEN_VALUE"fleet <command> 🌸
View your runner fleets. Yes, fleets. Very main character energy 👑
🎀 COMMANDS 🎀
get <resource-class>
Show a single runner fleet. Just the one. Spotlight moment ✨
OPTIONS
--jq— process values from the response usingjqsyntax. Chef's kiss for plucking out exactly what you want 🧚--json— output as JSON
EXAMPLES
# Show the fleet of a resource class
$ circleci runner fleet get my-org/my-runner# Show it by resource class ID
$ circleci runner fleet get
01234567-89ab-4cde-8f01-23456789abcd# Show how many tasks are waiting for an agent
$ circleci runner fleet get my-org/my-runner --json --jq
'.queued_tasks'list
List runner fleets. Gotta see 'em all 🌈
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON--namespace— filter by namespace (organization)--org— organization slug (e.g.gh/myorg) or UUID; defaults to git remote 🫶--resource-class— filter by resource class (namespace/nameor ID)
EXAMPLES
# List fleets for the org inferred from the git remote
$ circleci runner fleet list# List the fleets in one namespace
$ circleci runner fleet list --namespace my-org# Show the fleet of one resource class, by name or ID
$ circleci runner fleet list --resource-class my-org/my-
runner# Extract the resource classes with no connected agents
$ circleci runner fleet list --json --jq '.[] |
select(.agent_count == 0) | .resource_class'instance <command> 💜
Manage runner instances — the ones actually connected and out here living their lives 🦋
🎀 COMMANDS 🎀
list [namespace | resource-class]
List connected runner instances
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON--namespace— filter by namespace (organization)--org— organization slug (e.g.gh/myorg) or UUID; defaults to git remote--resource-class— filter by resource class (namespace/nameor ID)
EXAMPLES
# List connected instances for the org inferred from the git
# remote
$ circleci runner instance list# List instances for a specific organization (slug or UUID)
$ circleci runner instance list --org gh/my-org# List instances for a namespace
$ circleci runner instance list my-org# List instances for a specific resource class
$ circleci runner instance list my-org/my-runneropen 🔥
Open the runners inventory page in the browser. Literally one command, zero scrolling, we love convenience 💅
OPTIONS
--org— organization slug (e.g.gh/myorg); defaults to git remote
EXAMPLES
# Open runners for the org inferred from git remote
$ circleci runner open# Open runners for a specific organization
$ circleci runner open --org gh/myorg# Open when your remote is on CircleCI server
$ CIRCLE_HOST=https://circleci.example.com circleci runner openngl that last one is the sneaky genius one — set CIRCLE_HOST inline and it'll open the right place on CircleCI server 👑✨
resource-class <command> 🎀
Manage runner resource classes. This is the section, fr fr — create 'em, delete 'em, list 'em, update 'em 😭
🎀 COMMANDS 🎀
create <namespace>/<name>
Create a runner resource class. Fresh out the box ✨
OPTIONS
--description— human-readable description of the resource class--generate-token— also create a token for the resource class, nicknamed"default"--jq— process values from the response usingjqsyntax--json— output as JSON--org— organization slug (e.g.gh/myorg) or UUID; defaults to git remote
EXAMPLES
# Create a resource class in the org inferred from the git
# remote
$ circleci runner resource-class create my-org/my-runner# Create in a specific organization
$ circleci runner resource-class create my-org/my-runner
--org gh/my-org# Create with a description
$ circleci runner resource-class create my-org/my-runner
--description "Linux amd64 runner"# Create a resource class and generate a token nicknamed
# "default"
$ circleci runner resource-class create my-org/my-runner
--generate-token# Output as JSON
$ circleci runner resource-class create my-org/my-runner
--jsondelete <resource-class>
Delete a runner resource class. Bye bestie 💀
OPTIONS
-f,--force— skip confirmation prompt--jq— process values from the response usingjqsyntax--json— output as JSON
EXAMPLES
# Delete a resource class (with confirmation prompt)
$ circleci runner resource-class delete my-org/my-runner# Delete without confirmation
$ circleci runner resource-class delete my-org/my-runner
--force# Delete by ID in a script, and report what was deleted
$ circleci runner resource-class delete
01234567-89ab-4cde-8f01-23456789abcd --force --jsonlist [namespace]
List runner resource classes
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON--namespace— filter by namespace (organization)--org— organization slug (e.g.gh/myorg) or UUID; defaults to git remote--resource-class— filter by resource class (namespace/nameor ID)
EXAMPLES
# List resource classes for the org inferred from the git
# remote
$ circleci runner resource-class list# List resource classes for a specific organization (slug)
$ circleci runner resource-class list --org gh/my-org# List resource classes for a specific organization (UUID)
$ circleci runner resource-class list --org
f22b6566-597d-46d5-ba74-99ef5bb3d85c# List the resource classes in one namespace
$ circleci runner resource-class list my-org# Output as JSON
$ circleci runner resource-class list --org gh/my-org --jsonupdate <resource-class>
Update a runner resource class — glow-up time 🌸
OPTIONS
--description— new description for the resource class (use""to clear)--jq— process values from the response usingjqsyntax--json— output as JSON
EXAMPLES
# Update the description of a resource class
$ circleci runner resource-class update my-org/my-runner
--description "Linux amd64 runner"# Clear the description
$ circleci runner resource-class update my-org/my-runner
--description ""# Update a resource class by its ID
$ circleci runner resource-class update
01234567-89ab-4cde-8f01-23456789abcd --description "ARM
runner"# Update and output the result as JSON
$ circleci runner resource-class update my-org/my-runner
--description "ARM runner" --jsontoken <command> 🔑
Manage runner tokens. Guard these with your life, okay? 🫶
🎀 COMMANDS 🎀
create <resource-class>
Create a token for a resource class
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON--nickname— human-readable nickname for the token
EXAMPLES
# Create a token for a resource class
$ circleci runner token create my-org/my-runner# Create a token with a nickname
$ circleci runner token create my-org/my-runner --nickname
"prod-server-1"# Create a token for a resource class given by its ID
$ circleci runner token create
01234567-89ab-4cde-8f01-23456789abcd# Output as JSON (includes the token value)
$ circleci runner token create my-org/my-runner --jsondelete <token-id>
Delete a runner token
OPTIONS
-f,--force— skip confirmation prompt--jq— process values from the response usingjqsyntax--json— output as JSON
EXAMPLES
# Delete a token by ID (with confirmation prompt)
$ circleci runner token delete
abc12345-0000-0000-0000-000000000000# Delete without confirmation
$ circleci runner token delete
abc12345-0000-0000-0000-000000000000 --force# Delete in a script using JSON output
$ ID=$(circleci runner token list --resource-class my-
org/my-runner --json --jq '.[0].id')
$ circleci runner token delete "$ID" --force --jsonlist [resource-class]
List tokens for a resource class
OPTIONS
--jq— process values from the response usingjqsyntax--json— output as JSON--org— organization slug (e.g.gh/myorg) or UUID; defaults to git remote--resource-class— filter by resource class, either asnamespace/nameor as an ID
EXAMPLES
# List tokens for all resource classes in the org inferred from the git remote
$ circleci runner token list
# List tokens for all resource classes in a specific org
$ circleci runner token list --org gh/my-org
# List tokens for a specific resource class
$ circleci runner token list my-org/my-runner
# Extract IDs with --jq
$ circleci runner token list --resource-class my-org/my-runner --json --jq '.[].id'setting <command> 🎀
Configure the CLI itself — like, the token, the host, the defaults, all that self-care stuff. Your CLI's little morning routine, honestly.
COMMANDS
list — List current CLI settings
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON
EXAMPLES
# Show current settings
$ circleci setting list
# Output as JSON
$ circleci setting list --jsonset <key> <value> — Set a CLI setting
EXAMPLES
# Store your personal API token
$ circleci setting set token mytoken123
# Read the token from stdin to avoid shell history exposure
$ echo "mytoken123" | circleci setting set token -
# Point to a self-hosted CircleCI server
$ circleci setting set host https://circleci.mycompany.com
# Enable telemetry
$ circleci setting set telemetry on
# Disable telemetry
$ circleci setting set telemetry off
# Set the color theme used for rendered output
$ circleci setting set theme dracula
# Pick the color theme interactively
$ circleci setting set theme
# Disable update notifications
$ circleci setting set update-check offBestie, note the-for the value ontoken— that's how you pipe it in through stdin so your token never ends up chillin' in your shell history. Protect your secrets, periodt. 🔐
unset <key> — Remove a stored CLI setting
EXAMPLES
# Remove your stored API token
$ circleci setting unset token
# Revert update notifications to the default
$ circleci setting unset update-checksigning-config <command> 🍎
Manage iOS signing configs. Yes, iOS. Yes, certificates. It's giving ✨developer account anxiety✨ but we're handling it.
COMMANDS
create — Create an iOS signing config
OPTIONS
--cert-id— ID of an uploaded certificate (see:circleci certificate list)--jq— Process values from the response using jq syntax--json— Output as JSON--name— Name for the signing config (referenced in pipeline config)--org— Organization slug (e.g.gh/myorg) or UUID; defaults to git remote--profile— Path to a provisioning profile file (repeatable)
EXAMPLES
# Create a signing config (org inferred from git remote)
$ circleci signing-config create \
--name production-signing \
--cert-id <cert-id> \
--profile ./MyApp.mobileprovision
# Multiple profiles
$ circleci signing-config create \
--name multi-target-signing \
--cert-id <cert-id> \
--profile ./MyApp.mobileprovision \
--profile ./MyAppExtension.mobileprovision
# Explicit org and capture the id for scripting
$ circleci signing-config create --org gh/acme --name prod --cert-id <cert-id> --profile ./p.mobileprovision --json --jq -r '.id'delete <signing-config-id> — Delete an iOS signing config
OPTIONS
-f,--force— skip confirmation prompt
EXAMPLES
# Delete a signing config (with confirmation)
$ circleci signing-config delete <signing-config-id>
# Delete without confirmation
$ circleci signing-config delete <signing-config-id> --forcelist — List iOS signing configs
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON--org— Organization slug (e.g.gh/myorg) or UUID; defaults to git remote
EXAMPLES
# List signing configs (org inferred from git remote)
$ circleci signing-config list
# List for a specific org
$ circleci signing-config list --org gh/acme
# Output as JSON
$ circleci signing-config list --json
# Get signing config names only
$ circleci signing-config list --json --jq '.[].name'profile <command> — Add or remove provisioning profiles on a signing config
COMMANDS
add <signing-config-id> — Add or replace a provisioning profile on a signing config
OPTIONS
--profile— Path to a provisioning profile file
EXAMPLES
# Add a new profile
$ circleci signing-config profile add <signing-config-id> --profile ./MyAppExtension.mobileprovision
# Replace an existing profile (same bundle ID and profile type, regardless of file name)
$ circleci signing-config profile add <signing-config-id> --profile ./MyApp.mobileprovision
# Find the signing config ID first
$ circleci signing-config list --json --jq '.[].id'remove <signing-config-id> <profile-id> — Remove a provisioning profile from a signing config
EXAMPLES
# Remove a profile by ID
$ circleci signing-config profile remove <signing-config-id> <profile-id>
# Find the profile ID first
$ circleci signing-config list --json --jq '.[] | select(.id=="<signing-config-id>") | .provisioning_profiles'testresult <command> 🧪
Inspect test results for a job. Your tests flopped? This is where we go find out which one and why, bestie. 🫶
COMMANDS
get <job-id> <name> — Get a single test result by name
OPTIONS
--filter— Disambiguate byclassname=<value>when a name is shared; repeatable--jq— Process values from the response using jq syntax--json— Output as JSON--plain— Print only the raw test message, verbatim and unformatted
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 <job-id> TestLogin --filter classname=api
# Print only the raw test message
$ circleci testresult get <job-id> TestLogin --plain
# Output as JSON
$ circleci testresult get <job-id> TestLogin --jsonlist <job-id> — List test results for a job
OPTIONS
--all— Show all results (passing, failed and skipped), not just failures--filter— Filter bykey=value; repeatable. Keys:result(success|failure|skipped, exact),nameandclassname(case-insensitive substring). Same key repeated is OR, different keys AND. Cannot combineresult=with--all--jq— Process values from the response using jq syntax--json— Output as JSON--limit— Maximum number of results to show (0= no limit)--sort— Sort byname,classname,resultorrun_time
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 <job-id> --all
# Show skipped tests instead
$ circleci testresult list <job-id> --filter result=skipped
# Failed tests in one suite, slowest last
$ circleci testresult list <job-id> --filter classname=api --sort run_time
# Count failed tests by aggregating the JSONL stream with jq
$ circleci testresult list <job-id> --json --jq '[.,inputs] | length'Ok important vibe check 💅 — the default is failures only. Andresult=and--allare beefing; you genuinely cannot use them together. Pick a lane, girlie.
testsuite 🧚
Extension (circleci-testsuite)
version ⭐
Print version information
OPTIONS
--json— output as JSON (fields:version,commit,modified,latest,outdated,upgrade_command)
EXAMPLES
# Print version and commit hash
$ circleci version
# Print as JSON
$ circleci version --json
# Extract just the commit hash
$ circleci version --json | jq -r .commit
# Check whether a newer release is available
$ circleci version --json | jq .outdatedworkflow <command> 🔥
Inspect, rerun and cancel workflows (job graphs). The whole little pipeline ecosystem, under your thumb. Main character energy fr fr.
COMMANDS
cancel <workflow-id> — Cancel a running workflow
OPTIONS
-f,--force— skip confirmation prompt
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 --forceget <workflow-id> — Get workflow details
OPTIONS
--jq— Process values from the response using jq syntax--json— Output as JSON
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"list [<run-id>] — List workflows for a run or recent runs
OPTIONS
-b,--branch— Filter by branch (recent-runs mode)--jq— Process values from the response using jq syntax--json— Output as JSON--limit— Number of recent runs to show (recent-runs mode)--project— Project slug (e.g.gh/org/repo); defaults to git remote
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--json— output it as JSON instead, king behaviour
EL EXAMPLES ✨
$ circleci workflow list 9e0c9d52-3b7e-4cd6-b5f7-bfc5e4a07e81and if you want the raw JSON tea instead of the pretty table:
# Output as JSON
$ circleci workflow list --json👀 open <workflow-id>
Open workflow in browser. that's it, that's the whole job — it literally just yeets you straight to the workflow page in your default browser so you don't have to go digging through the UI like a peasant 🫶
EXAMPLES
# Open workflow details
$ circleci workflow open 5034460f-c7c4-4c43-9457-de07e2029e7b🔁 rerun <workflow-id>
Rerun a workflow. your build broke, your vibe is shattered, the pipeline said no — so you run it again. main character energy, periodt 💅
OPTIONS
--from-failed— rerun only the failed jobs, not the whole thing. lowkey the most useful flag here ngl--json— output as JSON
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-failedokay but how do you even find a workflow ID 😭 the pipeline keeps printing them but you never wrote them down. bestie, it's fine — grab it out of the latest run:
# Find a workflow ID from the latest run
$ circleci run get --json --jq '.workflows[].id'and the combo move, the iconic one-two punch — rerun just the failed bits and capture the brand-new workflow's ID so you can stalk it:
# Rerun and capture the new workflow's ID
$ circleci workflow rerun <workflow-id> --from-failed --json --jq .workflow_id⭐ real talk bestie:--json+--jqis the ship that never sinks. pipe it, script it, put it in CI, live your truth. iykyk 💜
and that's a wrap on the whole page, babe 🎀 this gorgeous thing came from the circleci tool itself, version/date stamped 2026-10-27 in the footer, and it's formatted as CIRCLECI(1) because of course it is. go forth and make your pipelines immaculate 💖✨🌸
📦 where this page comes from
- nixpkgs unstable: circleci-cli 1.11.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms