teamcity-cli

# TeamCity CLI (`teamcity`) ```bash 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** — 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](references/workflows.md) 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](references/commands.md) — all commands and flags - [Workflows](references/workflows.md) — failure investigation, build chains, fix workflows, monitoring, flaky tests, pipelines - [Output Formats](references/output.md) — JSON, plain text, scripting