argos-cli

Argos CLI

运行 argos <command> --help 查看任意命令的准确标志。本技能仅涵盖 --help 无法说明的内容：令牌模型、输出约定和命令索引。

输出约定（Agent）

• 解析标准输出时，始终传入 --json；否则命令会输出便于阅读的文本。
• 错误通过标准错误以 Error: <message> 的形式输出。退出码 0 = 成功，1 = 失败。
• 切勿输出令牌值。

身份验证

<buildReference> 是构建编号（例如 72652）或完整的构建 URL。使用编号时，请添加 --project owner/project；URL 中已包含项目信息。<changeId> 不是构建引用：它来自 diff 的 change.id，且不包含账号信息，因此每个 change 命令都需要 --project owner/project（或 ARGOS_PROJECT）。<testId> 来自 diff 的 test.id，包含项目名称但不包含账号信息，因此 test 命令需要相同的 --project/ARGOS_PROJECT 参数；使用项目令牌时除外，因为项目令牌已标识其所属项目。project 和 automation 命令使用相同的 --project owner/project；account 命令使用 --account <slug>（或 ARGOS_ACCOUNT）。

两种令牌类型——按命令选择：

命令	令牌	解析顺序
build get、build snapshots、test list、test get、test changes、change list、project get、project deployments、project domain get、media get、media list、media versions、media update、media delete	项目令牌	--token › ARGOS_TOKEN
review *、comment *、test comment *、media comment *、test subscribe / unsubscribe、build subscribe / unsubscribe、change ignore / unignore、account *、project update、project transfer、project contributor *、project domain set、automation *、analytics、create-project	个人访问令牌（PAT）	--token › ARGOS_TOKEN › argos login
upload、finalize、skip、deploy、media upload	CI / 项目令牌	--token › ARGOS_TOKEN（或无令牌 CI）

项目令牌可以读取构建数据，但不能审核、评论、忽略变更，也不能管理项目或团队——这些操作需要 PAT。如果没有可用的合适令牌，请询问用户。对于这些操作，如果不存在 PAT，请报告结论和证据，而不要执行操作。argos login 面向需要交互操作的人员，不适用于 CI。

命令

• 检查 — build get <ref> · build snapshots <ref> [--needs-review] [--metrics-period 24h|3d|7d|30d|90d] · build subscribe|unsubscribe <ref>
• 评审 — review list <ref> · review create <ref> --event <approve|reject|comment> [--body <md>] · review dismiss <ref> <reviewId> · review reviewer list <ref> · review reviewer add|remove <ref> <userId...>
• 评论 — comment list <ref> · comment create <ref> --body <md> [--reply-to <id>] [--diff <id>] [--draft] · comment get|edit|delete|resolve|unresolve|subscribe|unsubscribe <ref> <id> · comment react|unreact <ref> <id> <emoji>
• 不稳定性 — test list [--build-name <name>] [--search <q>] · test get <testId> · test changes <testId> [--ignored true|false] [--metrics-period …] · test subscribe|unsubscribe <testId> · change list · change ignore|unignore <changeId> --project owner/project
• 测试评论 — test comment list|create <testId> · test comment get|edit|delete|resolve|unresolve|subscribe|unsubscribe <testId> <id> · test comment react|unreact <testId> <id> <emoji>
• 项目 — project get · project update [--name …] [--summary-check …] [--default-user-level …] [--ignore-changes true|false] [--deployments true|false] … · project transfer --to <slug> · project contributor list|set|remove · project deployments [--environment preview|production] · project domain get|set <domain>
• 自动化 — automation list [--active true|false] · automation get <ruleId> · automation create|update [<ruleId>] --definition-file <path> · automation deactivate <ruleId>
• 团队 — account get · account update --default-user-level <member|contributor> · account member list|set-level|remove · account invite list|create|cancel|reset-link · account domain list|add|remove
• 账户 — analytics --account <slug> · create-project <name> --account <slug> · whoami
• 媒体 — media upload <files...> [--branch <b> | --pr <n>] [--state before|after] [--description <text>] [--visibility team|public] [--no-compress] · media list [--branch <b>] [--pr <n>] [--stage staged|published] [--search <q>] [--type image|video] · media get|delete|versions <mediaId> · media update <mediaId> [--name <n>] [--description <text>] [--branch <b>]
• 媒体评论 — media comment list <mediaId> [--all]（默认显示未关闭的讨论串） · media comment create <mediaId> · media comment get|edit|delete|resolve|unresolve|subscribe|unsubscribe <mediaId> <id> · media comment react|unreact <mediaId> <id> <emoji>
• CI — upload <dir> · finalize · skip · deploy <dir>
• 身份验证 — login · logout

列表命令（test list、change list、account member list、project contributor list、project deployments、automation list、account invite list）会按分页获取结果，直至达到 --limit（默认值为 100）。

build snapshots --json 会为每个差异补充 test.metrics（不稳定性： stability、consistency、flakiness，取值均为 0–1）；若存在变更，还会补充 change （id、ignored、occurrences）。较高的 occurrences 或 flakiness 表明该变更值得忽略；将其 change.id 传给 change ignore。

常见流程

审查一次构建（使用项目令牌检查，使用 PAT 做出决定）：

ARGOS_TOKEN=<project-token> argos build snapshots <ref> --needs-review --json
argos review create <ref> --token <pat> --event approve --json
# regression: argos review create <ref> --token <pat> --event reject --body "..."

忽略不稳定的更改（使用项目令牌检查，使用 PAT 忽略）。 被忽略的更改不再需要审查，并会在后续构建中自动获批：

ARGOS_TOKEN=<project-token> argos build snapshots <ref> --json   # read each diff's change.id + occurrences
argos change ignore <changeId> --token <pat> --project owner/project
# revert: argos change unignore <changeId> --token <pat> --project owner/project

处理项目中的不稳定性积压。test list 会返回项目中仍在运行的测试，并按不稳定程度从高到低排序，因此第一页就是需要稳定下来的测试；change list 用于审查已忽略的更改：

ARGOS_TOKEN=<project-token> argos test list --project owner/project --json --limit 20
ARGOS_TOKEN=<project-token> argos change list --project owner/project --json   # already ignored

在决定修复还是忽略不稳定测试之前，先对其进行诊断。test get 会报告测试的不稳定程度；test changes 会按出现频率从高到低列出不同的更改，每项都包含可供查看的差异、基线和最新版本图像 URL：

ARGOS_TOKEN=<project-token> argos test get <testId> --json          # flakiness, stability, consistency, series
ARGOS_TOKEN=<project-token> argos test changes <testId> --json      # occurrences + diff/base/head URLs per change
# a change with occurrences > 1 that nothing in the UI explains is flaky:
argos change ignore <changeId> --token <pat> --project owner/project

在 CI 中上传屏幕截图：

argos upload ./screenshots --token $ARGOS_TOKEN

并行构建：

argos upload ./screenshots --parallel-nonce $ID --parallel-index $i --parallel-total $n
argos finalize --parallel-nonce $ID

将某人添加到团队和项目中。团队角色来自 account，每个项目的访问权限则来自 project contributor——所有者和成员本来就能访问每个项目，因此只有贡献者需要授权：

argos account invite create [email protected] --account acme --level contributor --json
argos account member list --account acme --search dev --json          # read back user.id once they accept
argos project contributor set <userId> --level reviewer --project acme/web --json

配置项目。project update 只会更改传入的设置，并会打印更新后的项目信息，供你检查最终配置：

argos project get --project acme/web --json
argos project update --project acme/web --summary-check auto --ignore-changes true --auto-ignore-after 3 --json

在构建上请求审查，然后查看还有谁需要处理：

argos review reviewer add <ref> <userId> --token <pat> --project acme/web
argos review reviewer list <ref> --token <pat> --project acme/web --json