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-changes excludes Kotlin DSL — push .teamcity/ changes before running.
• Select a server per command with TEAMCITY_URL — TEAMCITY_URL=https://cli.teamcity.com teamcity run list uses stored credentials for that server; set TEAMCITY_TOKEN to override them.
• Read-only mode blocks remote shells — TEAMCITY_RO=1 or per-server ro: true rejects agent exec and agent term before connecting.
• Multi-root runs: repeat --revision ROOT=SHA[@BRANCH]; ROOT=@BRANCH uses a fetched branch head. Bare SHA pins every root.
• 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.

Core Commands

Cross-origin downloads drop request headers; HTTPS downgrades and cross-origin terminal redirects are rejected.

Quick Workflows

Artifact downloads stay within --output: escaping directory symlinks are rejected, and failed transfers preserve existing files.

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-changes for personal builds)
• Pipeline lifecycle: pipeline pull <id> → edit → pipeline validate → pipeline push <id>, pipeline schema to get the complete schema with enabled runners and features 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

project settings status reports the server’s runtime message and missing DSL context parameters. Its “Recorded” timestamp is when the status was recorded, not the last successful sync.