配置

本页介绍 配置 命令、配置文件格式、环境变量和 TeamCity CLI 的 shell 补全设置。

使用 `teamcity config` 管理配置

配置 命令可用于查看和修改 CLI 设置，无需直接编辑 YAML 文件。

列出所有设置

teamcity config list
teamcity config list --json

获取设置

teamcity config get default_server
teamcity config get ro --server tc.example.com

设置设置

# Switch default server
teamcity config set default_server tc.example.com

# Enable read-only mode for a specific server
teamcity config set ro true --server tc.example.com

# Enable guest auth for the default server
teamcity config set guest true

   

可用密钥

密钥	作用域	描述
`default_server`	全局	默认 TeamCity 服务器 URL。
`guest`	按服务器	启用访客认证（无需令牌）。使用 `--server` 以指定服务器为目标。
`ro`	按服务器	启用只读模式（阻止所有写入操作）。使用 `--server` 以指定服务器为目标。
`token_expiry`	按服务器	令牌过期时间戳（RFC 3339）。通常由 `auth login` 设置。
`analytics`	全局	启用或禁用匿名用法统计。默认值： `true`。设置为 `false` 以选择退出。

认证字段（token、 user ）由 teamcity auth login/teamcity auth logout 管理，无法通过 config set 设置。

配置文件

TeamCity CLI 将其配置存储在 ~/.config/tc/config.yml 的 YAML 文件中。当你运行 teamcity auth login 时，此文件会自动创建。

一个典型的配置文件如下所示：

default_server: https://teamcity.example.com
servers:
  https://teamcity.example.com:
    user: alice
  https://teamcity-staging.example.com:
    user: alice
    guest: true
  https://teamcity-prod.example.com:
    user: alice
    ro: true
aliases:
  rl: 'run list'
  rw: 'run view $1 --web'
  mine: 'run list --user=@me'

  

配置字段

字段	描述
`default_server`	当未设置 `TEAMCITY_URL` 环境变量时使用的服务器 URL。当你运行 `teamcity auth login` 时会自动更新。
`服务器`	服务器 URL 到其设置的映射。每个条目会保存 `user` 字段（该服务器上的用户名），并可选包含 `guest: true` 用于访客访问， `ro: true` 用于只读模式。令牌存储在系统密钥环中，而不是此文件中，除非登录时使用了 `--insecure-storage`。
`aliases`	别名名称到其扩展的映射。参见 Aliases 以获取详细信息。

环境变量

环境变量会重写配置文件设置，推荐在 CI/CD 流水线中用来配置 CLI。

变量	描述
`TEAMCITY_URL`	TeamCity 服务器 URL。在配置文件中优先于 `default_server`。
`TEAMCITY_TOKEN`	用于认证的访问令牌。优先于密钥环和配置文件中的令牌。
`TEAMCITY_GUEST`	设置为 `1` 即可使用访客认证（只读，无需令牌）。 CLI 必须能解析服务器 URL（通过 `TEAMCITY_URL` 、DSL 检测或配置文件）。
`TEAMCITY_RO`	设置为 `1`、 `true` 或 `yes` 可启用只读模式。启用后，所有非 GET API 请求（POST、PUT、DELETE）将被阻止，防止任何对 TeamCity 服务器的修改。适用于监控脚本和仪表板。也可通过 `ro: true` 在配置文件内为每个服务器单独设置。
`TEAMCITY_DSL_DIR`	Kotlin DSL 目录路径。会重写自动检测 `.teamcity/` 或 `.tc/` 目录。
`NO_COLOR`	禁用彩色输出。遵循 NO_COLOR 标准。
`TEAMCITY_NO_COLOR`	用于禁用彩色输出的应用专用替代方案 `NO_COLOR`。
`TEAMCITY_NO_UPDATE`	设置为 `1`、 `true` 或 `yes` 即可禁用自动更新检查。在 CI 环境和非交互式终端中也会自动禁用更新检查。
`TEAMCITY_HEADER_*`	为每个外部请求添加一个 HTTP 页眉。后缀会变为以连接符分隔、规范大小写的页眉名称： `TEAMCITY_HEADER_FOO_BAR=baz` 发送 `Foo-Bar: baz`。空值会被忽略；包含 CR/LF/NUL 的值会被舍弃，以防止页眉注入。页眉值会在 `--verbose` 输出中被隐藏。
`DO_NOT_TRACK`	设置为 `1`、 `true`、 `yes` 或 `on` 可禁用匿名用法统计。遵循行业约定。优先于 `TEAMCITY_ANALYTICS` 与配置文件。
`TEAMCITY_ANALYTICS`	设置为 `0`、 `false`、 `no` 或 `off` 可仅对该 CLI 禁用匿名用法统计。优先于配置文件。

示例：

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

设置 TERM=dumb 也会禁用彩色输出。当输出不是终端时（例如管道到其他命令），会自动禁用彩色。

额外 HTTP 页眉（企业代理）

如果你的 TeamCity 服务器位于 Cloudflare Access 或 Google IAP 等需认证代理之后，该代理在每次请求时都需要凭据。 TEAMCITY_HEADER_* 可让你通过环境变量提供凭据，无需编辑配置文件。 CLI 会在每次 API 调用、认证登录探测、PKCE 交换和代理终端 WebSocket 时应用这些凭据——任何可能通过代理的请求都会用到。

页眉名称遵循以下规则：

后缀在前缀之后变为大写；下划线变为连字符；结果保持规范大小写。
TEAMCITY_HEADER_CF_ACCESS_CLIENT_ID=value → Cf-Access-Client-Id: value。
空值会被跳过。值中包含 CR/LF/NUL 会被舍弃。
无论页眉名称如何，值都会在 --verbose 输出中被隐藏。

Cloudflare Access 服务令牌

export TEAMCITY_HEADER_CF_ACCESS_CLIENT_ID="abc123.access"
export TEAMCITY_HEADER_CF_ACCESS_CLIENT_SECRET="$(cat ~/.cf-access-secret)"
teamcity run list

    

Google IAP

IAP 需要由你的服务账号签名的新 ID 令牌。一个小型包装器可保持令牌为最新：

teamcity-iap() {
  export TEAMCITY_HEADER_PROXY_AUTHORIZATION="Bearer $(gcloud auth print-identity-token --audiences=$IAP_AUDIENCE)"
  teamcity "$@"
}

teamcity-iap run list

    

对于仓库范围的配置，可在 direnv.envrc 中设置，以便仅在你 cd 进入项目目录时生效。

全局标志

以下标志在每个命令中均可用：

标志	描述
`-h`， `--帮助`	显示该命令的帮助。
`-v`， `--version`	显示 CLI 版本。
`--no-color`	禁用彩色输出。
`-q`， `--quiet`	隐藏非必要的输出。与 `--verbose` 互斥。
`--verbose`	显示详细输出，包括调试信息。与 `--quiet` 互斥。
`--no-input`	禁用交互式提示。当本应出现提示时，CLI 会采用合理默认值。

shell 补全

TeamCity CLI 支持 Bash、Zsh、Fish 和 PowerShell 的选项卡补全。补全内容包含命令、子命令、标志，某些情况下还包括项目和作业 ID 等值。

teamcity completion bash > /etc/bash_completion.d/teamcity

如果没有 /etc/bash_completion.d/ 的写入权限，请写入用户级路径，并从 .bashrc 引用：

teamcity completion bash > ~/.teamcity-completion.bash
echo 'source ~/.teamcity-completion.bash' >> ~/.bashrc

teamcity completion zsh > "${fpath[1]}/_teamcity"

请确保你的 ~/.zshrc 包含 compinit：

autoload -Uz compinit && compinit

teamcity completion fish > ~/.config/fish/completions/teamcity.fish

teamcity completion powershell > teamcity.ps1
. ./teamcity.ps1

如需自动加载补全，把输出添加到 PowerShell 配置文件。

2026年 8月 6日

配置

使用 teamcity config 管理配置