$ teamcity From the Command Line

Start builds, tail logs, and manage agents and queues – without switching windows.

Whether you are debugging a failed build, managing build agents, or scripting your deployment pipeline (or your AI coding agent is doing so) – there are times when opening a browser is one step too many.

TeamCity CLI is a lightweight, open-source tool that puts TeamCity at your fingertips. 

A CLI for TeamCity has been a long-standing request from the community. Here’s how it works and what you can use it for.

TeamCity CLI includes over 60 commands, and for anything it doesn't wrap yet, teamcity api gives you direct access to the full TeamCity REST API.

Source code (Apache 2.0): https://github.com/JetBrains/teamcity-cli

Getting started

Install and authenticate in seconds:

# macOS / Linux
brew install jetbrains/utils/teamcity

# via a bash script
curl -fsSL https://jb.gg/tc/install | bash

# Windows
winget install JetBrains.tc

# via a powershell script
irm https://jb.gg/tc/install.ps1 | iex

# Connect to your server
teamcity auth login https://example.teamcity.com/

That's all! Now let’s see it in action.

Investigating a failed build

Let’s say something breaks. Here’s how to go from wondering what happened to having it fixed without switching windows.

See what's happening

teamcity run list --all

Build 1389 failed. Here’s how we can drill down:

teamcity run view 1389

Need to jump to the TeamCity UI instead? Add --web.

Find the root cause

You don't need to scroll through the entire log. Show only the failed step, then the failed tests:

teamcity run log 1389 --failed

Only one test failed, so you know exactly what to fix.

Fix and re-trigger

After you push the fix, restart and watch it in real time:

teamcity run restart 1389
teamcity run watch 1408 --logs

You see all the updates happening live in your terminal – build state changes, step progress, and streaming log output.

Test before you push

Want to validate your changes with CI before committing to a push? Run a personal build with your local changes:

teamcity run start Sandbox_Test --local-changes

TeamCity runs the build with your uncommitted work applied as a patch – no branch, no force-push, no noise in the repo.

Remote agent access

You can open an interactive shell session on any build agent – or execute commands remotely:

teamcity agent list
teamcity agent term 813

No SSH keys to manage, no VPN to connect – if your TeamCity server can reach the agent, so can you.

Need to just run a quick command? Here’s how:

teamcity agent exec 813 "docker ps -a"

Built for scripting

teamcity covers queues, agents, artifacts, and project configuration – the commands look exactly as you’d expect:

teamcity queue list                                          # what's queued
teamcity queue top 461                                       # move a build to the front
teamcity queue approve 462                                   # approve a waiting build

teamcity agent list                                          # all agents with status
teamcity agent disable "Linux Agent 03" --comment "Maint"    # take one offline

teamcity run artifacts 453                                   # browse artifacts
teamcity run download 453 "reports/**/*.html" --output ./out # grab what you need

# Restart all failed builds on main
teamcity run list --failed --branch main --plain=id | xargs -I{} tc run restart {}

# Structured data for dashboards or scripts
teamcity run list --failed --json=id,status,buildType.name

# Hit any REST API endpoint directly
teamcity api /app/rest/server

Every list command supports --json with field selection and --plain for tab-delimited text – making teamcity a building block for automation.

teamcity api is the escape hatch – anything the CLI doesn't wrap yet, you can call directly.

Compatible with AI coding agents

TeamCity CLI ships with an Agent Skill that teaches AI coding assistants how to use the tool. Your AI agent can then check the build status, investigate failures, download artifacts, and manage your pipeline on your behalf.

Users should limit the token rights granted to the agent, be aware of security implications, and always check the actions the agent intends to execute.

What's next

TeamCity CLI is open-source under Apache 2.0. There's more we want to build – for example, pipeline visualization, richer TUI interfaces, and deeper integration with version control workflows. Your feedback will shape what comes next.

Try it

brew install jetbrains/utils/teamcity       # macOS
winget install JetBrains.TeamCityCLI        # Windows
curl -fsSL https://jb.gg/tc/install | bash  # Linux/macOS setup script
irm https://jb.gg/tc/install.ps1 | iex      # Windows setup script

Source code and docs: github.com/JetBrains/teamcity-cli

Report issues or request features: GitHub Issues