Getting Started | TeamCity Cloud 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. New installs go to ~/.local/bin without sudo; rerunning it updates an existing unmanaged installation in place. Missing Bash/Zsh PATH entries are added automatically. Restart your shell or run the printed PATH command. To choose a directory explicitly, use bash -s -- "" "$HOME/custom/bin". Package-managed or symlinked installs should use their original update method.

Install script (all distros):

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

The script detects your operating system and architecture. New installs go to ~/.local/bin without sudo; rerunning it updates an existing unmanaged installation in place. Missing Bash/Zsh PATH entries are added automatically. Restart your shell or run the printed PATH command. To choose a directory explicitly, use bash -s -- "" "$HOME/custom/bin". Package-managed or symlinked installs should use their original update method.

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

Update TeamCity CLI

Run teamcity update to check for a newer release and confirm installation. Use teamcity update --yes to install without prompting, including in non-interactive scripts. Use teamcity update --check or teamcity update --json to report status without installing.

Homebrew, Scoop, Winget, and Chocolatey installations update through their package manager. Unmanaged macOS/Linux binaries update at the current executable's location, including custom directories and symlink targets. The updater checks the release archive's SHA-256 against the published checksum, verifies the new binary's version, then replaces the old file. Failed downloads and verification leave the installed binary unchanged; the updater never runs sudo or a downloaded shell script.

Go installs, Linux distro packages, and unmanaged Windows binaries currently show manual update instructions. A package-manager release may lag the GitHub release; run teamcity --version after updating to check what was installed.

--json emits current_version, latest_version, update_available, install_method, and release_url. It cannot be combined with --yes.

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 (TeamCity 2026.1 and newer), the CLI opens your browser to approve access automatically. Otherwise (TeamCity servers older than 2026.1), you will need to manually issue a new access token on your TeamCity user profile page.
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.