Getting Started | TeamCity CLI

Install TeamCity CLI

Prerequisites

TeamCity CLI requires a running TeamCity server (version 2020.1 or later) to connect to. Some features may require newer TeamCity versions (for example, 2024.04 or later). No additional runtime dependencies are needed — the CLI is distributed as a standalone binary.

Installation

Homebrew (recommended):

brew install jetbrains/utils/teamcity

To update to the latest version:

brew upgrade teamcity

Install script:

curl -fsSL https://jb.gg/tc/install | bash

The script detects your operating system and architecture automatically and installs the teamcity binary to a directory on your PATH.

Install script (all distros):

curl -fsSL https://jb.gg/tc/install | bash

The script detects your operating system and architecture automatically and installs the teamcity binary to a directory on your PATH.

Packages by distribution:

curl -fsSLO https://github.com/JetBrains/teamcity-cli/releases/latest/download/teamcity_linux_amd64.deb
sudo dpkg -i teamcity_linux_amd64.deb

sudo rpm -i https://github.com/JetBrains/teamcity-cli/releases/latest/download/teamcity_linux_amd64.rpm

curl -fsSLO https://github.com/JetBrains/teamcity-cli/releases/latest/download/teamcity_linux_amd64.pkg.tar.zst
sudo pacman -U teamcity_linux_amd64.pkg.tar.zst

Winget (recommended):

winget install JetBrains.TeamCityCLI

PowerShell (install script):

irm https://jb.gg/tc/install.ps1 | iex

CMD (install script):

curl -fsSL https://jb.gg/tc/install.cmd -o install.cmd && install.cmd && del install.cmd

Chocolatey:

choco install teamcitycli

Scoop:

scoop bucket add jetbrains https://github.com/JetBrains/scoop-utils
scoop install teamcity

Build from source (advanced)

Go install:

go install github.com/JetBrains/teamcity-cli/tc@latest

Clone and build:

git clone https://github.com/JetBrains/teamcity-cli.git
cd teamcity-cli
go build -o teamcity ./tc

Verify the installation

After installing, verify that the CLI is available:

teamcity --version

Authenticate with your server

Run the login command:
teamcity auth login
Follow the prompts to enter the server URL and create an access token in your browser.
Verify the login:
teamcity auth status

Tokens are stored in your system keyring (macOS Keychain, GNOME Keyring, or Windows Credential Manager) when available.

Guest access

If the server has guest access enabled, you can log in without a token:

teamcity auth login --guest

Guest access provides read-only access to the server.

Understand the terminology

TeamCity CLI uses shorter names for TeamCity concepts. Knowing these mappings will help you navigate the commands.

Run: A single build execution. Equivalent to build in the TeamCity web interface. Run IDs are numeric.
teamcity run list
Job: A build configuration — the set of instructions that define how to run a build. Job IDs look like MyProject_Build.
teamcity job list
Project: A collection of jobs. Projects can be nested to form a hierarchy. Project IDs look like MyProject.
teamcity project list

The hierarchy is: Project contains Jobs, each Job produces Runs, and each Run executes on an Agent.

List recent builds

teamcity run list

Add filters to narrow results:

# Builds from a specific job
teamcity run list --job MyProject_Build

# Only failures from the last 24 hours
teamcity run list --status failure --since 24h

# Builds on a specific branch
teamcity run list --branch main --limit 10

Find job IDs

Many commands require a job ID. Use teamcity job list to browse available jobs:

# List all jobs
teamcity job list

# Filter by project
teamcity job list --project MyProject

Start a build

Trigger a new build by specifying a job ID:

teamcity run start MyProject_Build

Add --watch to follow the build in real time:

teamcity run start MyProject_Build --branch main --watch

The --watch flag displays a live progress view that updates until the build completes.

View build logs

View the log output from a specific build:

teamcity run log 12345

Or get the latest log for a job:

teamcity run log --job MyProject_Build

Investigate a failure

When a build fails, use this workflow to quickly find the root cause:

Find the failed build:
teamcity run list --status failure
View failure diagnostics (problems, failed tests with full stack traces):
teamcity run log 12345 --failed
Inspect individual test failures:
teamcity run tests 12345 --failed

Check the build queue

See what builds are waiting to run:

teamcity queue list

View build agents

List all registered build agents and their status:

teamcity agent list

Filter to show only connected agents:

teamcity agent list --connected

Open in the browser

Most view commands support a --web flag that opens the corresponding page in your browser:

teamcity run view 12345 --web
teamcity job view MyProject_Build --web
teamcity project view MyProject --web

Next steps

Shell completion: Set up tab completion for Bash, Zsh, Fish, or PowerShell — see Configuration.
Authentication: Learn about authentication methods including multi-server setup and CI/CD usage.
Managing runs: Go deeper with build management — artifacts, personal builds, pinning, tagging, and more.
Aliases: Set up custom shortcuts for frequently used commands.
Scripting: Configure JSON output for scripting and automation.
Command reference: Browse the full command reference for all available commands and flags.