teamcity-cli

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.

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/enable
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
Server	server plugin upload (optionally with --hot-reload)
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

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.