By name: teamcity-cli
version: 1.0.0
description: Use when working with TeamCity CI/CD or when a user provides a TeamCity build URL — drives the teamcity CLI for builds, logs, jobs, queues, agents, pools, projects, and pipelines.
TeamCity CLI (teamcity)
Quick Start
teamcity auth status # Check authentication
teamcity run list --status failure # Find failed builds
teamcity run log <id> --failed --raw # Full failure diagnostics
Do not guess flags or syntax. Use the command reference or teamcity <command> --help. Builds are runs (teamcity run); build configurations are jobs (teamcity job). Never use --count — use --limit (or -n).
Gotchas
- Composite builds have empty logs — drill into child builds for the actual failure.
- Build chains fail bottom-up — deepest failed dependency is the root cause. Use
teamcity run tree <id>. --local-changesexcludes Kotlin DSL — push.teamcity/changes before running.TEAMCITY_URLalone bypasses stored auth — set bothTEAMCITY_URLandTEAMCITY_TOKEN, or leave unset.- Logs: use
--rawand dump to a temp file. Builds: use--watchwhen starting them. - VCS triggers aren't always wired up — after pushing a fix you may need to start builds manually.
pipeline pushdoes not validate — alwaysteamcity pipeline validatefirst.- GitHub VCS roots: use a GitHub App connection. Never paste a PAT via
--auth password. See workflows.
Core Commands
| Area | Commands |
|---|---|
| Auth | auth login, logout, status |
| Builds | run list, view, start, watch, log, cancel, restart, tests, changes, tree |
| Artifacts | run artifacts, run download |
| Metadata | run pin/unpin, run tag/untag, run comment |
| Jobs | job list, view, create, tree, pause/resume, step list/view/add/delete, param list/get/set/delete, settings list/get/set |
| Projects | project list, view, create, tree, param, token put/get, settings export/status |
| VCS/Conn | project vcs list/view/create/delete, project connection list/create/authorize/delete |
| Queue | queue list, approve, remove, top |
| Agents | agent list, view, enable/disable, authorize/deauthorize, exec, term, reboot, move |
| Pools | pool list, view, link/unlink |
| Pipelines | pipeline list, view, create, validate, pull, push, schema, delete |
| API | teamcity api <endpoint> — raw REST access |
| Link | teamcity link — bind repo via teamcity.toml |
Quick Workflows
See Workflows for full details on each.
- Investigate failure:
run list --status failure→run log <id> --failed --raw→run tests <id> --failed - Debug build chain:
run tree <id>→ drill to deepest failed child - Fix and verify: edit → push →
run start --watch(use--local-changesfor personal builds) - Pipeline lifecycle:
pipeline pull <id>→ edit →pipeline validate→pipeline push <id>,pipeline schemato get the actual schema from the server - GitHub VCS:
connection create github-app→connection authorize→ install App on repo →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
References
- Command reference — all commands and flags
- Workflows — failure investigation, build chains, connections, pipelines
- Output formats — JSON, plain text, scripting