脚本和自动化

TeamCity CLI 提供多种输出格式和功能，专为脚本、自动化和 CI/CD 集成设计。

JSON 输出

许多命令支持 --json 标志以获得机器可读输出。列表命令也支持可选字段选择功能。

基本用法

teamcity run list --json
teamcity job list --json
teamcity project list --json

   

发现可用字段

传递 --json= （值为空）即可查看某命令的所有可用字段：

teamcity run list --json=

选择特定字段

指定以逗号分隔的字段列表：

teamcity run list --json=id,status,webUrl

字段选择（--json=... ）仅适用于列表命令。视图和检查命令支持 --json ，但不支持字段选择。

嵌套字段

使用点号表示法访问嵌套字段：

teamcity run list --json=id,status,buildType.name,triggered.user.username

用于视图和检查命令的 JSON

teamcity run view 12345 --json
teamcity run log 12345 --json
teamcity run log 12345 --json --failed
teamcity run changes 12345 --json
teamcity run tests 12345 --json
teamcity run artifacts 12345 --json
teamcity agent view Agent-Linux-01 --json
teamcity project settings status MyProject --json
teamcity auth status --json

   

按命令分类的可用字段

命令	示例字段
`teamcity run list`	`iD`， `number`， `状态`， `state`， `branchName`， `buildTypeId`， `buildType.name`， `buildType.projectName`， `triggered.type`， `triggered.user.name`， `agent.name`， `startDate`， `finishDate`， `webUrl`
`teamcity job list`	`iD`， `名称`， `projectName`， `项目 ID`， `paused`， `href`， `webUrl`
`teamcity project list`	`iD`， `名称`， `描述`， `parentProjectId`， `href`， `webUrl`
`teamcity queue list`	`iD`， `buildTypeId`， `state`， `branchName`， `queuedDate`， `buildType.name`， `triggered.user.name`， `webUrl`
`teamcity agent list`	`iD`， `名称`， `connected`， `已启用`， `authorized`， `pool.name`， `webUrl`
`teamcity pool list`	`iD`， `名称`， `maxAgents`

纯文本输出

使用 --plain 可生成便于标准 Unix 工具解析的以选项卡分隔的输出。该标志适用于所有列表命令以及 agent jobs 和 param list：

teamcity run list --plain
teamcity agent list --plain
teamcity agent jobs 1 --plain
teamcity project param list MyProject --plain

  

可省略页眉以便于管道处理：

teamcity run list --plain --no-header
teamcity agent list --plain --no-header | awk '{print $1}'

脚本示例

获取失败构建的 ID

teamcity run list --status failure --json=id | jq -r '.[].id'

导出构建数据到 CSV

teamcity run list --json=id,status,branchName | jq -r '.[] | [.id,.status,.branchName] | @csv'

   

获取队列中构建的 web URL

teamcity queue list --json=webUrl | jq -r '.[].webUrl'

按状态统计构建数量

teamcity run list --since 24h --json=status | jq 'group_by(.status) | map({status: .[0].status, count: length})'

   

等待构建完成

teamcity run start MyProject_Build --watch --json

或单独启动和监视：

BUILD_ID=$(teamcity run start MyProject_Build --json | jq -r '.id')
teamcity run watch "$BUILD_ID" --json

取消某作业所有队列中的构建

teamcity queue list --job MyProject_Build --json=id | jq -r '.[].id' | xargs -I {} teamcity run cancel {} --yes

   

CI/CD 集成

环境变量认证

在 CI/CD 流水线中，可使用环境变量进行认证：

export TEAMCITY_URL="https://teamcity.example.com"
export TEAMCITY_TOKEN="your-access-token"

PowerShell：

$env:TEAMCITY_URL = "https://teamcity.example.com"
$env:TEAMCITY_TOKEN = "your-access-token"

CMD：

set TEAMCITY_URL=https://teamcity.example.com
set TEAMCITY_TOKEN=your-access-token

参见 Authentication 以获取详细信息。

非交互式模式

在自动化环境下使用 --no-input 可禁用交互式提示。当提示被禁用时，CLI 使用合理的默认值：

teamcity run cancel 12345 --no-input

或者在支持的命令上使用 --yes：

teamcity queue remove 12345 --yes

只读模式

设置 TEAMCITY_RO=1 ，可阻止所有写入操作。在该模式下，会在请求发送前拒绝所有可能修改数据的命令（如触发构建、取消、固定、修改参数等）：

export TEAMCITY_RO=1
teamcity run list              # works — read-only
teamcity run start MyBuild     # blocked — would trigger a build

   

此功能适用于监控仪表板、报表脚本以及需要防止意外更改的共享环境。该标志也会阻止通过 teamcity api 使用非 GET 方法的写入操作。

有关可接受值，请参见配置。

静默模式

使用 --quiet 可抑制非必要输出：

teamcity run start MyProject_Build --quiet

退出码

大多数命令在成功时返回退出码 0 ，失败时返回 1。 teamcity run watch 流程（包括 teamcity run start --watch ）返回：

运行被取消时，返回 2
超时时，返回 124

teamcity run start MyProject_Build --watch --quiet --timeout 30m
case $? in
  0) echo "Build succeeded" ;;
  1) echo "Build failed" ;;
  2) echo "Build cancelled" ;;
  124) echo "Timed out" ;;
  *) echo "Unknown error" ;;
esac

   

结构化错误

当 --json 激活且命令失败时，错误会以结构化 JSON 格式写入 stderr，而不是纯文本形式：

{
  "error": {
    "code": "auth_expired",
    "message": "Authentication failed: invalid or expired token",
    "suggestion": "teamcity auth login"
  }
}

  

错误代码：

代码	含义
`auth_expired`	令牌无效或已过期
`permission_denied`	权限不足
`not_found`	请求的资源不存在
`network_error`	无法连接到服务器
`read_only`	写入操作被 `TEAMCITY_RO` 阻止
`validation_error`	输入无效（标志、实参）
`internal_error`	意外错误

当没有可操作修复时， suggestion 字段将被省略。 code 字段始终存在，可安全用于程序匹配。

JSON 兼容性策略

--json 输出为机器可读协议。适用下列规则：

禁止移除或重命名字段。，未在上一版本给予弃用期。
始终允许添加字段。—— 新密钥可出现在任意版本中。
错误代码保持稳定。—— 现有代码不会改变含义。
信封结构是固定的。—— 成功输出为资源数据，错误输出使用 {"error": {...}} 框架返回到 stderr。

建议消费端忽略未知字段，并避免依赖字段顺序。

原始 API 访问

对于未由专用命令覆盖的操作，可使用 teamcity api 直接发起 REST API 请求：

teamcity api '/app/rest/server'
teamcity api '/app/rest/builds' --paginate --slurp

参见 REST API access 以获取详细信息。

2026年 9月 11日