Getting Started | TeamCity On-Premises Documentation

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

npm (cross-platform):

npm install -g @jetbrains/teamcity-cli

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
Enter your server URL when prompted. If browser-based login (PKCE) is available on the server, the CLI opens your browser to approve access automatically. Otherwise, you'll be guided to create an access token manually.
Verify the login:
teamcity auth status

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

If you prefer access token login, run teamcity auth login --no-browser. If you already have a token, use teamcity auth login --server https://teamcity.example.com --token <token>.

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.