TeamCity CLI (teamcity)

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 — the deepest failed dependency is the root cause, not the top-level build. Use teamcity run tree <id>.
• --local-changes excludes Kotlin DSL — push .teamcity/ changes before running.
• TEAMCITY_URL alone bypasses stored auth — for env override mode set both TEAMCITY_URL and TEAMCITY_TOKEN; otherwise leave TEAMCITY_URL unset to use auth login credentials.
• Always use --raw for logs and dump to a temp file. Always use --watch when starting builds.
• VCS triggers aren't always configured — after pushing a fix, you may need to start builds manually.
• pipeline push does not validate — always run teamcity pipeline validate first.

Core Commands

Area	Commands
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, tree, pause/resume, param list/get/set/delete
Projects	project list, view, tree, param, token put/get, settings export/status/validate
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, delete
API	teamcity api <endpoint> — raw REST API access

Quick Workflows

See Workflows for full details on each.

Investigate failure: teamcity run list --status failure → teamcity run log <id> --failed --raw → teamcity run tests <id> --failed Debug build chain: teamcity run tree <run-id> → find deepest failed child → investigate that build Fix build failure: diagnose → classify → fix (code: --local-changes, DSL: settings validate, pipeline: pipeline validate) → push Monitor until green: start → watch → fix if failed → push → watch new build → repeat (max 3 attempts) Pipeline: teamcity pipeline create <name> -p <project> / teamcity pipeline validate [file] / teamcity pipeline pull <pipeline-id> → edit → teamcity pipeline push <pipeline-id> [file] Project VCS root details: teamcity project vcs list --project <project-id> → teamcity project vcs view <vcs-root-id> (do not guess VCS root IDs)

References

• Command Reference — all commands and flags
• Workflows — failure investigation, build chains, fix workflows, monitoring, flaky tests, pipelines
• Output Formats — JSON, plain text, scripting