teamcity-cli

TeamCity CLI（teamcity）

快速开始

teamcity auth status                    # Check authentication
teamcity run list --status failure      # Find failed builds
teamcity run log <id> --failed --raw    # Full failure diagnostics

不要猜测标志或语法。请使用命令参考或 teamcity <command> --help。构建称为运行（teamcity run）；构建配置称为作业（teamcity job）。切勿使用 --count——请使用 --limit（或 -n）。

注意事项

• 复合构建的日志为空——请深入查看子构建，找出实际故障。
• 构建链自底向上失败——最深处的失败依赖项是根本原因。请使用 teamcity run tree <id>。
• --local-changes 不包含 Kotlin DSL——运行前请先推送 .teamcity/ 更改。
• 使用 TEAMCITY_URL 为每条命令选择服务器——TEAMCITY_URL=https://cli.teamcity.com teamcity run list 会使用该服务器已存储的凭据；设置 TEAMCITY_TOKEN 可覆盖这些凭据。
• 只读模式会阻止远程 Shell——TEAMCITY_RO=1 或按服务器设置的 ro: true 会在连接前拒绝 agent exec 和 agent term。
• 多根运行：重复指定 --revision ROOT=SHA[@BRANCH]；ROOT=@BRANCH 使用已获取的分支头。单独指定 SHA 会固定每个根。
• 日志：使用 --raw 并将输出写入临时文件。构建：启动构建时使用 --watch。
• VCS 触发器不一定会配置好——推送修复后，可能需要手动启动构建。
• pipeline push 不会执行验证——请务必先运行 teamcity pipeline validate。
• **GitHub VCS 根目录：请使用 GitHub App 连接。**切勿通过 --auth password 粘贴 PAT。请参阅工作流。

核心命令

跨源下载会丢弃请求标头；HTTPS 降级和跨源终端重定向都会被拒绝。

区域	命令
身份验证	auth login、logout、status
构建	run list、view、start、watch、log、cancel、restart、tests、changes、tree
构件	run artifacts、run download
元数据	run pin/unpin、run tag/untag、run comment
作业	job list、view、create、tree、pause/resume、step list/view/add/delete、param list/get/set/delete、settings list/get/set
项目	project list、view、create、tree、param、token put/get、settings export/status/enable
VCS/连接	project vcs list/view/create/delete、project connection list/create/authorize/delete
队列	queue list、approve、remove、top
Agent	agent list、view、enable/disable、authorize/deauthorize、exec、term、reboot、move
池	pool list、view、link/unlink
服务器	server plugin upload（可选使用 --hot-reload）
流水线	pipeline list、view、create、validate、pull、push、schema、delete
API	teamcity api <endpoint>——原始 REST 访问
关联	teamcity link——通过 teamcity.toml 绑定仓库

快速工作流

Artifact 下载始终位于 --output 目录内：拒绝指向目录外的符号链接，传输失败时保留现有文件。

每项工作流的完整详情请参阅 工作流。

• 调查失败原因：run list --status failure → run log <id> --failed --raw → run tests <id> --failed
• 调试构建链：run tree <id> → 深入查看失败的最深层子项
• 修复并验证：编辑 → 推送 → run start --watch（个人构建请使用 --local-changes）
• 流水线生命周期：pipeline pull <id> → 编辑 → pipeline validate → pipeline push <id>；使用 pipeline schema 获取包含服务端已启用运行器和功能的完整架构
• GitHub VCS：connection create github-app → connection authorize → 在仓库中安装 App → vcs create --auth token --connection-id <id>
• Docker registry：echo $TOKEN | connection create docker -p <id> --name X --url https://ghcr.io --username U --stdin

参考资料

• 命令参考 — 所有命令和标志
• 工作流 — 失败调查、构建链、连接、流水线
• 输出格式 — JSON、纯文本、脚本编写

project settings status 会报告服务端的运行时消息和缺失的 DSL 上下文参数。其 “Recorded” 时间戳表示状态记录的时间，而非最近一次成功同步的时间。