circleci-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CircleCI day-to-day developer workflow (CLI)

CircleCI 开发者日常工作流（CLI）

The 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.

日常循环：修改 config → commit/push → 观察 run → 查看失败 → rerun。几乎每个命令都会根据当前 git remote 推断 project，并根据当前 checkout 的分支推断 branch，因此进入 repo 后，通常很少需要传入

--project

--branch

。

每个返回数据的命令都接受

--json

，而

--jq '<expr>'

可直接过滤结果，无需另行使用

jq

；人类可读输出为 markdown。没有终端时，CLI 会跳过 pager、去除颜色，并在发现缺少 flag 时立即失败并指出具体 flag，而不是进行提示（例如

--value is required in non-interactive mode.

），因此不需要额外进行防御性设置。

Preflight and signing in

预检与登录

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:

Run it in the background, or with a timeout well above your default, not in a foreground call that gives up after a minute or two.
Tell the user to approve the request in their browser, and pass along the printed URL in case the window never came to the front. They are watching you, not your tool output.
Once they have approved, confirm with
```
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 version

，然后运行

circleci auth me

。它会读取

$CIRCLE_TOKEN

（其优先级高于已存储的 token），并确认该 token 对应哪个用户，因此也可作为 auth 检查。找不到可用 token 时，会报出

No CircleCI API token found

。

要登录，请运行

circleci auth login

。不要向用户索要 API token：OAuth flow 不需要用户提供任何 secret；在聊天中粘贴 token 反而比通过浏览器完成一次授权更不安全。没有终端时，它会在用户浏览器中打开授权页面，将同一 URL 打印到 stderr，然后最多阻塞 5 分钟等待批准：

在后台运行它，或设置远高于默认值的 timeout；不要放在默认一两分钟后放弃的前台调用中。
告知用户在浏览器中批准请求，并转发打印出的 URL，以防窗口未自动置前。用户关注的是你的说明，而不是工具输出。
用户批准后，运行
```
circleci auth me
```
进行确认。

--no-browser

会打印 URL，但不会打开任何内容。

CI

和

CIRCLE_NO_INTERACTIVE

也会禁止自动打开浏览器，因为此时没有人能够完成授权；应改为在这些环境中设置

CIRCLE_TOKEN

。

1. Before you commit — validate locally (fast feedback)

1. 提交前——在本地验证（快速反馈）

bash

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.
Scaffold a starter config for a new repo:
```
circleci config generate [path]
```
(won't overwrite).

Handy git hook — block a push when the config is invalid (

.git/hooks/pre-push

bash

#!/bin/sh
circleci config validate || { echo "Fix .circleci/config.yml before pushing"; exit 1; }

bash

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

解析 private orbs 时需要使用
```
validate --org gh/<org>
```
。
```
-n/--next
```
可预览即将推出（可能破坏兼容性）的 config 变更。
为新 repo 生成 starter config：
```
circleci config generate [path]
```
（不会覆盖已有文件）。

实用的 git hook——当 config 无效时阻止 push（

.git/hooks/pre-push

）：

bash

#!/bin/sh
circleci config validate || { echo "Fix .circleci/config.yml before pushing"; exit 1; }

2. Commit, push, and watch the run it triggers

2. Commit、push，并观察其触发的 run

bash

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)"

bash

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 可用于脚本化：0 所有 workflow 通过 · 1 有任务失败 · 6 已取消 · 7 config 被拒绝 · 8 超时（

--timeout

，默认 30 分钟）。可以串联执行：

git push && circleci run watch --sha "$(git rev-parse HEAD)"

。

3. Review your pipelines / runs

3. 审查 pipeline / run

bash

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.

bash

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

会显示 run → workflow → job 树。添加

--json

可提取用于继续下钻的 IDs（

workflows[].id

、

workflows[].jobs[].id

）——这些 UUID 可用于以下命令。

4. Drill into a failure

4. 深入排查失败

bash

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.

bash

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

对于并行 job：

job output list --execution <index>

可定位到某个 shard。

5. Act on a run

5. 对 run 执行操作

bash

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.

bash

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

如需以交互方式调试（通过 SSH 进入 job），请从 Web 应用中带 SSH 重跑——CLI 没有对应 flag；

circleci run open

可以快速进入该页面。

Troubleshooting — where to get each piece of information

故障排除——从哪里获取各类信息

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

你想了解什么……	命令
我的 push 是否触发了 build？对应哪个 run？	`circleci run watch --sha "$(git rev-parse HEAD)"` / `circleci run list -B`
最近一次 run 的整体状态	`circleci run get`
哪个 workflow/job 失败了	`circleci run get --json --jq '.workflows[].jobs[] \| select(.current_outcome=="failed")'`
某一步为何失败（日志）	`circleci job output list <job-id>` → `job output get <job-id> --step-num N`
哪些测试失败	`circleci testresult list <job-id>`
构建产物/报告	`circleci job artifact <job-id> -o ./artifacts`
push 前的 config 问题	`circleci config validate` / `circleci config process`
UI 中与本地出现的 config 错误	使用 `--org` 进行验证，以匹配 private-orb 的解析方式
我最近触发的一切	`circleci my runs`
在浏览器中打开	`circleci run open` 、 `circleci workflow open` 、 `circleci job open`
项目中的 env var 名称	`circleci envvar list`
组织中的 contexts 及其 secrets	`circleci context list` 、 `circleci context secret list <context>`
Pipeline definitions 及其 triggers	`circleci pipeline list` ，然后运行 `circleci project trigger list --pipeline-definition-id <id>`
这里未列出的内容	`references/api-coverage.md` 将每个 v3 endpoint 映射到对应命令
CircleCI feature/config 语法问题	使用 circleci-config skill / docs MCP，不要猜测

Gotchas

常见陷阱

Commands default to the git remote's project and your current branch —
```
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.
Logs, tests, and artifacts key off the job UUID (from
```
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.
One execution of a pipeline is a run (
```
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.
Don't confuse
```
run trigger
```
(this skill: fire a run on the inferred project/branch) with
```
pipeline run --definition-id …
```
(definition-targeted; see the onboarding skill).
Verify a real run +
```
job output
```
/
```
testresult
```
— a green status alone doesn't prove the step did what you intended.

命令默认使用 git remote 的 project 和当前 branch——请先
```
cd
```
进入 repo。在 repo 外时，使用
```
--project gh/<org>/<repo>
```
和
```
-b <branch>
```
覆盖默认值（注意：设置
```
--project
```
后，
```
run get
```
/
```
run open
```
的默认 branch 是
```
main
```
，而不是 checkout 的分支）。
```
run watch --sha
```
最多会轮询 2 分钟以等待 run 出现——push 后立即出现属于正常现象。
日志、测试和 artifacts 都以 job UUID 为键（来自
```
run get --json
```
/
```
workflow get
```
），而不是 job 编号。
```
run cancel
```
接受 run number 或 UUID；按 number 取消时需传入
```
--project
```
。
```
circleci api <path>
```
会相对于
```
/api/v3
```
解析；以
```
api
```
开头的 path 会按原样发送。仅当没有命令覆盖所需功能时才使用它：
```
references/api-coverage.md
```
会说明哪些 endpoints 有对应命令。path 中的
```
{project-id}
```
和
```
{org-id}
```
会根据 git remote 自动填充。
pipeline 的一次执行是 run（
```
run list
```
、
```
run get
```
）。
```
circleci pipeline
```
管理的是 pipeline definitions，即 run 执行时使用的 config 和 checkout sources，因此 run 不在
```
pipeline list
```
中。
不要混淆
```
run trigger
```
（本 skill：在推断出的 project/branch 上触发 run）与
```
pipeline run --definition-id …
```
（面向 definition；参见 onboarding skill）。
验证真实 run 以及
```
job output
```
/
```
testresult
```
——仅凭绿色状态无法证明该步骤确实执行了你预期的操作。

Guardrails

防护准则

Read before you mutate. Prefer read-only commands (
```
run get
```
/
```
list
```
,
```
job output
```
,
```
testresult
```
,
```
job artifact
```
) before
```
rerun
```
/
```
trigger
```
/
```
cancel
```
, and confirm the organization/project scope before mutating pipeline state.
Never print raw secret values from environment variables or tokens. Pipe secrets from
```
op read
```
/stdin — never pass them as command-line args (they leak into shell history and logs).
Don't invent commands. Verify with
```
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.
If auth/permissions fail, report the exact scope gap and safest remediation (
```
circleci auth login
```
, refresh permissions in User Settings) rather than retrying blindly.

先读取，再修改。 在
```
rerun
```
/
```
trigger
```
/
```
cancel
```
前，优先使用只读命令（
```
run get
```
/
```
list
```
、
```
job output
```
、
```
testresult
```
、
```
job artifact
```
），并在修改 pipeline 状态前确认 organization/project 范围。
绝不打印环境变量或 token 中的原始 secret 值。 通过
```
op read
```
/stdin 传入 secrets——绝不要将其作为命令行参数传递（否则会泄露到 shell history 和 logs 中）。
不要臆造命令。 先用
```
circleci help
```
验证；如果没有列出某个 subcommand，就不要使用。不存在顶层
```
trigger
```
：触发 run 的命令是
```
run trigger
```
，而
```
project trigger
```
管理附加到 definition 上的 triggers。在缺少
```
api
```
的旧版本中，应从 CircleCI app/UI 或已连接的 CircleCI MCP tooling 读取 cloud job logs。
如果 auth/permissions 失败，应报告具体的权限范围缺口和最安全的修复方式（
```
circleci auth login
```
、在 User Settings 中刷新权限），不要盲目重试。

Telling CircleCI when the CLI falls short

何时向 CircleCI 反馈 CLI 的不足

circleci feedback

sends a report to the team that builds the CLI. Send one when the CLI itself got in the way of the task:

An error that looks like CircleCI's fault: a 5xx, or anything the CLI follows with
```
If this looks like a CircleCI problem, report it: circleci feedback …
```
.
A missing capability: no command covers what you needed, even after checking
```
circleci help
```
and
```
references/api-coverage.md
```
.
Confusing output: you misread it, or it contradicted what you found elsewhere.

bash

circleci feedback "run get --json listed no jobs for a run the web app shows with three" --tool "run get"

Say what you were trying to do, what you ran and what happened, quoted as one argument.
```
--tool
```
names the command it's about.
The report carries the user's CircleCI identity, so describe the CLI's behavior in your own words and keep secrets, env var values and log excerpts out of it.
Problems in the user's config or code, or a missing token or permission, belong to the user, not in a report.
Send one report per problem, then carry on with the task. If
```
feedback
```
fails, or
```
circleci help
```
doesn't list it, move on without it.

circleci feedback

会向负责构建 CLI 的团队发送报告。当 CLI 本身妨碍任务完成时发送报告：

看起来是 CircleCI 自身问题的错误：5xx，或 CLI 在其后提示
```
If this looks like a CircleCI problem, report it: circleci feedback …
```
的任何错误。
缺少能力：即使检查了
```
circleci help
```
和
```
references/api-coverage.md
```
，仍没有命令覆盖所需功能。
输出令人困惑：你无法解读，或它与其他位置发现的信息相矛盾。

bash

circleci feedback "run get --json listed no jobs for a run the web app shows with three" --tool "run get"

说明你尝试做什么、运行了什么以及发生了什么，并将其作为单个加引号的参数传入。
```
--tool
```
指定相关命令。
报告会携带用户的 CircleCI identity，因此请用自己的话描述 CLI 行为，并且不要在报告中包含 secrets、env var 值和 log excerpts。
用户 config 或代码中的问题，以及缺少 token 或权限，属于用户侧问题，不应提交报告。
每个问题发送一份报告，然后继续任务。如果
```
feedback
```
调用失败，或
```
circleci help
```
未列出该命令，则跳过并继续。

Report back

汇报结果

When you finish, summarize:

Commands run and their purpose.
Key outputs — pipeline/workflow/job ids, status, failing step.
Actions taken (rerun/trigger/validate) and why.
Remaining blockers and the next recommended CLI command.
Any feedback you sent to CircleCI, and what it said.

完成后，请总结：

执行过的命令及其目的。
关键输出——pipeline/workflow/job IDs、状态、失败步骤。
已执行的操作（rerun/trigger/validate）及其原因。
剩余阻塞项以及建议的下一条 CLI 命令。
发送给 CircleCI 的任何反馈及其回复。