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.- 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]
References
- Command Reference — all commands and flags
- Workflows — failure investigation, build chains, fix workflows, monitoring, flaky tests, pipelines
- Output Formats — JSON, plain text, scripting
1---2name: teamcity-cli-23description: Use when working with TeamCity CI/CD or when user provides a TeamCity build URL. Use `teamcity` CLI for builds, logs, jobs, queues, agents, and pipelines.4---56# TeamCity CLI (`teamcity`)78```bash9teamcity auth status # Check authentication10teamcity run list --status failure # Find failed builds11teamcity run log <id> --failed --raw # Full failure diagnostics12```1314**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`).1516## Gotchas1718- **Composite builds have empty logs** — drill into child builds for the actual failure.19- **Build chains fail bottom-up** — the deepest failed dependency is the root cause, not the top-level build. Use `teamcity run tree <id>`.20- **`--local-changes` excludes Kotlin DSL** — push `.teamcity/` changes before running.21- **Always use `--raw` for logs** and dump to a temp file. Always use `--watch` when starting builds.22- **VCS triggers aren't always configured** — after pushing a fix, you may need to start builds manually.23- **`pipeline push` does not validate** — always run `teamcity pipeline validate` first.2425## Core Commands2627| Area | Commands |28|-----------|---------------------------------------------------------------------------------------------------|29| Builds | `run list`, `view`, `start`, `watch`, `log`, `cancel`, `restart`, `tests`, `changes`, `tree` |30| Artifacts | `run artifacts`, `run download` |31| Metadata | `run pin/unpin`, `run tag/untag`, `run comment` |32| Jobs | `job list`, `view`, `tree`, `pause/resume`, `param list/get/set/delete` |33| Projects | `project list`, `view`, `tree`, `param`, `token put/get`, `settings export/status/validate` |34| Queue | `queue list`, `approve`, `remove`, `top` |35| Agents | `agent list`, `view`, `enable/disable`, `authorize/deauthorize`, `exec`, `term`, `reboot`, `move` |36| Pools | `pool list`, `view`, `link/unlink` |37| Pipelines | `pipeline list`, `view`, `create`, `validate`, `pull`, `push`, `delete` |38| API | `teamcity api <endpoint>` — raw REST API access |3940## Quick Workflows4142See [Workflows](references/workflows.md) for full details on each.4344**Investigate failure:** `teamcity run list --status failure` → `teamcity run log <id> --failed --raw` → `teamcity run tests <id> --failed`45**Debug build chain:** `teamcity run tree <run-id>` → find deepest failed child → investigate that build46**Fix build failure:** diagnose → classify → fix (code: `--local-changes`, DSL: `settings validate`, pipeline: `pipeline validate`) → push47**Monitor until green:** start → watch → fix if failed → push → watch new build → repeat (max 3 attempts)48**Pipeline:** `teamcity pipeline create <name> -p <project>` / `teamcity pipeline validate [file]` / `teamcity pipeline pull <pipeline-id>` → edit → `teamcity pipeline push <pipeline-id> [file]`4950## References5152- [Command Reference](references/commands.md) — all commands and flags53- [Workflows](references/workflows.md) — failure investigation, build chains, fix workflows, monitoring, flaky tests, pipelines54- [Output Formats](references/output.md) — JSON, plain text, scripting
jetbrains