---
name: teamcity-cli
version: 1.3.0
description: Use when working with TeamCity CI/CD or when a user provides a TeamCity build URL — drives the `teamcity` CLI for builds, logs, jobs, queues, agents, pools, projects, and pipelines.
---

# TeamCity CLI (`teamcity`)

## Quick Start

```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** — 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.
- **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

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](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 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](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

`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.