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](references/commands.md) 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-changes excludes Kotlin DSL — push .teamcity/ changes before running.
• TEAMCITYURL alone bypasses stored auth — set both TEAMCITYURL and TEAMCITY_TOKEN, or leave unset.
• Logs: use --raw and dump to a temp file. Builds: use --watch when starting them.
• VCS triggers aren't always wired up — after pushing a fix you may need to start builds manually.
• pipeline push does not validate — always teamcity pipeline validate first.
• GitHub VCS roots: use a GitHub App connection. Never paste a PAT via --auth password. See [workflows](references/workflows.md).

Core Commands

Quick Workflows

See [Workflows](references/workflows.md) 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-changes for personal builds)
• Pipeline lifecycle: pipeline pull <id> → edit → pipeline validate → pipeline push <id>, pipeline schema to 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](references/commands.md) — all commands and flags
• [Workflows](references/workflows.md) — failure investigation, build chains, connections, pipelines
• [Output formats](references/output.md) — JSON, plain text, scripting