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.
• `TEAMCITY_URL` alone bypasses stored auth — set both TEAMCITY_URL and TEAMCITY_TOKEN, or leave unset.
• 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

Quick Workflows

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 actual schema 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

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.

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)
• Configuration (teamcity config)
• Direct API (teamcity api)
• Global Flags
• List Output Flags

Authentication (teamcity auth)

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.

Builds/Runs (teamcity 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
• --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 build to a specific Git commit 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
• --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

• -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)

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)

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 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 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)

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)

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)

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.

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

Configuration (teamcity config)

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

# 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).

# 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)

Output Formats

Most commands support multiple output formats for different use cases.

Available Formats

JSON Output

Default JSON (all fields):

teamcity run list --json

List available fields:

teamcity run list --json=

Select specific fields:

teamcity run list --json=id,status,webUrl

Nested fields (dot notation):

teamcity run list --json=id,buildType.name,triggered.user.username

Available JSON Fields by Command

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

Scripting Examples

Get build IDs of failed builds:

teamcity run list --status failure --plain --no-header | awk '{print $2}'

JSON with jq:

teamcity run list --json | jq '.build[] | {id, status, branchName}'

Get build IDs that failed (JSON):

teamcity run list --status failure --json=id | jq -r '.build[].id'

Export runs to CSV:

teamcity run list --json=id,status,branchName | jq -r '.build[] | [.id,.status,.branchName] | @csv'

Filter builds by pattern:

teamcity run list --json | jq '.build[] | select(.branchName | contains("feature"))'

Count builds by status:

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

Get web URLs for queued builds:

teamcity queue list --json=webUrl | jq -r '.build[].webUrl'

Environment Variables

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

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:

teamcity run view <id> -w

Pipe to less with color:

teamcity run list | less -R

Watch and notify:

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

# 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

# Extract config ID (last non-numeric path segment): ConfigId
teamcity run list --job ConfigId

Format 3: Project — https://host/project/ProjectId

# 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:

   teamcity run list --status failure -n 10

2. View build details:

   teamcity run view <run-id>

3. Check the build log:

   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:

   teamcity run log <run-id> --failed

4. View test results:

   teamcity run tests <run-id>

For failed tests only:

   teamcity run tests <run-id> --failed

5. See what changes triggered the build:

   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:

teamcity run start <job-id> --watch

Start with specific branch:

teamcity run start <job-id> --branch feature/my-branch --watch

Start with parameters:

teamcity run start <job-id> -P "param1=value1" -P "param2=value2"

Start with env vars and system properties:

teamcity run start <job-id> -P version=1.0 -S build.number=123 -E CI=true

Start and watch:

teamcity run start <job-id> --watch
teamcity run start <job-id> --watch --timeout 30m

Start with comment and tags:

teamcity run start <job-id> --comment "Release build" --tag release --tag v1.0

Start with clean checkout and rebuild deps:

teamcity run start <job-id> --clean --rebuild-deps --top

Dry run (see what would be triggered):

teamcity run start <job-id> --dry-run

Watch an existing build:

teamcity run watch <run-id>

Stream logs while watching:

teamcity run watch <run-id> --logs

Watch with timeout:

teamcity run watch <run-id> --timeout 30m --quiet

Wait for completion and get JSON result (for scripting):

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:

teamcity run start <job-id> --local-changes

Run build from a patch file:

teamcity run start <job-id> --local-changes changes.patch

Personal build with specific branch:

teamcity run start <job-id> --personal --branch my-feature --watch

Skip auto-push:

teamcity run start <job-id> --local-changes --no-push

Finding Jobs and Projects

List all projects:

teamcity project list

List sub-projects:

teamcity project list --parent <project-id>

Create a project:

teamcity project create <name>
teamcity project create <name> --id <id> --parent <parent-id>

List jobs in a project:

teamcity job list --project <project-id>

View job details:

teamcity job view <job-id>

Search for a job by name:

teamcity job list --json | jq '.buildType[] | select(.name | contains("deploy"))'

Working with Build Artifacts

List artifacts from a build:

teamcity run artifacts <run-id>

List artifacts from latest build of a job:

teamcity run artifacts --job <job-id>

Download all artifacts:

teamcity run download <run-id>

Download to specific directory:

teamcity run download <run-id> -o ./artifacts

Download a subdirectory:

teamcity run download <run-id> --path build/assets

Download specific artifact pattern:

teamcity run download <run-id> --artifact "*.jar"

Combine path and pattern:

teamcity run download <run-id> --path build/assets -a "*.js"

Build Metadata

Pin a build (prevent cleanup):

teamcity run pin <run-id> --comment "Release candidate"

Unpin a build:

teamcity run unpin <run-id>

Tag a build:

teamcity run tag <run-id> deployed production

Remove tags:

teamcity run untag <run-id> deployed

Add a comment:

teamcity run comment <run-id> "Verified by QA"

View existing comment:

teamcity run comment <run-id>

Delete a comment:

teamcity run comment <run-id> --delete

Managing the Build Queue

View queued builds:

teamcity queue list

Filter queue by job:

teamcity queue list --job <job-id>

Move a build to top of queue:

teamcity queue top <run-id>

Remove from queue:

teamcity queue remove <run-id>

Approve a build waiting for approval:

teamcity queue approve <run-id>

Managing Job and Project Parameters

List job parameters:

teamcity job param list <job-id>

Set a parameter:

teamcity job param set <job-id> MY_PARAM "my value"

Set a secure parameter:

teamcity job param set <job-id> SECRET_KEY "****" --secure

Get a parameter:

teamcity job param get <job-id> MY_PARAM

Delete a parameter:

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.

# 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):

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

Inspect existing connections in a project:

teamcity project connection list --project <project-id>

Connecting a GitHub repository (GitHub App)

Always use this path for GitHub. Don't vcs create --auth password with a personal access token — PATs tie infrastructure to one human, leak in job logs, and can't be revoked centrally. The four-step flow below produces a non-personal "Refreshable access token" tied to a service-identity App, which is what the TeamCity UI's "Sign in to GitHub App" button creates.

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):

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)):

teamcity project connection authorize PROJECT_EXT_NN -p <project-id>
# browser opens TeamCity's OAuth page → click Authorize on GitHub → tab self-closes.

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:

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

TeamCity auto-fills authMethod=ACCESS_TOKEN, username=oauth2, and the proper tokenId from the connection's stored token. No manual property setup needed; the resulting VCS root uses a non-personal "Refreshable access token" — exactly what the UI's "Sign in to GitHub App" produces.

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

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.

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

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

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:

teamcity project vcs list --project <project-id>

View VCS root details:

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:

# 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 workflow before falling back to PAT auth.

Delete a VCS root:

teamcity project vcs delete <vcs-root-id>
teamcity project vcs delete <vcs-root-id> --yes   # skip confirmation

Project Settings (Export & Status)

Check versioned settings sync status (requires server connection):

teamcity project settings status <project-id>

Export project settings as Kotlin DSL:

teamcity project settings export <project-id>

Export as XML:

teamcity project settings export <project-id> --xml -o settings.zip

Secure Tokens

Store a secret and get a token reference:

teamcity project token put <project-id> "my-secret-password"

Store from stdin (for piping):

echo -n "my-secret" | teamcity project token put <project-id> --stdin

Retrieve a token value (requires System Admin):

teamcity project token get <project-id> "credentialsJSON:abc123..."

Managing Agents

List all agents:

teamcity agent list

List connected agents only:

teamcity agent list --connected

Filter agents by pool:

teamcity agent list --pool Default

View agent details:

teamcity agent view <agent-id>

See what jobs an agent can run:

teamcity agent jobs <agent-id>

See why jobs are incompatible with an agent:

teamcity agent jobs <agent-id> --incompatible

Enable/disable an agent:

teamcity agent enable <agent-id>
teamcity agent disable <agent-id>

Authorize/deauthorize an agent:

teamcity agent authorize <agent-id>
teamcity agent deauthorize <agent-id>

Move agent to a different pool:

teamcity agent move <agent-id> <pool-id>

Reboot an agent:

teamcity agent reboot <agent-id>

Reboot after current build finishes:

teamcity agent reboot <agent-id> --graceful

Remote Agent Access

Open interactive shell on an agent:

teamcity agent term <agent-id>

Execute a command on an agent:

teamcity agent exec <agent-id> "ls -la"

Execute with timeout:

teamcity agent exec <agent-id> --timeout 10m -- long-running-script.sh

Managing Agent Pools

List all pools:

teamcity pool list

View pool details:

teamcity pool view <pool-id>

Link a project to a pool:

teamcity pool link <pool-id> <project-id>

Unlink a project from a pool:

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:

# 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

# 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 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:

   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:

   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:

  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:

  # 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:

   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 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:

     # 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:

     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

# 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

# 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:

teamcity pipeline list
teamcity pipeline list --project <project-id>

View pipeline details:

teamcity pipeline view <pipeline-id>
teamcity pipeline view <pipeline-id> --web   # open in browser

Create a pipeline from YAML:

# --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:

# Validates against server schema (cached locally 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):

# 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:

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