入门指南 本指南将带您了解如何安装 TeamCity CLI、与 TeamCity 服务器进行身份验证并运行您的第一个命令。
安装 TeamCity CLI 前提条件 TeamCity CLI 需要连接到正在运行的 TeamCity 服务器（版本 2020.1 或更高）。 部分功能可能需要更新版本的 TeamCity（例如 2024.04 或更高）。 无需额外运行时依赖项 —— CLI 作为独立二进制文件分发。
安装 Homebrew（推荐）：
brew install jetbrains/utils/teamcity
更新到最新版本：
brew upgrade teamcity
安装脚本：
curl -fsSL https://jb.gg/tc/install | bash
脚本会自动检测操作系统和架构，并将 teamCity 二进制文件安装到 PATH 所在目录。
安装脚本（所有发行版）：
curl -fsSL https://jb.gg/tc/install | bash
脚本会自动检测操作系统和架构，并将 teamCity 二进制文件安装到 PATH 所在目录。
按发行版分的软件包：
curl -fsSLO https://github.com/JetBrains/teamcity-cli/releases/latest/download/teamcity_linux_amd64.deb
sudo dpkg -i teamcity_linux_amd64.deb
sudo rpm -i https://github.com/JetBrains/teamcity-cli/releases/latest/download/teamcity_linux_amd64.rpm
curl -fsSLO https://github.com/JetBrains/teamcity-cli/releases/latest/download/teamcity_linux_amd64.pkg.tar.zst
sudo pacman -U teamcity_linux_amd64.pkg.tar.zst
Winget（推荐）：
winget install JetBrains.TeamCityCLI
PowerShell（安装脚本）：
irm https://jb.gg/tc/install.ps1 | iex
CMD（安装脚本）：
curl -fsSL https://jb.gg/tc/install.cmd -o install.cmd && install.cmd && del install.cmd
Chocolatey：
choco install teamcitycli
Scoop：
scoop bucket add jetbrains https://github.com/JetBrains/scoop-utils
scoop install teamcity
npm（跨平台）：
npm install -g @jetbrains/teamcity-cli
从源代码构建（高级） Go 安装：
go install github.com/JetBrains/teamcity-cli/tc@latest
克隆并构建：
git clone https://github.com/JetBrains/teamcity-cli.git
cd teamcity-cli
go build -o teamcity ./tc
验证安装 安装完成后，验证 CLI 是否可用：
teamcity --version
与服务器进行身份验证 运行登录命令：
teamcity auth login
在提示时输入服务器 URL。 如果服务器（TeamCity 2026.1 及更新版本）启用了基于浏览器的登录（PKCE），CLI 会自动打开浏览器以批准访问。 否则（TeamCity 服务器早于 2026.1），需要在 TeamCity 用户个人资料页手动生成新的访问令牌。
验证登录：
teamcity auth status
Token 在可用时存储于系统密钥环（macOS 钥匙串、GNOME Keyring 或 Windows 凭据管理器）。
如果偏好使用访问令牌登录，请运行 teamcity auth login --no-browser。 如果已有令牌，请使用 teamcity auth login --server https://teamcity.example.com --token <token>。
访客访问 如果服务器启用了访客访问，可无需令牌登录：
teamcity auth login --guest
访客访问为服务器提供只读权限。
了解术语 TeamCity CLI 为 TeamCity 概念使用更短名称。 了解这些映射有助于您操作命令。
运行 一次构建执行。 等同于 TeamCity web 接口上的 构建 。 运行 ID 是数字型。
teamcity run list
工作 构建配置——定义如何运行构建的指令设置。 作业 ID 类似于 MyProject_Build。
teamcity job list
Project（项目） 作业的集合。 项目可以嵌套以形成层次结构。 项目 ID 类似于 MyProject。
teamcity project list
层次结构如下： Project（项目） 包含 作业 ，每个作业产生 运行 ，每次运行在 代理 上执行。
列出最近的构建
teamcity run list
添加筛选器以缩小结果范围：
# Builds from a specific job
teamcity run list --job MyProject_Build
# Only failures from the last 24 hours
teamcity run list --status failure --since 24h
# Builds on a specific branch
teamcity run list --branch main --limit 10
查找作业 ID 许多命令需要作业 ID。 使用 teamcity job list 浏览可用作业：
# List all jobs
teamcity job list
# Filter by project
teamcity job list --project MyProject
启动构建 通过指定作业 ID 触发新构建：
teamcity run start MyProject_Build
添加 --watch 以实时跟踪构建进度：
teamcity run start MyProject_Build --branch main --watch
--watch 标志会显示一个实时进度视图，直到构建结束。
视图构建日志 视图特定构建的日志输出：
teamcity run log 12345
或获取作业的最新日志：
teamcity run log --job MyProject_Build
调查故障 当构建失败时，使用此流程快速定位根本原因：
查找失败的构建：
teamcity run list --status failure
视图故障诊断（问题、带完整堆栈跟踪的失败测试）：
teamcity run log 12345 --failed
排查单个测试故障：
teamcity run tests 12345 --failed
检查构建队列 查看哪些构建正在等待运行：
teamcity queue list
视图构建代理 列出所有已注册构建代理及其状态：
teamcity agent list
筛选器仅显示已连接代理：
teamcity agent list --connected
在浏览器中打开 大部分视图命令支持 --web 标志，可在浏览器中打开相应页面：
teamcity run view 12345 --web
teamcity job view MyProject_Build --web
teamcity project view MyProject --web
后续步骤 shell 补全 为 Bash、Zsh、Fish 或 PowerShell 设置选项卡补全——详见 配置 。
身份验证 详细了解 身份验证方法 ，包括多服务器设置及 CI/CD 用法。
运行管理 深入了解 构建管理 ——如工件、个人构建、置顶、标签等。
别名 为常用命令设置 自定义快捷键 。
脚本 为脚本及自动化配置 JSON 输出 。
命令参考 浏览完整的 命令参考 ，查看所有可用命令和参数。
2026年 8月 6日
