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          # Full failure diagnostics

Do not guess flags or syntax. Use the Command Reference or teamcity <command> --help. Fall back to teamcity api /app/rest/... when needed. Builds are runs (teamcity run), build configurations are jobs (teamcity job).

Core Commands

Quick Workflows

Investigate failure: teamcity run list --status failure → teamcity run log <id> --failed → teamcity run tests <id> --failed From a URL: Extract build ID from https://host/buildConfiguration/ConfigId/12345 → teamcity run view 12345 Start build: teamcity run start <job-id> --branch <branch> --watch Find jobs: teamcity project list → teamcity job list --project <id> Validate Kotlin DSL: teamcity project settings validate (not mvn compile — see Workflows)

References

• Command Reference - All commands and flags
• Workflows - URL handling, failure investigation, artifacts, agents, and more
• Output Formats - JSON, plain text, scripting

Command Reference

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

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.

• -j, --job <id> - Filter by job
• -b, --branch <name> - Filter by branch
• --status <status> - Filter: success, failure, running, error, unknown
• -u, --user <name> - Filter by user
• -p, --project <id> - Filter by project
• -n, --limit <n> - Limit results (default: 30)
• --since <time> - Since time (e.g., 24h, 2026-01-01)
• --until <time> - Until time (e.g., 12h, 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
• --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
• --top - Add to top of queue
• -n, --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
• --raw - Show raw log without formatting

Flags for teamcity run watch

• -i, --interval <s> - Refresh interval in seconds
• --logs - Stream build logs while watching
• -Q, --quiet - Minimal output, show only state changes and result
• --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

• --failed - Show only failed tests
• -j, --job <id> - Get tests for latest run of this job
• --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 download
• -d, --dir <path> - Directory to download artifacts to

Flags for teamcity run cancel

• --comment <text> - Comment for cancellation
• -f, --force - Skip confirmation prompt

Flags for teamcity run restart

• --watch - Watch the new run after restarting
• -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

Jobs (teamcity job)

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

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

• -v, --verbose - Show full Maven output

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

• -f, --force - 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

• --after-build - 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

Direct API (teamcity api)

For features not covered by specific commands. Endpoints always start with /app/rest/.

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

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 $1}'

JSON with jq:

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

Get build IDs that failed (JSON):

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

Export runs to CSV:

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

Filter builds by pattern:

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

Count builds by status:

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

Get web URLs for queued builds:

teamcity queue list --json=webUrl | jq -r '.[].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.

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

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

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

Start a build:

teamcity run start <job-id>

Start with specific branch:

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

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

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

Personal Builds (Local Changes)

Run build with uncommitted 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>

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 '.[] | 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> --dir ./artifacts

Download specific artifact:

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

Browse artifact subdirectory:

teamcity api /app/rest/builds/id:<run-id>/artifacts/children/html_reports

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.

# 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 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> --after-build

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>

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 - Set TEAMCITY_URL and TEAMCITY_TOKEN for non-interactive use

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