Scripting and Automation

TeamCity CLI provides several output formats and features designed for scripting, automation, and CI/CD integration.

JSON output

Many commands support a --json flag for machine-readable output. List commands also accept optional field selection.

Basic usage

teamcity run list --json
teamcity job list --json
teamcity project list --json

Discovering available fields

Pass --json= (with an empty value) to see all available fields for a command:

teamcity run list --json=

Selecting specific fields

Specify a comma-separated list of fields:

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

Field selection (--json=...) is available on list commands only. View and inspection commands accept --json without field selection.

Nested fields

Use dot notation to access nested fields:

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

JSON for view and inspection commands

teamcity run view 12345 --json
teamcity run log 12345 --json
teamcity run log 12345 --json --failed
teamcity run changes 12345 --json
teamcity run tests 12345 --json
teamcity run artifacts 12345 --json
teamcity agent view Agent-Linux-01 --json
teamcity project settings status MyProject --json
teamcity auth status --json

Available fields by command

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

Plain text output

Use --plain for tab-separated output that is easy to parse with standard Unix tools. This flag is available on all list commands and on agent jobs and param list:

teamcity run list --plain
teamcity agent list --plain
teamcity agent jobs 1 --plain
teamcity project param list MyProject --plain

Omit the header row for cleaner piping:

teamcity run list --plain --no-header
teamcity agent list --plain --no-header | awk '{print $1}'

Scripting examples

Get IDs of failed builds

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

Export build data to CSV

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

Get web URLs for queued builds

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

Count builds by status

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

Wait for a build to finish

teamcity run start MyProject_Build --watch --json

Or start and watch separately:

BUILD_ID=$(teamcity run start MyProject_Build --json | jq -r '.id')
teamcity run watch "$BUILD_ID" --json

Cancel all queued builds for a job

teamcity queue list --job MyProject_Build --json=id | jq -r '.[].id' | xargs -I {} teamcity run cancel {} --yes

CI/CD integration

Environment variable authentication

In CI/CD pipelines, use environment variables for authentication:

export TEAMCITY_URL="https://teamcity.example.com"
export TEAMCITY_TOKEN="your-access-token"

PowerShell:

$env:TEAMCITY_URL = "https://teamcity.example.com"
$env:TEAMCITY_TOKEN = "your-access-token"

CMD:

set TEAMCITY_URL=https://teamcity.example.com
set TEAMCITY_TOKEN=your-access-token

See Authentication for details.

Non-interactive mode

Use --no-input to disable interactive prompts in automated environments. The CLI uses sensible defaults when prompts are suppressed:

teamcity run cancel 12345 --no-input

Alternatively, use --yes on commands that support it:

teamcity queue remove 12345 --yes

Read-only mode

Set TEAMCITY_RO=1 to prevent any write operations. In this mode, commands that would modify data (triggering builds, canceling, pinning, changing parameters, and so on) are rejected before a request is sent:

export TEAMCITY_RO=1
teamcity run list              # works — read-only
teamcity run start MyBuild     # blocked — would trigger a build

This is useful for monitoring dashboards, reporting scripts, and shared environments where accidental modifications must be prevented. The flag also blocks write operations through teamcity api with non-GET methods.

See Configuration for accepted values.

Quiet mode

Use --quiet to suppress non-essential output:

teamcity run start MyProject_Build --quiet

Exit codes

Most commands return exit code 0 on success and 1 on failure. The teamcity run watch flow (including teamcity run start --watch) returns:

2 when a run is canceled
124 on timeout

teamcity run start MyProject_Build --watch --quiet --timeout 30m
case $? in
  0) echo "Build succeeded" ;;
  1) echo "Build failed" ;;
  2) echo "Build cancelled" ;;
  124) echo "Timed out" ;;
  *) echo "Unknown error" ;;
esac

Structured errors

When --json is active and a command fails, the error is written to stderr as structured JSON instead of plain text:

{
  "error": {
    "code": "auth_expired",
    "message": "Authentication failed: invalid or expired token",
    "suggestion": "teamcity auth login"
  }
}

Error codes:

Code	Meaning
`auth_expired`	Token is invalid or expired
`permission_denied`	Insufficient permissions
`not_found`	Requested resource does not exist
`network_error`	Cannot reach the server
`read_only`	Write operation blocked by `TEAMCITY_RO`
`validation_error`	Invalid input (flags, arguments)
`internal_error`	Unexpected error

The suggestion field is omitted when there is no actionable fix. The code field is always present and is safe for programmatic matching.

JSON compatibility policy

The --json output is a machine-readable contract. The following rules apply:

No field removals or renames without a deprecation period in a prior release.
Additive fields are always allowed — new keys may appear in any release.
Error codes are stable — existing codes will not change meaning.
Envelope structure is fixed — success output is the resource data; error output uses the {"error": {...}} envelope on stderr.

Consumers should ignore unknown fields and avoid relying on field ordering.

Raw API access

For operations not covered by dedicated commands, use teamcity api to make direct REST API requests:

teamcity api '/app/rest/server'
teamcity api '/app/rest/builds' --paginate --slurp

See REST API access for details.

14 April 2026