circleci-cli

CircleCI 日常开发工作流（CLI）

日常循环：修改配置 → 提交/推送 → 观察运行 → 查看失败 → 重新运行。 几乎所有命令都会根据当前 git 远程仓库推断项目，并根据已检出的分支推断分支，因此在仓库内通常无需传入 --project/--branch。

每个返回数据的命令都支持 --json，而 --jq '<expr>' 可以直接筛选结果，无需单独使用 jq；人类可读输出为 Markdown。没有终端时，CLI 会跳过分页器、关闭颜色，并快速失败，指出缺少的标志，而不是发起提示（例如 --value is required in non-interactive mode.），因此无需提前进行任何防护性设置。

预检和登录

运行 circleci version，然后运行 circleci auth me。它会读取 $CIRCLE_TOKEN（其优先级高于已存储的令牌），并确认解析出的用户，因此也可用于检查身份验证。如果没有可用令牌，则会失败并显示 No CircleCI API token found。

要登录，请运行 circleci auth login。不要向用户索要 API 令牌：OAuth 流程无需用户提供任何密钥，而将令牌粘贴到聊天中对他们来说比通过浏览器完成授权更不安全。没有终端时，它会在用户的浏览器中打开授权页面，将相同的 URL 输出到 stderr，然后最多阻塞 5 分钟，等待用户批准：

• 在后台运行，或设置远高于默认值的超时时间，不要在前台调用中运行，以免一两分钟后就放弃。
• 告知用户在浏览器中批准请求，并将输出的 URL 告诉他们，以防窗口未能置于最前端。他们关注的是你，而不是你的工具输出。
• 用户批准后，运行 circleci auth me 确认。

--no-browser 会输出 URL，但不打开任何页面。CI 和 CIRCLE_NO_INTERACTIVE 也会抑制浏览器打开，因为此时没有人可以操作浏览器；在这些环境中，请改为设置 CIRCLE_TOKEN。

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

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> 是解析私有 Orb所必需的。
• -n/--next 可预览即将进行的配置更改（可能存在破坏性变更）。
• 为新仓库生成初始配置：circleci config generate [path]（不会覆盖已有文件）。

实用的 git 钩子 — 配置无效时阻止推送（.git/hooks/pre-push）：

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

2. 提交、推送并观察由此触发的运行

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 的退出代码便于编写脚本：0 所有工作流均通过 · 1 有失败项 · 6 已取消 · 7 配置被拒绝 · 8 已超时（--timeout，默认 30m）。可将其串联：git push && circleci run watch --sha "$(git rev-parse HEAD)"。

3. 查看流水线 / 运行

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 会显示运行 → 工作流 → 作业树。添加 --json 可提取 ID，供后续深入查看 （workflows[].id、workflows[].jobs[].id）——这些 UUID 可用于下面的命令。

4. 深入查看失败

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 output list --execution <index> 可指定一个分片。

5. 对运行执行操作

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 连接到作业），请在 Web 应用中选择通过 SSH 重新运行——CLI 没有对应标志；运行 circleci run open 即可快速跳转到相关页面。

故障排查 — 如何获取各项信息

你想了解……	命令
我的推送是否触发了构建？是哪次运行？	circleci run watch --sha "$(git rev-parse HEAD)" / circleci run list -B
最近一次运行的总体状态	circleci run get
哪个工作流/作业失败了	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
推送前检查配置问题	circleci config validate / circleci config process
UI 中的配置错误与本地结果不一致	使用 --org 进行验证，以匹配私有 orb 的解析方式
最近我触发的所有运行	circleci my runs
在浏览器中打开	circleci run open、circleci workflow open、circleci job open
项目中的环境变量名称	circleci envvar list
组织中的上下文及其密钥	circleci context list、circleci context secret list <context>
流水线定义及其触发器	circleci pipeline list，然后运行 circleci project trigger list --pipeline-definition-id <id>
这里未列出的内容	references/api-coverage.md 将每个 v3 端点映射到对应命令
CircleCI 功能/配置语法问题	使用 circleci-config 技能 / docs MCP，不要猜测

注意事项

• 命令默认使用 git 远程仓库对应的项目和当前分支 — 请先 cd 到仓库目录。在仓库外时，使用 --project gh/<org>/<repo> 和 -b <branch> 指定目标（注意：设置了 --project 时，run get/run open 默认使用 main 分支，而不是当前检出的分支）。
• run watch --sha 会轮询最多 2 分钟，等待运行出现 — 推送后立即使用时，这是预期行为。
• 日志、测试和构建产物均以作业 UUID 为依据（来自 run get --json / workflow get），而不是作业编号。
• run cancel 接受运行编号或 UUID；按编号取消时，请传入 --project。
• circleci api <path> 会将相对路径解析为 /api/v3 下的路径；如果路径以 api 开头，则会按原样发送。仅在没有对应命令时才使用它： references/api-coverage.md 列出了哪些端点有对应命令。 路径中的 {project-id} 和 {org-id} 会根据 git 远程仓库自动填入。
• 流水线的一次执行称为运行（run list、run get）。circleci pipeline 用于管理流水线定义，即运行所执行的配置和检出源，因此不能在 pipeline list 中查找运行。
• 不要混淆 run trigger（此技能：在推断出的项目/分支上触发运行）与 pipeline run --definition-id …（针对特定定义；请参阅入门技能）。
• 请验证实际运行以及 job output/testresult 的结果 — 仅凭绿色状态无法证明步骤执行符合预期。

安全准则

• 先读取，再修改。 优先使用只读命令（run get/list、job output、 testresult、job artifact），然后再使用 rerun/trigger/cancel；修改流水线状态前，先确认组织/项目范围。
• 绝不打印环境变量或令牌中的原始密钥值。 通过 op read/stdin 传递密钥 — 切勿将其作为命令行参数传入（否则会泄露到 shell 历史记录和日志中）。
• 不要臆造命令。 先用 circleci help 验证；如果其中未列出某个子命令，就不要使用。不存在顶层 trigger：触发运行的命令是 run trigger，而 project trigger 用于管理附加到某个定义的触发器。对于不支持 api 的旧版本，请从 CircleCI 应用/UI 或已连接的 CircleCI MCP 工具中读取云端作业日志。
• 如果身份验证/权限失败，请准确说明缺少的权限范围，并给出最安全的补救方法（circleci auth login、在 User Settings 中刷新权限），不要盲目重试。

在 CLI 力有未逮时向 CircleCI 反馈

circleci feedback 会向负责构建 CLI 的团队发送报告。如果 CLI 本身妨碍了任务，请发送报告：

• 看起来是 CircleCI 的错误：5xx 错误，或 CLI 后面附有 If this looks like a CircleCI problem, report it: circleci feedback … 的任何错误。
• 缺少功能：即使查看了 circleci help 和 references/api-coverage.md，仍然没有可满足需求的命令。
• 输出令人困惑：你误读了输出，或输出与在其他地方找到的信息相矛盾。

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

• 说明你想做什么、运行了什么以及发生了什么，并将这些内容作为一个参数引用。--tool 用于指定报告所针对的命令。
• 报告会包含用户的 CircleCI 身份，因此请用自己的话描述 CLI 的行为，并避免在报告中包含机密信息、环境变量值和日志摘录。
• 用户配置或代码的问题，以及缺少令牌或权限的问题，都由用户负责，不应写入报告。
• 每个问题发送一份报告，然后继续任务。如果 feedback 运行失败，或 circleci help 中未列出该命令，请跳过报告，继续处理。

汇报结果

完成后，请总结：

1. 运行过的命令及其用途。
2. 关键输出——pipeline、workflow 和 job 的 ID、状态以及失败的步骤。
3. 已采取的操作（rerun/trigger/validate）及其原因。
4. 尚未解决的阻碍，以及建议接下来运行的 CLI 命令。
5. 你向 CircleCI 发送的任何反馈及其内容。