用途：通过 teamcity 命令行操作 TeamCity CI/CD，覆盖构建（run）、构建配置（job）、项目、队列、代理、池、流水线及原始 REST API 访问。
主要能力：认证（auth login/logout/status）；构建的 list、view、start、watch、log、cancel、restart、tests、changes、tree；产物 artifacts 与 download；pin/tag/comment 元数据；job 的查看、创建、步骤与参数、设置；project 的查看、创建、参数、token、设置导出；VCS 与连接管理；queue 的 list/approve/remove/top；agent 的启用、授权、exec、term、reboot、move；pool 链接；server plugin upload；pipeline 的 list/view/create/validate/pull/push/schema/delete；teamcity api 直接访问 REST；teamcity link 通过 teamcity.toml 绑定仓库。
必要用法：先 teamcity auth status 检查认证；用 teamcity run list --status failure 找失败构建，teamcity run log <id> --failed --raw 获取完整失败诊断。构建用 run，构建配置用 job；不要用 --count，改用 --limit 或 -n。可用 TEAMCITY_URL 按命令选择服务器，TEAMCITY_TOKEN 覆盖凭据；TEAMCITY_RO=1 或每服务器 ro: true 启用只读模式，会在连接前拒绝 agent exec 与 agent term。多根构建重复 --revision ROOT=SHA[@BRANCH]。日志建议 --raw 输出到临时文件；启动构建用 --watch。pipeline push 不校验，应先 teamcity pipeline validate。GitHub VCS 根使用 GitHub App 连接，不要用 --auth password 粘贴 PAT。
适用场景：失败排查（run list → run log → run tests）、构建链调试（run tree 定位最深失败子构建）、修复验证（编辑→推送→run start --watch，个人构建用 --local-changes）、流水线生命周期（pull→编辑→validate→push）、GitHub VCS 与 Docker registry 连接配置。
限制与注意：复合构建日志为空，需下钻子构建；构建链自底向上失败，最深失败依赖才是根因；--local-changes 不包含 Kotlin DSL，需先推送 .teamcity/ 变更；VCS 触发器不一定配置，推送修复后可能需手动启动构建；跨源下载会丢弃请求头，HTTPS 降级与跨源终端重定向被拒绝；产物下载限制在 --output 内，逃逸目录的符号链接被拒绝，失败传输保留原文件；project settings status 的 Recorded 时间是状态记录时间，非上次成功同步时间。具体命令与参数以命令参考或 teamcity <command> --help 为准。