# Command Reference

## Contents

- Authentication (`teamcity auth`)
- Builds/Runs (`teamcity run`)
- Jobs (`teamcity job`)
- Projects (`teamcity project`)
- Queue (`teamcity queue`)
- Agents (`teamcity agent`)
- Agent Pools (`teamcity pool`)
- Pipelines (`teamcity pipeline`)
- Server (`teamcity server`)
- Configuration (`teamcity config`)
- Direct API (`teamcity api`)
- Global Flags
- List Output Flags
- CLI Updates (`teamcity update`)

## CLI Updates (`teamcity update`)

- `teamcity update` checks the release feed and asks before installing.
- `--yes`, `-y` installs without prompting; required for non-interactive installation.
- `--check` or `--json` reports status without installing; neither combines with `--yes`.

## Authentication (`teamcity auth`)

| Command                        | Description                       |
|--------------------------------|-----------------------------------|
| `teamcity auth login -s <url>` | Authenticate with TeamCity server |
| `teamcity auth logout`         | Log out from current server       |
| `teamcity auth status`         | Show auth status and server info  |

Login options:
- `-s, --server <url>` - TeamCity server URL
- `-t, --token <token>` - Access token
- `--insecure-storage` - Store token in plain text config file instead of system keyring

Environment override note:
- `TEAMCITY_URL` + `TEAMCITY_TOKEN` should be set together when overriding auth in scripts
- `TEAMCITY_URL` alone bypasses stored `teamcity auth login` credentials
- `TEAMCITY_HEADER_*` adds an HTTP header to every request: `TEAMCITY_HEADER_FOO_BAR=baz` sends `Foo-Bar: baz`. Use this for proxies that gate access (Cloudflare Access, Google IAP). Values are redacted in `--verbose` output.
- Cross-origin redirects drop request headers and only permit body-free GET/HEAD requests. HTTPS downgrades and cross-origin terminal redirects are rejected.

## Builds/Runs (`teamcity run`)

| Command                          | Description              |
|----------------------------------|--------------------------|
| `teamcity run list`              | List recent builds       |
| `teamcity run view <id>`         | View build details       |
| `teamcity run start <job-id>`    | Start a new build        |
| `teamcity run cancel <id>`       | Cancel a build           |
| `teamcity run restart <id>`      | Restart a build          |
| `teamcity run watch <id>`        | Watch build in real-time |
| `teamcity run log <id>`          | View build log           |
| `teamcity run tests <id>`        | View test results        |
| `teamcity run changes <id>`      | View VCS changes         |
| `teamcity run artifacts <id>`    | List artifacts           |
| `teamcity run download <id>`     | Download artifacts       |
| `teamcity run pin <id>`          | Pin build                |
| `teamcity run unpin <id>`        | Unpin build              |
| `teamcity run tag <id> <tags>`   | Add tags                 |
| `teamcity run untag <id> <tags>` | Remove tags              |
| `teamcity run comment <id>`      | Manage comments          |
| `teamcity run tree <id>`        | Show snapshot dependency tree for a run |

### Flags for `teamcity run list`

Shows all branches and all build states (including canceled, personal, composite sub-builds) by default — matching the TeamCity UI. Use `--branch` to narrow to a specific branch, or `--branch @this` to use the current git branch.

- `-j, --job <id>` - Filter by job
- `-b, --branch <name>` - Filter by branch (`@this` = current git branch)
- `--status <status>` - Filter: success, failure, running, queued, error, unknown
- `-u, --user <name>` - Filter by user
- `-t, --tag <tag>` - Filter by tag (repeatable, matches runs with all given tags)
- `--favorites` - Show favorite builds for the current user
- `-p, --project <id>` - Filter by project
- `-n, --limit <n>` - Limit results (default: 30)
- `--since <time>` - Since time (e.g., 24h, 7d, 2w, 2026-01-01)
- `--until <time>` - Until time (e.g., 12h, 7d, 2026-01-02)
- `--json` - JSON output (use `--json=` to list fields, `--json=f1,f2` for specific)
- `--plain` - Plain text output for scripting
- `--no-header` - Omit header row (use with --plain)
- `-w, --web` - Open in browser

### Flags for `teamcity run start`

- `-b, --branch <name>` - Branch to build
- `--revision <sha>` - Pin every VCS root to one Git commit SHA (or local `@head`)
- `--revision ROOT=SHA[@BRANCH]` - Pin individual roots (repeatable); `ROOT=@BRANCH` uses the latest fetched branch head; cannot mix with a bare SHA
- `-P, --param <k=v>` - Build parameter (repeatable)
- `-S, --system <k=v>` - System property (repeatable)
- `-E, --env <k=v>` - Environment variable (repeatable)
- `-t, --tag <tag>` - Add tag (repeatable)
- `-m, --comment <text>` - Run comment
- `--watch` - Watch after starting
- `-i, --interval <s>` - Refresh interval in seconds when watching (default: 5)
- `--timeout <duration>` - Timeout when watching (e.g., 30m, 1h); implies --watch
- `--clean` - Clean checkout
- `--agent <id>` - Run on specific agent
- `--personal` - Run as personal build
- `-l, --local-changes` - Include local changes (git, -, or path)
- `--no-push` - Skip auto-push of branch to remote
- `--rebuild-deps` - Rebuild all dependencies
- `--rebuild-failed-deps` - Rebuild failed/incomplete dependencies
- `--reuse-deps <id,...>` - Reuse existing builds as snapshot dependencies (comma-separated IDs)
- `--top` - Add to top of queue
- `--settings <vcs|current>` - Versioned-settings source: `vcs` loads settings from VCS, `current` uses the settings on the server (default: the job's configured mode)
- `--dry-run` - Show what would be triggered without running
- `--json` - Output as JSON (for scripting)
- `-w, --web` - Open run in browser

### Flags for `teamcity run log`

- `--failed` - Show failure summary (problems and failed tests)
- `-j, --job <id>` - Get log for latest run of this job
- `-f, --follow` - Stream log output in real-time until build finishes
- `--tail <N>` - Show last N log messages
- `--raw` - Show raw log without formatting
- `--json` - Output as JSON
- `-w, --web` - Open build log in browser

### Flags for `teamcity run watch`

- `-i, --interval <s>` - Refresh interval in seconds
- `--logs` - Stream build logs while watching
- `--quiet` - Minimal output, show only state changes and result
- `--json` - Wait for completion and output result as JSON
- `--timeout <duration>` - Timeout duration (e.g., 30m, 1h)

### Flags for `teamcity run view`

- `--json` - Output as JSON
- `-w, --web` - Open in browser

### Flags for `teamcity run tests`

Without `--test`, shows one run's results (positional `id` or `--job` latest).
With `--test NAME`, follows that test across builds (history): `--job X --test NAME`
for a job's history, or `--test NAME` alone for server-wide. The history view shows
the name once as a header, one row per build, and a pass-rate footer.

- `--failed` - Show only failed tests, excluding muted failures
- `--muted` - Show only muted failed tests
- `-j, --job <id>` - Latest run of this job (or, with `--test`, that job's history)
- `--test <name>` - Follow one test across builds instead of a single run
- `--json` - Output as JSON
- `-n, --limit <n>` - Maximum number of tests to show

### Flags for `teamcity run changes`

- `--json` - Output as JSON
- `--no-files` - Hide file list, show commits only

### Flags for `teamcity run artifacts`

- `-j, --job <id>` - List artifacts from latest run of this job
- `-p, --path <subdir>` - Browse artifacts under this subdirectory
- `--json` - Output as JSON

### Flags for `teamcity run download`

Downloads confine writes to `--output`, replace destination file symlinks rather than following them, and preserve existing files on failed transfers.

- `-a, --artifact <pattern>` - Artifact name pattern to filter (matches full path and basename)
- `-p, --path <subdir>` - Download artifacts under this subdirectory
- `-o, --output <path>` - Local directory to save artifacts to

### Flags for `teamcity run cancel`

- `--comment <text>` - Comment for cancellation
- `-y, --yes` - Skip confirmation prompt

### Flags for `teamcity run restart`

- `--watch` - Watch the new run after restarting
- `-i, --interval <s>` - Refresh interval in seconds when watching (default: 5)
- `--timeout <duration>` - Timeout when watching (e.g., 30m, 1h); implies --watch
- `-w, --web` - Open run in browser

### Flags for `teamcity run pin`

- `-m, --comment <text>` - Comment explaining why the run is pinned

### Flags for `teamcity run comment`

- `--delete` - Delete the comment

### Flags for `teamcity run tree`

- `-d, --depth <n>` - Limit tree depth (0 = unlimited)
- `--json` - Output as JSON

## Jobs (`teamcity job`)

| Command                              | Description               |
|--------------------------------------|---------------------------|
| `teamcity job create <name>`               | Create a job                   |
| `teamcity job list`                        | List build configurations      |
| `teamcity job view <id>`                   | View job details               |
| `teamcity job tree <id>`                   | Show snapshot dependency tree  |
| `teamcity job pause <id>`                  | Pause job                      |
| `teamcity job resume <id>`                 | Resume job                     |
| `teamcity job param list <id>`             | List parameters                |
| `teamcity job param get <id> <name>`       | Get parameter                  |
| `teamcity job param set <id> <name> <val>` | Set parameter                  |
| `teamcity job param delete <id> <name>`    | Delete parameter               |
| `teamcity job step list <id>`              | List build steps               |
| `teamcity job step view <id> <step-id>`    | View build step details        |
| `teamcity job step add <id> --type <r>`    | Add a build step               |
| `teamcity job step delete <id> <step-id>`  | Delete a build step            |
| `teamcity job settings list <id>`             | List settings                  |
| `teamcity job settings get <id> <name>`       | Get a setting value            |
| `teamcity job settings set <id> <name> <val>` | Set a setting value            |

### Flags for `teamcity job create`

- `-p, --project <id>` - Parent project ID (or `TEAMCITY_PROJECT` / linked project)
- `--id <id>` - Explicit job ID (default: auto-generated from name)
- `--template <id>` - Create from an existing template ID
- `--json` - Output as JSON
- `-w, --web` - Open in browser after creation

### Flags for `teamcity job list`

- `--json` - JSON output (use `--json=` to list fields, `--json=f1,f2` for specific)
- `-n, --limit <n>` - Maximum number of jobs
- `-p, --project <id>` - Filter by project ID

### Flags for `teamcity job view`

- `--json` - Output as JSON
- `-w, --web` - Open in browser

### Flags for `teamcity job tree`

- `-d, --depth <n>` - Limit tree depth (0 = unlimited)
- `--only <type>` - Show only `dependents` or `dependencies`

### Flags for `teamcity job param list`

- `--json` - Output as JSON

### Flags for `teamcity job param set`

- `--secure` - Mark as secure/password parameter

### Flags for `teamcity job step add`

- `--type <runner-id>` - Runner type ID as used by the REST API: `simpleRunner` (Command Line), `gradle-runner` (Gradle), `Maven2` (Maven), ... (required). Find IDs via `teamcity job step view`.
- `--name <name>` - Step name
- `--param <key=value>` - Step parameter (repeatable)
- `--json` - Output as JSON

The `<id>` (job) positional is optional when the repo is linked; `delete` accepts `remove`/`rm` aliases.

## Projects (`teamcity project`)

| Command                                        | Description                  |
|------------------------------------------------|------------------------------|
| `teamcity project list`                        | List projects                |
| `teamcity project view <id>`                   | View project details         |
| `teamcity project create <name>`               | Create a project             |
| `teamcity project tree [id]`                   | Show project hierarchy tree  |
| `teamcity project vcs list --project <id>`     | List VCS roots               |
| `teamcity project vcs view <id>`              | View VCS root details        |
| `teamcity project vcs create --project <id>`  | Create a VCS root; `--json` returns the created object |
| `teamcity project vcs delete <id>`            | Delete a VCS root            |
| `teamcity project connection list -p <id>`    | List project connections     |
| `teamcity project connection create github-app -p <id>` | Register GitHub App (manifest flow) |
| `teamcity project connection create docker -p <id>`    | Register Docker registry credentials |
| `teamcity project connection authorize <conn-id> -p <id>` | Per-user OAuth dance for an OAuth connection |
| `teamcity project connection delete <conn-id> -p <id>` | Delete a connection         |
| `teamcity project param list <id>`             | List parameters              |
| `teamcity project param get <id> <name>`       | Get parameter                |
| `teamcity project param set <id> <name> <val>` | Set parameter                |
| `teamcity project param delete <id> <name>`    | Delete parameter             |
| `teamcity project token put <id>`              | Store secret, get token      |
| `teamcity project token get <id> <token>`      | Retrieve secret              |
| `teamcity project settings enable <id>`        | Import initial settings from VCS |
| `teamcity project settings export <id>`        | Export settings as ZIP       |
| `teamcity project settings status <id>`        | Show versioned settings sync |
| `teamcity project settings validate [path]`    | Validate Kotlin DSL config   |

### Flags for `teamcity project tree`

- `-d, --depth <n>` - Limit tree depth (0 = unlimited)
- `--no-jobs` - Hide build configurations

### Flags for `teamcity project list`

- `--json` - JSON output (use `--json=` to list fields, `--json=f1,f2` for specific)
- `-n, --limit <n>` - Maximum number of projects
- `-p, --parent <id>` - Filter by parent project ID

### Flags for `teamcity project view`

- `--json` - Output as JSON
- `-w, --web` - Open in browser

### Flags for `teamcity project create`

- `--id <id>` - Explicit project ID (default: auto-generated from name)
- `-p, --parent <id>` - Parent project ID (default: `_Root`)
- `--json` - Output as JSON
- `-w, --web` - Open in browser after creation

### Flags for `teamcity project vcs list`

- `--json` - JSON output (use `--json=` to list fields, `--json=f1,f2` for specific)
- `-n, --limit <n>` - Maximum number of VCS roots
- `-p, --project <id>` - Project ID (required)

### Flags for `teamcity project vcs view`

- `--json` - Output as JSON
- `-w, --web` - Open in browser

### Flags for `teamcity project vcs create`

- `--token-id <id>` - Reference a stored token; requires `--auth token`, excludes `--connection-id`

### Flags for `teamcity project vcs delete`

- `-y, --yes` - Skip confirmation prompt

### Flags for `teamcity project param list`

- `--json` - Output as JSON

### Flags for `teamcity project param set`

- `--secure` - Mark as secure/password parameter

### Flags for `teamcity project settings enable`

- `--vcs-root <id>` - Settings VCS root (required)
- `--format <kotlin|xml>` - Settings format (default: kotlin)
- `--settings-path <path>` - Repository settings directory (default: .teamcity)
- `--json` - Output the configuration as JSON

### Flags for `teamcity project settings export`

- `--kotlin` - Export as Kotlin DSL (default)
- `--xml` - Export as XML
- `-o, --output <path>` - Output file path (default: projectSettings.zip)
- `--relative-ids` - Use relative IDs in exported settings

### Flags for `teamcity project settings status`

- `--json` - Output as JSON

### Flags for `teamcity project settings validate`

- `--verbose` - Show full Maven output
- Positional argument: optional filesystem path to `.teamcity` (not a project ID/name; there is no `--dir` flag)

### Flags for `teamcity project token put`

- `--stdin` - Read value from stdin

## Queue (`teamcity queue`)

| Command                       | Description           |
|-------------------------------|-----------------------|
| `teamcity queue list`         | List queued builds    |
| `teamcity queue remove <id>`  | Remove from queue     |
| `teamcity queue top <id>`     | Move to top of queue  |
| `teamcity queue approve <id>` | Approve waiting build |

### Flags for `teamcity queue list`

- `-j, --job <id>` - Filter by job ID
- `--json` - JSON output (use `--json=` to list fields, `--json=f1,f2` for specific)
- `-n, --limit <n>` - Maximum number of queued runs

### Flags for `teamcity queue remove`

- `-y, --yes` - Skip confirmation prompt

## Agents (`teamcity agent`)

| Command                           | Description                       |
|-----------------------------------|-----------------------------------|
| `teamcity agent list`             | List build agents                 |
| `teamcity agent view <id>`        | View agent details                |
| `teamcity agent authorize <id>`   | Authorize agent to run builds     |
| `teamcity agent deauthorize <id>` | Revoke agent authorization        |
| `teamcity agent enable <id>`      | Enable agent                      |
| `teamcity agent disable <id>`     | Disable agent                     |
| `teamcity agent move <id> <pool>` | Move agent to different pool      |
| `teamcity agent jobs <id>`        | List compatible/incompatible jobs |
| `teamcity agent exec <id> <cmd>`  | Execute command on agent          |
| `teamcity agent term <id>`        | Open interactive shell on agent   |
| `teamcity agent reboot <id>`      | Reboot a build agent              |

`agent exec` and `agent term` are blocked by `TEAMCITY_RO=1` or per-server `ro: true`.

### Flags for `teamcity agent list`

- `-p, --pool <name>` - Filter by agent pool
- `--connected` - Show only connected agents
- `--enabled` - Show only enabled agents
- `--authorized` - Show only authorized agents
- `-n, --limit <n>` - Limit results
- `--json` - JSON output (use `--json=` to list fields, `--json=f1,f2` for specific)

### Flags for `teamcity agent view`

- `--json` - Output as JSON
- `-w, --web` - Open in browser

### Flags for `teamcity agent jobs`

- `--incompatible` - Show incompatible jobs with reasons
- `--json` - Output as JSON

### Flags for `teamcity agent exec`

- `--timeout <duration>` - Command timeout

### Flags for `teamcity agent reboot`

- `--graceful` - Wait for current build to finish before rebooting
- `-y, --yes` - Skip confirmation prompt

## Agent Pools (`teamcity pool`)

| Command                          | Description              |
|----------------------------------|--------------------------|
| `teamcity pool list`                   | List agent pools         |
| `teamcity pool view <id>`              | View pool details        |
| `teamcity pool link <id> <project>`    | Link project to pool     |
| `teamcity pool unlink <id> <project>`  | Unlink project from pool |

### Flags for `teamcity pool list`

- `--json` - JSON output (use `--json=` to list fields, `--json=f1,f2` for specific)

### Flags for `teamcity pool view`

- `--json` - Output as JSON
- `-w, --web` - Open in browser

## Pipelines (`teamcity pipeline`)

Pipelines are YAML-first build configurations. Each pipeline is a project that can contain multiple jobs defined in a `.teamcity.yml` file. Pipelines differ from jobs/build configs: they use YAML for configuration and can be stored in VCS or on the server.

| Command                                  | Description                              |
|------------------------------------------|------------------------------------------|
| `teamcity pipeline list`                 | List pipelines                           |
| `teamcity pipeline view <id>`            | View pipeline details                    |
| `teamcity pipeline create <name>`        | Create pipeline from YAML                |
| `teamcity pipeline validate [file]`      | Validate pipeline YAML against complete server schema    |
| `teamcity pipeline pull <id>`            | Download pipeline YAML                   |
| `teamcity pipeline push <id> [file]`     | Upload YAML; `-f file` is an alternative to `[file] |
| `teamcity pipeline delete <id>`          | Delete a pipeline                        |

### Flags for `teamcity pipeline list`

- `-p, --project <id>` - Filter by project ID
- `-n, --limit <n>` - Maximum number of items (default: 30)
- `--json` - JSON output (use `--json=` to list fields, `--json=f1,f2` for specific)
- `--plain` - Plain text output for scripting
- `--no-header` - Omit header row

### Flags for `teamcity pipeline view`

- `--json` - Output as JSON
- `-w, --web` - Open in browser

### Flags for `teamcity pipeline create`

- `-p, --project <id>` - Parent project ID **(required)**
- `--vcs-root <id>` - VCS root ID (interactive selection if omitted)
- `-f, --file <path>` - Pipeline YAML file (default: `.teamcity.yml`)

### Flags for `teamcity pipeline validate`

- `--schema <path>` - Local JSON schema file (overrides server schema)
- `--refresh-schema` - Force re-fetch schema from server

### Flags for `teamcity pipeline pull`

- `-o, --output <path>` - Write YAML to file instead of stdout

### Flags for `teamcity pipeline delete`

- `-y, --yes` - Skip confirmation prompt

## Server (`teamcity server`)

| Command                                      | Description                      |
|----------------------------------------------|----------------------------------|
| `teamcity server plugin upload <plugin.zip>` | Upload a TeamCity plugin archive |

### Flags for `teamcity server plugin upload`

- `--hot-reload` - Apply the uploaded update without restarting the server
- `--json` - Output the upload result as JSON

Hot reload requires an already loaded plugin that supports runtime reload. The
command reports TeamCity unload or load errors when the update cannot be applied.

## Configuration (`teamcity config`)

| Command                               | Description                    |
|---------------------------------------|--------------------------------|
| `teamcity config list`                | List all configuration values  |
| `teamcity config get <key>`           | Get a configuration value      |
| `teamcity config set <key> <value>`   | Set a configuration value      |

Valid keys: `default_server`, `guest`, `ro`, `token_expiry`.

Per-server keys (`guest`, `ro`, `token_expiry`) use `--server <url>` to target a specific server. Without `--server`, the default server is used.

### Flags for `teamcity config list`

- `--json` - Output as JSON

### Flags for `teamcity config get` and `set`

- `-s, --server <url>` - Server URL for per-server settings

### Examples

```bash
# Switch default server
teamcity config set default_server tc.example.com

# Enable read-only mode
teamcity config set ro true --server tc.example.com

# Check current default server
teamcity config get default_server
```

## Direct API (`teamcity api`)

For features not covered by specific commands. Endpoints always start with `/app/rest/`.
Pass only the endpoint path as the first argument (never include `GET`, `POST`, etc. in the path).

```bash
# GET request
teamcity api '/app/rest/server'

# POST request
teamcity api '/app/rest/buildQueue' -X POST -f 'buildType=id:MyBuild'

# With pagination
teamcity api '/app/rest/builds' --paginate --slurp

# Browse artifact subdirectory
teamcity api '/app/rest/builds/id:BUILD_ID/artifacts/children/SUBPATH'
```

### Flags

- `-X, --method <method>` - HTTP method
- `-H, --header <h>` - Custom header (repeatable)
- `-f, --field <k=v>` - Body field (builds JSON)
- `--input <file>` - Read body from file (use - for stdin)
- `--paginate` - Fetch all pages
- `--slurp` - Combine pages into array (requires --paginate)
- `--raw` - Output raw response without formatting
- `--silent` - Suppress output on success
- `-i, --include` - Include response headers in output

## Global Flags

Available on all commands:

- `-h, --help` - Help for command
- `-v, --version` - Version information
- `--no-color` - Disable colored output
- `-q, --quiet` - Suppress non-essential output
- `--verbose` - Show detailed output including debug info
- `--no-input` - Disable interactive prompts
- `-w, --web` - Open in browser (on view commands)

## List Output Flags

Available on all list commands (`run list`, `agent list`, `job list`, `pool list`, `project list`, `queue list`, `project vcs list`, `pipeline list`) and on `agent jobs`, `project param list`, `job param list`:

- `--plain` - Tab-separated plain text output for scripting (mutually exclusive with `--json`)
- `--no-header` - Omit header row (use with `--plain`)

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

# Output Formats

Most commands support multiple output formats for different use cases.

## Available Formats

| Format          | Flag          | Use Case                       |
|-----------------|---------------|--------------------------------|
| Table (default) | none          | Human-readable, colored output |
| Plain text      | `--plain`     | Scripting, parsing             |
| JSON            | `--json`      | Programmatic access            |
| No color        | `--no-color`  | Logs, CI environments          |
| No header       | `--no-header` | Clean output for piping        |

## JSON Output

**Default JSON (all fields):**
```bash
teamcity run list --json
```

**List available fields:**
```bash
teamcity run list --json=
```

**Select specific fields:**
```bash
teamcity run list --json=id,status,webUrl
```

**Nested fields (dot notation):**
```bash
teamcity run list --json=id,buildType.name,triggered.user.username
```

## Available JSON Fields by Command

| Command        | Example fields                                                                                                                                                                                        |
|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `run list`     | `id`, `number`, `status`, `state`, `branchName`, `buildTypeId`, `buildType.name`, `buildType.projectName`, `triggered.type`, `triggered.user.name`, `agent.name`, `startDate`, `finishDate`, `webUrl` |
| `job list`     | `id`, `name`, `projectName`, `projectId`, `paused`, `href`, `webUrl`                                                                                                                                  |
| `project list` | `id`, `name`, `description`, `parentProjectId`, `href`, `webUrl`                                                                                                                                      |
| `queue list`   | `id`, `buildTypeId`, `state`, `branchName`, `queuedDate`, `buildType.name`, `triggered.user.name`, `webUrl`                                                                                           |
| `agent list`   | `id`, `name`, `connected`, `enabled`, `authorized`, `pool.name`, `webUrl`                                                                                                                             |
| `pool list`    | `id`, `name`, `maxAgents`                                                                                                                                                                             |
| `pipeline list`| `id`, `name`, `webUrl`, `parentProject.id`, `parentProject.name`, `headBuildType.id`, `jobs.count`                                                                                                    |

Run `teamcity <command> --json=` to see all available fields for that command.

## Scripting Examples

**Get build IDs of failed builds:**
```bash
teamcity run list --status failure --plain --no-header | awk '{print $2}'
```

**JSON with jq:**
```bash
teamcity run list --json | jq '.build[] | {id, status, branchName}'
```

**Get build IDs that failed (JSON):**
```bash
teamcity run list --status failure --json=id | jq -r '.build[].id'
```

**Export runs to CSV:**
```bash
teamcity run list --json=id,status,branchName | jq -r '.build[] | [.id,.status,.branchName] | @csv'
```

**Filter builds by pattern:**
```bash
teamcity run list --json | jq '.build[] | select(.branchName | contains("feature"))'
```

**Count builds by status:**
```bash
teamcity run list --json | jq '.build | group_by(.status) | map({status: .[0].status, count: length})'
```

**Get web URLs for queued builds:**
```bash
teamcity queue list --json=webUrl | jq -r '.build[].webUrl'
```

## Environment Variables

For non-interactive use (CI/CD, scripts):

```bash
export TEAMCITY_URL="https://teamcity.example.com"
export TEAMCITY_TOKEN="your-api-token"

# Commands will use these automatically
teamcity run list
```

Environment variables always take precedence over config file settings.

Other supported variables:
- `TEAMCITY_GUEST=1` — use guest authentication
- `TEAMCITY_RO=1` — read-only mode (block write operations)
- `TEAMCITY_NO_UPDATE=1` — disable automatic update checks
- `NO_COLOR` or `TEAMCITY_NO_COLOR` — disable colored output

## Combining with Other Tools

**Open in browser:**
```bash
teamcity run view <id> -w
```

**Pipe to less with color:**
```bash
teamcity run list | less -R
```

**Watch and notify:**
```bash
teamcity run watch <id> && notify-send "Build complete"
```

# Common Workflows

## Contents

- Inspecting a build from a TeamCity URL
- Investigating a build failure
- Starting and monitoring builds
- Personal builds (local changes)
- Finding jobs and projects
- Working with build artifacts
- Build metadata (pin/unpin, tag, comment)
- Managing the build queue
- Managing job and project parameters
- Validating Kotlin DSL locally
- Project connections (GitHub App, Docker)
- VCS roots
- Project settings (export & status)
- Secure tokens
- Managing agents
- Remote agent access (term, exec)
- Managing agent pools
- Failure classification
- Build chain debugging
- Fixing a build failure
- Monitoring builds until green
- Test reliability analysis
- Working with pipelines
- Tips
- Troubleshooting

## Inspecting a Build from a TeamCity URL

When a user provides a TeamCity URL, parse it and map to `teamcity` commands.

**Format 1: Specific build** — `https://host/buildConfiguration/ConfigId/12345`
```bash
# Extract build ID (last numeric path segment): 12345
teamcity run view 12345
# If failed:
teamcity run log 12345 --failed --raw
teamcity run tests 12345 --failed
```

**Format 2: Build configuration** — `https://host/buildConfiguration/ConfigId`
```bash
# Extract config ID (last non-numeric path segment): ConfigId
teamcity run list --job ConfigId
```

**Format 3: Project** — `https://host/project/ProjectId`
```bash
# Extract project ID: ProjectId
teamcity job list --project ProjectId
```

Strip query params (`?mode=builds`) and fragments (`#all-projects`) before parsing.

## Investigating a Build Failure

When a build has **FAILURE** status, proactively suggest: `teamcity run log <id> --failed` (failure summary), `teamcity run tests <id> --failed` (failed tests), `teamcity run changes <id>` (triggering changes).

For **composite/matrix builds** (snapshot dependencies, no agent), find failed children with `teamcity run list --status failure` and appropriate filters.

1. **Find the failed build:**
   ```bash
   teamcity run list --status failure -n 10
   ```

2. **View build details:**
   ```bash
   teamcity run view <run-id>
   ```

3. **Check the build log:**
   ```bash
   teamcity run log <run-id> --raw
   ```

   Always use `--raw` to avoid interactive terminal formatting. Dump the output to a temp file to re-read it as needed.

   For failed steps only:
   ```bash
   teamcity run log <run-id> --failed
   ```

4. **View test results:**
   ```bash
   teamcity run tests <run-id>
   ```

   For failed tests only:
   ```bash
   teamcity run tests <run-id> --failed
   ```

5. **See what changes triggered the build:**
   ```bash
   teamcity run changes <run-id>
   ```

## Starting and Monitoring Builds

> **Always use `--watch`** when starting builds to wait until the build finishes before proceeding.
> **Always verify the branch name** — do not guess. Check with `git branch` or `teamcity run list --job <job-id>` to see valid branches.

**Start a build:**
```bash
teamcity run start <job-id> --watch
```

**Start with specific branch:**
```bash
teamcity run start <job-id> --branch feature/my-branch --watch
```

For jobs with unrelated VCS roots, pin each root independently (use VCS root IDs):

```bash
teamcity run start <job-id> --branch feature/game \
  --revision GameRepo=<sha>@feature/game --revision AssetsRepo=@main
```

Unspecified roots keep normal TeamCity selection. Branch-only pins use the latest
head TeamCity has fetched; explicit per-root SHAs are not resolved in local Git.


**Start with parameters:**
```bash
teamcity run start <job-id> -P "param1=value1" -P "param2=value2"
```

**Start with env vars and system properties:**
```bash
teamcity run start <job-id> -P version=1.0 -S build.number=123 -E CI=true
```

**Start and watch:**
```bash
teamcity run start <job-id> --watch
teamcity run start <job-id> --watch --timeout 30m
```

**Start with comment and tags:**
```bash
teamcity run start <job-id> --comment "Release build" --tag release --tag v1.0
```

**Start with clean checkout and rebuild deps:**
```bash
teamcity run start <job-id> --clean --rebuild-deps --top
```

**Dry run (see what would be triggered):**
```bash
teamcity run start <job-id> --dry-run
```

**Watch an existing build:**
```bash
teamcity run watch <run-id>
```

**Stream logs while watching:**
```bash
teamcity run watch <run-id> --logs
```

**Watch with timeout:**
```bash
teamcity run watch <run-id> --timeout 30m --quiet
```

**Wait for completion and get JSON result (for scripting):**
```bash
teamcity run start <job-id> --watch --json
teamcity run watch <run-id> --json
```

## Personal Builds (Local Changes)

> **Kotlin DSL caveat:** `--local-changes` does **not** include changes to Kotlin DSL (`.teamcity/`). Always push Kotlin DSL changes to the remote before running the build.

**Run build with local git changes:**
```bash
teamcity run start <job-id> --local-changes
```

**Run build from a patch file:**
```bash
teamcity run start <job-id> --local-changes changes.patch
```

**Personal build with specific branch:**
```bash
teamcity run start <job-id> --personal --branch my-feature --watch
```

**Skip auto-push:**
```bash
teamcity run start <job-id> --local-changes --no-push
```

## Finding Jobs and Projects

**List all projects:**
```bash
teamcity project list
```

**List sub-projects:**
```bash
teamcity project list --parent <project-id>
```

**Create a project:**
```bash
teamcity project create <name>
teamcity project create <name> --id <id> --parent <parent-id>
```

**List jobs in a project:**
```bash
teamcity job list --project <project-id>
```

**View job details:**
```bash
teamcity job view <job-id>
```

**Search for a job by name:**
```bash
teamcity job list --json | jq '.buildType[] | select(.name | contains("deploy"))'
```

## Working with Build Artifacts

**List artifacts from a build:**
```bash
teamcity run artifacts <run-id>
```

**List artifacts from latest build of a job:**
```bash
teamcity run artifacts --job <job-id>
```

**Download all artifacts:**
```bash
teamcity run download <run-id>
```

**Download to specific directory:**
```bash
teamcity run download <run-id> -o ./artifacts
```

**Download a subdirectory:**
```bash
teamcity run download <run-id> --path build/assets
```

**Download specific artifact pattern:**
```bash
teamcity run download <run-id> --artifact "*.jar"
```

**Combine path and pattern:**
```bash
teamcity run download <run-id> --path build/assets -a "*.js"
```

## Build Metadata

**Pin a build (prevent cleanup):**
```bash
teamcity run pin <run-id> --comment "Release candidate"
```

**Unpin a build:**
```bash
teamcity run unpin <run-id>
```

**Tag a build:**
```bash
teamcity run tag <run-id> deployed production
```

**Remove tags:**
```bash
teamcity run untag <run-id> deployed
```

**Add a comment:**
```bash
teamcity run comment <run-id> "Verified by QA"
```

**View existing comment:**
```bash
teamcity run comment <run-id>
```

**Delete a comment:**
```bash
teamcity run comment <run-id> --delete
```

## Managing the Build Queue

**View queued builds:**
```bash
teamcity queue list
```

**Filter queue by job:**
```bash
teamcity queue list --job <job-id>
```

**Move a build to top of queue:**
```bash
teamcity queue top <run-id>
```

**Remove from queue:**
```bash
teamcity queue remove <run-id>
```

**Approve a build waiting for approval:**
```bash
teamcity queue approve <run-id>
```

## Managing Job and Project Parameters

**List job parameters:**
```bash
teamcity job param list <job-id>
```

**Set a parameter:**
```bash
teamcity job param set <job-id> MY_PARAM "my value"
```

**Set a secure parameter:**
```bash
teamcity job param set <job-id> SECRET_KEY "****" --secure
```

**Get a parameter:**
```bash
teamcity job param get <job-id> MY_PARAM
```

**Delete a parameter:**
```bash
teamcity job param delete <job-id> MY_PARAM
```

Project parameters work the same way with `teamcity project param`.

## Validating Kotlin DSL Locally

**Always use `teamcity project settings validate`** to verify Kotlin DSL — never generic `mvn compile`.

Under the hood it runs `mvn teamcity-configs:generate` (or `./mvnw` when available) inside the `.teamcity/` directory, which is the only correct DSL validation step. Generic Maven commands like `mvn compile` do **not** validate TeamCity DSL and will give misleading results.
The optional positional argument is only a filesystem path to `.teamcity`; do **not** pass a TeamCity project ID/name, and do **not** invent `--dir`.

```bash
# Preferred — auto-detects .teamcity dir and Maven wrapper
teamcity project settings validate

# Explicit path
teamcity project settings validate ./path/to/.teamcity

# Show full Maven output for debugging
teamcity project settings validate --verbose
```

If you need the raw Maven command (e.g., in CI without the CLI installed):
```bash
./mvnw teamcity-configs:generate -f .teamcity/pom.xml   # prefer wrapper
mvn teamcity-configs:generate -f .teamcity/pom.xml       # fallback
```

## Project Connections

Connections give jobs credentials for external services (GitHub, Docker registries, AWS, ...) without storing secrets per-job. Required before creating a VCS root that authenticates via OAuth.

Connections listed or selected with `--project` include parent projects, including `_Root`. Delete an inherited connection from its owning project.

**Inspect existing connections in a project:**
```bash
teamcity project connection list --project <project-id>
```

### Connecting a GitHub repository (GitHub App)

> **Prefer a GitHub App connection for GitHub.** Authorization is per TeamCity user. TeamCity may copy a permanent token or reference a refreshable token; this flow does not guarantee a service identity.

Creates a fresh GitHub App via GitHub's manifest flow — credentials are captured automatically, no PAT involved. Lets jobs clone, post commit statuses, and comment on PRs.

**1. Create the connection** (one browser click on github.com):

```bash
teamcity project connection create github-app -p <project-id>
# prompts: Connection name (default "GitHub App"), GitHub organization (blank for personal)
# browser auto-redirects to GitHub's "Create GitHub App" page; click Create.
# CLI captures App ID, client ID, secret, PEM, owner URL.
```

The output prints `Next steps:` with follow-up commands and the install link. Capture the `PROJECT_EXT_NN` from the success line.

**2. Authorize as the current TeamCity user** (stores a token for `(connection × user)`):

```bash
teamcity project connection authorize PROJECT_EXT_NN -p <project-id>
# Prints the URL and opens the browser; add --no-input to print it without opening.
# Complete authorization in the browser; the tab closes on success.
```

**3. Install the App on a repo** (one-time, per repo, on github.com):

Open the printed install link `https://github.com/apps/<slug>/installations/new`, pick repos, click Install.

> Steps 2 and 3 are independent — order doesn't matter. Both must complete before step 4: Authorize provides the user token TeamCity uses for API calls; Install grants the App access to the repo. `vcs create` will fail without either.

**4. Create the VCS root using the connection:**

```bash
teamcity project vcs create -p <project-id> \
  --auth token \
  --connection-id PROJECT_EXT_NN \
  --url https://github.com/<owner>/<repo>.git
```

To reference an existing stored token explicitly, replace `--connection-id` with `--token-id <full-token-id>`. The token must be permitted in this project; use `--username` if the provider requires a value other than `oauth2`. This writes `ACCESS_TOKEN` and `tokenId` without copying a secret; test the root in the TeamCity UI.

**Non-interactive (agent) variant — bring your own GitHub App credentials:**

```bash
echo "$GH_APP_CLIENT_SECRET" | teamcity project connection create github-app \
  -p <project-id> --no-manifest \
  --name "Backend" \
  --owner my-org \
  --app-id 1234567 \
  --client-id Iv1.abc \
  --private-key-file /path/to/key.pem \
  --stdin
```

Skips the manifest browser flow; use when a human has already registered the App and stored its credentials in a vault.

### Connecting a Docker registry

For pushing images to GHCR, Docker Hub, or a private registry. Uses static credentials — always use a service account / robot user, never a personal password.

```bash
echo "$REGISTRY_TOKEN" | teamcity project connection create docker \
  -p <project-id> \
  --name "GHCR" \
  --url https://ghcr.io \
  --username my-org \
  --stdin
```

Interactive variant prompts for each field; password is read via a secret prompt (never echoed). The connection is referenced from the Docker Image Builder runner and the `docker-support` build feature via its ID; configure those in the UI or Kotlin DSL.

### Removing a connection

```bash
teamcity project connection delete PROJECT_EXT_NN -p <project-id>
teamcity project connection delete PROJECT_EXT_NN -p <project-id> --force   # skip confirm
```

VCS roots and build features that reference the deleted connection break — clean those up first.

**Gotchas:**
- `vcs create --auth token` test connection returns "Malformed request" if the user hasn't authorized yet. The CLI prints a tip pointing at `connection authorize`. Run that, then retry.
- The App's per-repo install (step 3) is mandatory; without it, clones return 404 even with a valid connection.
- Connections in a parent project are inherited by sub-projects — don't recreate the same connection in nested projects.
- For Docker on AWS-managed ECR, prefer an AWS connection with role-based federation over Docker credentials.

## VCS Roots

`teamcity project vcs test <id>` tests saved credentials through the web UI endpoint; if access is blocked, use the printed UI link.

For questions like "which repository URL and default branch does project `<id>` use", always discover attached VCS roots first, then inspect a concrete root.

**List VCS roots in a project:**
```bash
teamcity project vcs list --project <project-id>
```

**View VCS root details:**
```bash
teamcity project vcs view <vcs-root-id>
```

**Required sequence for project VCS inspection:**
1. Run `teamcity project vcs list --project <project-id>` to get valid root IDs.
2. Run `teamcity project vcs view <vcs-root-id>` for URL, default branch, auth method, and other properties.
3. Do not guess VCS root IDs.
4. Do not use `teamcity project view` or `teamcity project settings status` as a substitute for VCS root details.

**Create a VCS root:**
```bash
# Preferred for GitHub: use a GitHub App connection (see Project Connections above).
teamcity project vcs create -p <project-id> \
  --auth token --connection-id <connection-id> \
  --url https://github.com/<owner>/<repo>.git

# Other auth methods (use only when there is no usable connection).
teamcity project vcs create -p <project-id> --url <url> --auth anonymous
teamcity project vcs create -p <project-id> --url <url> --auth password --username U --stdin <<<"$PAT"
teamcity project vcs create -p <project-id> --url <url> --auth ssh-key --ssh-key-name my-key
```

> **For GitHub repositories, always prefer the GitHub App connection path** (`--auth token --connection-id <id>`). Pasting a personal access token via `--auth password` works but is an anti-pattern: PATs are tied to a single human, leak via job logs, and can't be revoked centrally. Use the [Connecting a GitHub repository](#connecting-a-github-repository-github-app) workflow before falling back to PAT auth.

**Delete a VCS root:**
```bash
teamcity project vcs delete <vcs-root-id>
teamcity project vcs delete <vcs-root-id> --yes   # skip confirmation
```

## Project Settings (Export & Status)

**Import initial settings from VCS (keeps UI editing enabled; refuses existing configurations):**
```bash
teamcity project settings enable <project-id> --vcs-root <root-id>
teamcity project settings status <project-id>
```

**Check versioned settings sync status (requires server connection):**
```bash
teamcity project settings status <project-id>
```

**Export project settings as Kotlin DSL:**
```bash
teamcity project settings export <project-id>
```

**Export as XML:**
```bash
teamcity project settings export <project-id> --xml -o settings.zip
```

## Secure Tokens

**Store a secret and get a token reference:**
```bash
teamcity project token put <project-id> "my-secret-password"
```

**Store from stdin (for piping):**
```bash
echo -n "my-secret" | teamcity project token put <project-id> --stdin
```

**Retrieve a token value (requires System Admin):**
```bash
teamcity project token get <project-id> "credentialsJSON:abc123..."
```

## Managing Agents

**List all agents:**
```bash
teamcity agent list
```

**List connected agents only:**
```bash
teamcity agent list --connected
```

**Filter agents by pool:**
```bash
teamcity agent list --pool Default
```

**View agent details:**
```bash
teamcity agent view <agent-id>
```

**See what jobs an agent can run:**
```bash
teamcity agent jobs <agent-id>
```

**See why jobs are incompatible with an agent:**
```bash
teamcity agent jobs <agent-id> --incompatible
```

**Enable/disable an agent:**
```bash
teamcity agent enable <agent-id>
teamcity agent disable <agent-id>
```

**Authorize/deauthorize an agent:**
```bash
teamcity agent authorize <agent-id>
teamcity agent deauthorize <agent-id>
```

**Move agent to a different pool:**
```bash
teamcity agent move <agent-id> <pool-id>
```

**Reboot an agent:**
```bash
teamcity agent reboot <agent-id>
```

**Reboot after current build finishes:**
```bash
teamcity agent reboot <agent-id> --graceful
```

## Remote Agent Access

`TEAMCITY_RO=1` or per-server `ro: true` blocks both commands below before connecting. Use server-side permissions, rather than this local guard alone, to restrict credential access.

**Open interactive shell on an agent:**
```bash
teamcity agent term <agent-id>
```

**Execute a command on an agent:**
```bash
teamcity agent exec <agent-id> "ls -la"
```

**Execute with timeout:**
```bash
teamcity agent exec <agent-id> --timeout 10m -- long-running-script.sh
```

## Managing Agent Pools

**List all pools:**
```bash
teamcity pool list
```

**View pool details:**
```bash
teamcity pool view <pool-id>
```

**Link a project to a pool:**
```bash
teamcity pool link <pool-id> <project-id>
```

**Unlink a project from a pool:**
```bash
teamcity pool unlink <pool-id> <project-id>
```

## Failure Classification

When a build fails, classify the failure before attempting a fix. The classification determines the fix strategy.

**Decision tree:**

1. **Is the build composite (no agent, has snapshot dependencies)?**
   - Yes → The composite build itself has no logs. Drill into child builds to find the actual failure. Use `teamcity run list --status failure` filtered to the relevant job tree.
2. **Is the failure transient or permanent?**
   - Transient: infrastructure timeouts, agent disconnects, OOM on agent, flaky tests (same code passes on retry). Fix: retry with `teamcity run restart <id>`.
   - Permanent: compilation errors, test failures correlated with code changes, config errors. Fix: change code or config.
3. **Is the failure in code, versioned settings, or server config?**
   - Code: fix in repo, verify with `--local-changes`, push.
   - Versioned settings (Kotlin DSL): fix in repo, validate with `teamcity project settings validate`, push. Cannot use `--local-changes`.
   - Pipeline YAML: fix in repo, validate with `teamcity pipeline validate`, push. Cannot use `--local-changes`.
   - Server config: fix via TeamCity UI or API. Not in repo.

**Default:** treat unknown failures as permanent until proven otherwise.

**Gotchas:**
- Composite builds have empty logs — always drill to child failures first.
- A build can fail with "no compatible agents" — this is server config, not code.
- `--local-changes` does NOT include Kotlin DSL or pipeline YAML stored in repo.

## Build Chain Debugging

TeamCity's snapshot dependency chains are unique — no competitor has this. When a build in a chain fails, the failure cascades upstream, so multiple builds may show as failed.

**Find the root failure:**

```bash
# View the dependency tree for a specific build run (shows statuses)
teamcity run tree <run-id>

# Use --json for programmatic analysis
teamcity run tree <run-id> --json
```

`run tree` shows the actual build runs with their statuses, so you can immediately see which dependency failed. Use `job tree` if you need the job-level (build configuration) dependency structure instead.

**Key principle:** The first failure in the chain (the deepest dependency that failed) is the root cause, not the last. Work bottom-up.

**Steps:**
1. Start from the build the user reported.
2. Run `teamcity run tree <run-id>` to see the full dependency tree with statuses.
3. Find the deepest build in the tree that has a failure status (not just "Snapshot dependency build failed").
4. That's your root cause. Investigate its logs: `teamcity run log <id> --failed --raw`

**Gotchas:**
- Builds that fail only because a dependency failed show "Snapshot dependency build failed" — skip these and go deeper.
- Restarting the top-level build won't help if the root child is still broken.
- Use `run tree` (shows actual builds with statuses) for debugging failures. Use `job tree` (shows build configuration structure) for understanding the dependency graph.

## Fixing a Build Failure

End-to-end workflow for diagnosing and fixing a CI failure. Equivalent to GitHub's `gh-fix-ci`.

### Step 1: Find and diagnose

```bash
# Get the failed build details
teamcity run view <run-id>

# Get the failure log (always use --raw, dump to temp file)
teamcity run log <run-id> --failed --raw > /tmp/build-failure.log

# Check failed tests
teamcity run tests <run-id> --failed

# See what changes triggered the build
teamcity run changes <run-id>
```

### Step 2: Classify the failure

Use the [Failure Classification](#failure-classification) decision tree above.

### Step 3: Fix

**For code failures:**
1. Read the relevant source files and understand the error.
2. Make the fix.
3. Verify locally if possible (run tests, compile, lint).
4. Verify on TeamCity without committing:
   ```bash
   teamcity run start <job-id> --local-changes --watch
   ```
5. Once green, commit and push.

**For versioned settings failures (Kotlin DSL):**
1. Fix the DSL code in `.teamcity/`.
2. Validate locally:
   ```bash
   teamcity project settings validate
   ```
3. Push the fix (cannot use `--local-changes` for DSL).

**For pipeline YAML failures:**
- **Server-stored pipelines:** pull → fix → validate → push:
  ```bash
  teamcity pipeline pull <pipeline-id> -o /tmp/pipeline.yml
  # edit /tmp/pipeline.yml
  teamcity pipeline validate /tmp/pipeline.yml
  teamcity pipeline push <pipeline-id> /tmp/pipeline.yml
  ```
- **VCS-stored pipelines** (`.teamcity.yml` in repo): edit the file directly, validate, then commit and push:
  ```bash
  # edit .teamcity.yml
  teamcity pipeline validate .teamcity.yml
  git add .teamcity.yml && git commit -m "fix: ..." && git push
  ```
  (`pull`/`push` commands fail for VCS-backed pipelines — edit the repo file instead.)

**For server config failures:**
1. Identify the misconfiguration from the logs.
2. Fix via TeamCity UI or `teamcity api`.
3. Restart the build: `teamcity run restart <run-id>`

### Guardrails

- Never delete or skip failing tests to make the build green.
- Never disable linting or static analysis steps.
- Never force-push to fix a build.
- If the fix requires changes outside your expertise, document the diagnosis and escalate.

**Gotchas:**
- Always use `--raw` for logs and dump to a temp file — build logs can be very large and lose formatting without `--raw`.
- `--local-changes` does NOT include Kotlin DSL or pipeline YAML stored in repo. Always push DSL changes before running.
- Composite builds have no logs of their own — drill to the child that actually failed.
- If the build fails with a different error after your fix, that's a new failure — re-diagnose from step 1.

## Monitoring Builds Until Green

Loop workflow for watching a build, fixing failures, and retrying. Equivalent to the `babysit-pr` pattern.

### Loop

1. **Start or watch the build:**
   ```bash
   teamcity run start <job-id> --branch <branch> --watch
   # or watch an existing build:
   teamcity run watch <run-id>
   ```

2. **If the build succeeds:** done.

3. **If the build fails:** run the [Fixing a Build Failure](#fixing-a-build-failure) workflow above.

4. **After pushing the fix:**
   - If the job has a VCS trigger, a new build starts automatically. Poll until a build with a higher ID than the failed one appears, then watch it:
     ```bash
     # Poll for a build on the pushed commit:
     teamcity run list --job <job-id> --branch <branch> --revision @head -n 1 --json
     # Repeat until a result appears (or ~30s pass).
     # If no new build appears, start one manually:
     teamcity run start <job-id> --branch <branch> --watch
     ```
   - If no VCS trigger, start a new build manually:
     ```bash
     teamcity run start <job-id> --branch <branch> --watch
     ```

5. **Repeat** from step 2.

### Stop conditions

- **Success:** the build is green.
- **Max attempts reached:** stop after 3 fix attempts. Each attempt must make different changes — if you're repeating the same fix, something deeper is wrong.
- **Unfixable issue:** server config problem, missing agent, infrastructure failure, or a failure outside the scope of code changes.
- **Same failure after fix:** if the exact same error appears after your fix, re-examine the diagnosis — the fix may not have addressed the root cause.

**Gotchas:**
- A VCS trigger fires only when new commits are pushed to a monitored branch. If the job doesn't have a VCS trigger configured, you must start builds manually with `teamcity run start`.
- After pushing, wait a few seconds before listing runs — the trigger needs time to pick up the change.
- Watch for "build already running" — if a build is queued or running for the same branch, watch it instead of starting a new one.

## Test Reliability Analysis

Identify flaky tests by cross-referencing failures across builds. Equivalent to CircleCI's `find_flaky_tests`.

### Identify potentially flaky tests

```bash
# Start from one build's failures
teamcity run tests <run-id> --failed --json | jq -r '.testOccurrence[].name'

# Then follow a suspect test across the job's builds (the flakiness signal) and
# turn its history into a pass-rate in one line
teamcity run tests --job <job-id> --test "<name>" --json \
  | jq -r '.testOccurrence | "pass \(map(select(.status=="SUCCESS"))|length)/\(length)"'

# Drop --job for a server-wide history of the same test
teamcity run tests --test "<name>" --json
```

### Cross-reference with code changes

```bash
# Check what changed between builds
teamcity run changes <run-id>
```

**Flaky test indicators:**
- Test fails intermittently across builds without corresponding code changes.
- Test passes on retry (restart) without any code change.
- Test fails on one agent but passes on another (environment-dependent).

### What to do with flaky tests

1. Document the flaky test: name, frequency, suspected cause. Use `teamcity run tests --job <id> --test <name>` to quantify frequency from its pass/fail history.
2. If `teamcity test mute` becomes available, use it to mute the test with a comment explaining why (`run tests` is read-only — it does not mute).
3. Otherwise, flag the test in the codebase (e.g., add a skip annotation with a tracking issue).
4. Never silently delete a flaky test — it may be catching real intermittent bugs.

**Gotchas:**
- A test that fails only on certain agents may be environment-dependent, not flaky. Check agent properties with `teamcity agent view <id>`.
- Some test frameworks report different test names on failure vs success (e.g., parameterized tests). Normalize test names before comparing.
- Large test suites may need `--json` output piped through `jq` for efficient filtering.

## Working with Pipelines

Pipelines are YAML-first build configurations. Unlike jobs (build configs) that are configured via UI or Kotlin DSL, pipelines are defined in a `.teamcity.yml` file. Each pipeline is a TeamCity project containing multiple jobs.

**List pipelines:**
```bash
teamcity pipeline list
teamcity pipeline list --project <project-id>
```

**View pipeline details:**
```bash
teamcity pipeline view <pipeline-id>
teamcity pipeline view <pipeline-id> --web   # open in browser
```

**Create a pipeline from YAML:**
```bash
# --vcs-root is required in non-interactive (agent) usage
teamcity pipeline create my-pipeline --project <project-id> --vcs-root <vcs-root-id>

# From a specific file
teamcity pipeline create my-pipeline --project <project-id> --vcs-root <vcs-root-id> --file pipeline.yml
```

**Validate pipeline YAML before pushing:**
```bash
# Validates against the complete server schema with enabled runners/features (cached for 24h)
teamcity pipeline validate

# Validate a specific file
teamcity pipeline validate my-pipeline.yml

# Force re-fetch schema from server
teamcity pipeline validate --refresh-schema
```

**Pull/push pipeline YAML (edit-in-place workflow):**
```bash
# Download current YAML
teamcity pipeline pull <pipeline-id> -o .teamcity.yml

# Edit the file...

# Validate before pushing
teamcity pipeline validate .teamcity.yml

# Upload changes
teamcity pipeline push <pipeline-id> .teamcity.yml
```

**Delete a pipeline:**
```bash
teamcity pipeline delete <pipeline-id>
teamcity pipeline delete <pipeline-id> --yes   # skip confirmation
```

**Gotchas:**
- If the pipeline stores YAML in VCS (versioned settings), `pull` and `push` will return an error — edit the YAML directly in the repo instead.
- `pipeline push` does NOT validate — always run `pipeline validate` first.
- `pipeline create` requires `--project` and `--vcs-root` in non-interactive mode — pipelines always belong to a parent project and VCS root.
- The default YAML file is `.teamcity.yml` in the current directory.

## Tips

1. **Use `--json` for programmatic access** - Parse with `jq` for complex queries

1. **Use `teamcity api` as escape hatch** - When a specific command doesn't exist, use raw API access

1. **Environment variables** - If overriding with env vars, set both `TEAMCITY_URL` and `TEAMCITY_TOKEN`; `TEAMCITY_URL` alone bypasses stored auth

1. **Open in browser** - Most view commands support `-w` to open in web browser

1. **Auto-detection from DSL** – When working in a project with Kotlin DSL config, the server URL is auto-detected from `.teamcity/pom.xml`

1. **Multiple servers** - Use `TEAMCITY_URL` env var to switch between servers, or `teamcity auth login --server <url>` to add servers

## Troubleshooting

| Symptom                      | Likely Cause              | Action                                                                                  |
|------------------------------|---------------------------|-----------------------------------------------------------------------------------------|
| `401 Unauthorized`           | Invalid or expired token  | Run `teamcity auth status` to check; re-login with `teamcity auth login`                |
| `403 Forbidden`              | Insufficient permissions  | Build config may require different access rights; check with TeamCity admin             |
| `404 Not Found`              | Build deleted or wrong ID | Verify the build ID/URL; the build may have been cleaned up                             |
| Connection refused / timeout | Server unreachable        | Check if TeamCity instance is accessible; verify server URL with `teamcity auth status` |
| `Not authenticated`          | Missing or invalid credentials for the selected server | Run `teamcity auth login -s <url>` or override credentials with `TEAMCITY_TOKEN` |
| `No server configured`       | Missing auth config       | Run `teamcity auth login -s <url>` or set `TEAMCITY_URL` and `TEAMCITY_TOKEN` env vars  |
| `Network access blocked by sandbox` | Sandbox proxy blocking outbound requests | Add the server domain to the sandbox `allowedDomains`, or exclude `teamcity` from sandboxing |

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

---
name: babysit-build
description: Monitor a TeamCity build, automatically diagnose and fix failures, and retry until green. Use when asked to watch, babysit, or monitor a build.
model: sonnet
background: true
permissionMode: auto
tools: Bash, Read, Edit, Write, Grep, Glob, Agent
skills:
  - teamcity-cli
---

# babysit-build

Monitor a build and fix failures until it goes green.

## Arguments

`$ARGUMENTS` — build ID, job ID, or TeamCity URL to monitor. If a job ID is given, monitors the latest build for that job.

## Behavior

You are an autonomous background agent. Follow the skill's "Monitoring Builds Until Green" workflow. Key additions:

**Autonomy scope:**
- **Code and DSL fixes** (repo changes) — act immediately, no confirmation needed.
- **Pipeline/server-side fixes** (changes pushed to TeamCity) — show the diff and ask for confirmation before applying.

**Fix discipline:**
- Each attempt MUST differ from previous ones — if you're repeating the same fix, stop and report.
- Verify code fixes with `--local-changes` before committing.

### Stop conditions

1. **Build succeeds** — report with a summary of what was fixed.
2. **3 fix attempts exhausted** — report what was tried and what's still failing.
3. **Unfixable failure** — infrastructure issue, missing agent. Report the diagnosis.
4. **Same error after fix** — fix didn't work. Report what was tried.
5. **Requires human action** — permissions, agent setup, server config beyond the CLI. Report what needs to change.

### Guardrails

- Never delete or skip tests.
- Never disable linting or analysis steps.
- Never force-push.
- Maximum 3 fix attempts total.
- Commit messages must describe what was fixed and why.