Terminal
Terminal/Skill
Terminal commands for CircleCI: validate config, watch runs, read job logs and failed tests, and rerun or cancel.
By CircleCI
Works with
npx skills add circleci-public/skills --skill circleci-cliThe everyday loop: change config → commit/push → watch the run → read failures → rerun.
Almost every command infers the project from the current git remote and the branch from
your checked-out branch, so from inside a repo you rarely pass --project/--branch.
Every data-returning command takes --json, and --jq '<expr>' filters it without a
separate jq; human output is markdown. Without a terminal the CLI skips the pager, drops
color, and fails fast naming the missing flag instead of prompting (for example
--value is required in non-interactive mode.), so there is nothing to set up defensively.
Run circleci version, then circleci auth me. It reads $CIRCLE_TOKEN (which wins over
a stored token) and confirms which user it resolves to, so it doubles as the auth check. It
fails with No CircleCI API token found when there is no usable token.
To sign in, run circleci auth login. Don't ask the user for an API token: the OAuth
flow needs no secret from them, and pasting tokens into a chat is worse for them than a
browser round-trip. Without a terminal it opens the authorize page in the user's browser,
prints the same URL to stderr, then blocks for up to 5 minutes waiting for approval:
circleci auth me.--no-browser prints the URL without opening anything. CI and CIRCLE_NO_INTERACTIVE
also suppress the browser, since there is no one there to use it; set CIRCLE_TOKEN in
those environments instead.
circleci config validate # lint .circleci/config.yml (default path); use -c <path> or - for stdin
circleci config process .circleci/config.yml # expand orbs/params → the final compiled config
circleci config process .circleci/config.yml --pipeline-parameters params.yml # process with pipeline params
validate --org gh/<org> is needed to resolve private orbs.-n/--next previews upcoming (potentially breaking) config changes.circleci config generate [path] (won't overwrite).Handy git hook — block a push when the config is invalid (.git/hooks/pre-push):
#!/bin/sh
circleci config validate || { echo "Fix .circleci/config.yml before pushing"; exit 1; }
git push # your trigger fires a run
circleci run watch # watch the latest run on the current branch; blocks to completion
circleci run watch --sha "$(git rev-parse HEAD)" # match the run for THIS commit (polls up to 2m for it to appear)
circleci run watch --failfast # bail the moment any job fails
run watch exit codes make it scriptable: 0 all workflows passed · 1 something
failed · 6 cancelled · 7 config rejected · 8 timed out (--timeout, default
30m). Chain it: git push && circleci run watch --sha "$(git rev-parse HEAD)".
circleci run list # recent runs for this project (--limit, -b <branch>, -B current branch)
circleci run get # latest run on current branch: workflows → jobs, with status
circleci run get <run-id> # a specific run
circleci my runs # YOUR recent runs across every project you can access
circleci run open # open the current branch's run in the browser
run get shows the run → workflow → job tree. Add --json to pull IDs for drilling in
(workflows[].id, workflows[].jobs[].id) — those UUIDs feed the commands below.
circleci run get --json --jq '.workflows[].jobs[] | select(.current_outcome=="failed") | {name,id}' # failing jobs + UUIDs
circleci job output list <job-id> # per-step logs (rendered; --tail N, default last 200 lines/step)
circleci job output get <job-id> --step-num <N> # full output of one step (--execution <i> for parallel runs)
circleci job get <job-id> # job metadata (status, timing, parallelism)
circleci testresult list <job-id> # FAILED tests only by default (--all, --filter result=…, --sort, --limit)
circleci job artifact <job-id> # list artifacts; -o <dir> to download them
Parallel jobs: job output list --execution <index> targets one shard.
circleci workflow rerun <workflow-id> # rerun the whole workflow from scratch
circleci workflow rerun <workflow-id> --from-failed # rerun only the failed jobs (workflow IDs come from `run get`)
circleci run cancel <run-number-or-id> # stop a run (-f to skip the prompt)
circleci run trigger # manually trigger a run (current project/branch)
circleci run trigger -b <branch> --parameter deploy=true --parameter tier=2 # trigger with params (repeatable)
circleci workflow cancel <workflow-id> # cancel a single workflow
To debug interactively (SSH into a job), rerun with SSH from the web app — there is no
CLI flag for it; circleci run open gets you there fast.
| You want to know… | Command |
|---|---|
| Did my push build? Which run? | circleci run watch --sha "$(git rev-parse HEAD)" / circleci run list -B |
| Overall status of the latest run | circleci run get |
| Which workflow/job failed | circleci run get --json --jq '.workflows[].jobs[] | select(.current_outcome=="failed")' |
| Why a step failed (logs) | circleci job output list <job-id> → job output get <job-id> --step-num N |
| Which tests failed | circleci testresult list <job-id> |
| Build outputs / reports | circleci job artifact <job-id> -o ./artifacts |
| Config problem before pushing | circleci config validate / circleci config process |
| Config error in the UI vs local | validate with --org to match private-orb resolution |
| Everything I triggered lately | circleci my runs |
| Open it in the browser | circleci run open, circleci workflow open, circleci job open |
| Env var names on the project | circleci envvar list |
| Contexts in the org, and their secrets | circleci context list, circleci context secret list <context> |
| Pipeline definitions, and their triggers | circleci pipeline list, then circleci project trigger list --pipeline-definition-id <id> |
| Anything not listed here | references/api-coverage.md maps each v3 endpoint to its command |
| CircleCI feature/config syntax question | use the circleci-config skill / docs MCP rather than guessing |
cd into the
repo. Override with --project gh/<org>/<repo> and -b <branch> when outside it (note:
run get/run open default the branch to main when --project is set, not your checkout).run watch --sha polls up to 2 minutes for the run to appear — expected right after a push.run get --json /
workflow get), not the job number.run cancel takes a run number or UUID; pass --project when cancelling by number.circleci api <path> resolves relative to /api/v3; a path starting with api is sent as
given. Reach for it only when no command covers what you need:
references/api-coverage.md says which endpoints have one.
{project-id} and {org-id} in the path are filled in from the git remote.run list, run get). circleci pipeline
manages pipeline definitions, the config and checkout sources a run executes, so
pipeline list is not where runs live.run trigger (this skill: fire a run on the inferred project/branch) with
pipeline run --definition-id … (definition-targeted; see the onboarding skill).job output/testresult — a green status alone doesn't prove the
step did what you intended.run get/list, job output,
testresult, job artifact) before rerun/trigger/cancel, and confirm the
organization/project scope before mutating pipeline state.op read/stdin — never pass them as command-line args (they leak into shell history and logs).circleci help first; if a subcommand isn't
listed, don't use it. There is no top-level trigger: firing a run is run trigger, and
project trigger manages the triggers attached to a definition. On older builds that lack
api, read cloud job logs from the CircleCI app/UI or connected CircleCI MCP tooling.circleci auth login, refresh permissions in User Settings) rather than retrying blindly.When you finish, summarize: