README
¶
TeamCity CLI
teamcity is the official command-line client for TeamCity. It covers the day-to-day — starting builds, tailing logs, digging through the queue — and the odd jobs too: shelling into build agents, editing job settings, raw REST calls when nothing else fits.
Full documentation, including installation, authentication, and a command reference, lives at jb.gg/tc/docs.
Install
macOS (Homebrew):
brew install jetbrains/utils/teamcity
Linux:
curl -fsSL https://jb.gg/tc/install | bash
Windows (Winget):
winget install JetBrains.TeamCityCLI
npm:
npm install -g @jetbrains/teamcity-cli
More installation methods (deb, rpm, Chocolatey, Scoop, build from source)
Debian/Ubuntu:
curl -fsSLO https://github.com/JetBrains/teamcity-cli/releases/latest/download/teamcity_linux_amd64.deb
sudo dpkg -i teamcity_linux_amd64.deb
RHEL/Fedora:
sudo rpm -i https://github.com/JetBrains/teamcity-cli/releases/latest/download/teamcity_linux_amd64.rpm
Arch Linux (AUR):
yay -S teamcity-bin
PowerShell:
irm https://jb.gg/tc/install.ps1 | iex
CMD:
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:
go install github.com/JetBrains/teamcity-cli/tc@latest
See the getting started guide for the full walkthrough.
Usage
Log in once and the CLI remembers the server:
teamcity auth login
Then:
# my latest build on this branch
teamcity run list --user @me --branch @this --limit 1
# start a build and stay attached to it
teamcity run start MyProject_Build --branch main --watch
# logs from the latest build of a job
teamcity run log --job MyProject_Build
# what's sitting in the queue
teamcity queue list
# shell into a build agent
teamcity agent term Agent-Linux-01
One naming note: TeamCity says build and build configuration; the CLI says run and job. The glossary has the full mapping.
Every command takes --json or --plain for scripting, and --web opens the matching page in the TeamCity UI. When no command covers what you need, teamcity api calls the REST API directly with your stored credentials. You can also log in to several servers and switch between them — see configuration.
Commands
| Group | Commands |
|---|---|
| auth | login, logout, status |
| run | list, start, view, watch, log, tree, changes, tests, diff, cancel, download, artifacts, restart, pin/unpin, tag/untag, comment |
| job | list, view, create, tree, pause/resume, step list/view/add/delete, param list/get/set/delete, settings list/get/set |
| project | list, view, create, tree, vcs list/view/create/test/delete, ssh list/generate/upload/delete, cloud profile/image/instance, connection list/view/create github-app/create docker/authorize/delete, param, token get/put, settings export/status/validate |
| pipeline | list, view, create, validate, pull, push, schema, delete |
| queue | list, approve, remove, top |
| agent | list, view, term, exec, jobs, authorize/deauthorize, enable/disable, move, reboot |
| pool | list, view, link/unlink |
| api | Raw REST API access |
| link | Bind this repository to a TeamCity project via teamcity.toml |
| config | list, get, set |
| alias | set, list, delete |
| skill | list, install, remove, update |
| update | Check for CLI updates |
Run teamcity <command> --help for usage, or see the command reference.
For AI agents
The CLI ships with an Agent Skill that teaches coding agents (Claude Code, Cursor, and others) how to drive teamcity:
teamcity skill install # auto-detects installed agents
teamcity skill install --project # install to current project only
teamcity skill update # update to the version bundled with teamcity
teamcity skill remove # uninstall
or specifically for Claude Code:
/plugin marketplace add JetBrains/teamcity-cli
/plugin install teamcity-cli@teamcity-cli
See AI agent integration for details.
Learn more
- Getting started – install, authenticate, and run your first commands
- Configuration – config file, environment variables, multi-server setup, shell completion
- Scripting and automation – JSON output, plain text mode, CI/CD integration
- Aliases – create custom command shortcuts
Contributing
TeamCity CLI is open source under the Apache-2.0 license. Bug reports and pull requests are welcome — CONTRIBUTING.md covers how the project is built and tested.
Documentation
¶
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
analytics
Package analytics implements the FUS telemetry pipeline for the TeamCity CLI.
|
Package analytics implements the FUS telemetry pipeline for the TeamCity CLI. |
|
atomicfile
Package atomicfile writes files atomically at 0600 so concurrent writers can't interleave and token-bearing data is never exposed at a looser mode.
|
Package atomicfile writes files atomically at 0600 so concurrent writers can't interleave and token-bearing data is never exposed at a looser mode. |
|
browserflow
Package browserflow runs a browser-driven authorization flow over a local HTTP listener.
|
Package browserflow runs a browser-driven authorization flow over a local HTTP listener. |
|
cmd/link
Package link implements `teamcity link`: upsert a [[server]] entry (or a per-path scope inside one) in teamcity.toml.
|
Package link implements `teamcity link`: upsert a [[server]] entry (or a per-path scope inside one) in teamcity.toml. |
|
cmdtest
Package cmdtest provides shared test helpers for CLI command tests.
|
Package cmdtest provides shared test helpers for CLI command tests. |
|
completion
Package completion exposes shell-completion helpers backed by static enums and on-disk config.
|
Package completion exposes shell-completion helpers backed by static enums and on-disk config. |
|
gallery
Package gallery generates the CLI screen gallery using termbook.
|
Package gallery generates the CLI screen gallery using termbook. |
|
git
Package git provides filesystem and shell helpers for interacting with git repositories.
|
Package git provides filesystem and shell helpers for interacting with git repositories. |
|
link
Package link reads and writes teamcity.toml: a committed file binding a repository to one or more TeamCity servers, with optional per-path overrides inside each server entry.
|
Package link reads and writes teamcity.toml: a committed file binding a repository to one or more TeamCity servers, with optional per-path overrides inside each server entry. |
|
Package schemas embeds the JSON Schemas published under schemas/ so the CLI and external consumers share one source of truth.
|
Package schemas embeds the JSON Schemas published under schemas/ so the CLI and external consumers share one source of truth. |