TeamCity CLI
JetBrains' official TeamCity CLI: start builds, tail logs, check the queue and shell into an agent from a terminal.
- 130 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- `agent exec` and `agent term` give a remote shell on build agents, not just build and queue management.
Install
- Works in
Manual install
brew install jetbrains/utils/teamcityThe first install method from the README, for macOS. Linux uses `curl -fsSL https://jb.gg/tc/install | bash`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- `agent exec` and `agent term` give a remote shell on build agents, not just build and queue management.
This is third-party code. Review the repository files before installing.
What it does
TeamCity CLI gives TeamCity a command line: sign in once (`teamcity auth login`), and the CLI remembers the server for later calls. Commands are grouped by entity — `run` starts and inspects builds, `job` manages build configurations, `project` handles VCS connections and cloud profiles, `queue` shows and edits the build queue, `agent` gives a shell and controls build agents, `pipeline` validates and moves YAML configurations between projects. Every command supports `--json` or `--plain` for scripting and `--web` to open the matching TeamCity UI page. Anything the CLI doesn't cover goes through `teamcity api` straight to the REST API. The `teamcity skill install` command installs a skill that teaches AI agents (Claude Code, Cursor and others) how to drive this CLI.
Who it is for. Engineers running TeamCity who need to start and track builds, read logs and manage agents without switching to the browser.
Good fit when
- A build failed, and the log and change diffs need checking right away without opening the web UI.
- An agent is working on a task and needs to start a build itself, wait for the result and read test output via the CLI.
- The queue is backed up and needs a quick look at what's in it, plus a priority bump for one build.
- A pipeline configuration needs moving between projects and validating before it's pushed.
Not a fit when
- There is no TeamCity server in play: the CLI only works with it and is not a REST API replacement.
- Only read-only build status is needed with no permission to start builds or manage agents — `TEAMCITY_RO=1` blocks writes for that case.
- Security takes priority and remote shell access to agents (`agent exec`, `agent term`) should not exist at all — restrict permissions server-side instead.
Example request
Start build MyProject_Build on branch main, wait for it to finish, and show the log of the last failed step.Limitations
`TEAMCITY_RO=1` blocks writes and remote shell on the CLI side, but it is not a substitute for server-side permissions, which are the real security boundary. `teamcity run download` only writes inside `--output` and leaves existing files untouched after a failed transfer. Redirects never downgrade HTTPS to HTTP or forward request headers to another origin. Cross-origin artifact downloads carry their own restrictions. The current version and changelog live on GitHub Releases; installing via deb, rpm, AUR, Chocolatey or Scoop depends on a third-party package manager.
How to disable. Run `teamcity auth logout`, then remove the binary the way it was installed (`brew uninstall jetbrains/utils/teamcity`, `sudo dpkg -r teamcity`, and similar). The agent skill is removed with `teamcity skill remove`.
FAQ
How do I install TeamCity CLI on macOS?
Via Homebrew: `brew install jetbrains/utils/teamcity`. On Linux, `curl -fsSL https://jb.gg/tc/install | bash` works, and the script also runs on macOS.
How do I connect the CLI to an AI agent like Claude Code?
`teamcity skill install` auto-detects installed agents and installs the skill. Claude Code also has a dedicated plugin via `/plugin marketplace add JetBrains/teamcity-skills` and `/plugin install teamcity@teamcity`, but it doesn't replace the CLI itself.
How do I restrict the CLI to read-only?
`TEAMCITY_RO=1` blocks writes and the `agent exec`/`agent term` commands. The real security boundary still needs to be server-side permissions, not just this variable.
What does teamcity run view show for a queued build?
Agent and cloud-image compatibility, including unmet requirements when the server supports it. For large agent pools, use `--json` and read the `.compatibility` field per entry.
Why does TeamCity say run and job instead of build and configuration?
That's the CLI's own terminology: TeamCity calls these entities build and build configuration, the CLI calls them run and job. The full mapping is in JetBrains' documentation glossary.
Discussion
No questions or reviews yet.
Related
CLI toolsCircleCI CLI
circleci-cli
The official CircleCI CLI shows runs and failing-test logs, while skills and MCP connect it to Claude Code, Codex and Cursor.
The Railway hosting CLI: deploy and manage projects, plus one command that installs Railway skills and MCP for your agents
Official Dynatrace CLI with kubectl-style syntax and a bundled skill: workflows, dashboards, DQL queries and SLOs
A Rust CLI and MCP server for the local 1C development loop: builds, syntax checks, YAxUnit and Vanessa tests, dumping changes
Docker’s terminal client connects agent commands to containers, images, networks and volumes in the selected environment.
Official Dynatrace skills for agents: DQL, traces, logs, Kubernetes, cloud and security work inside Claude Code and Cursor.
README in short
The README tables every command group and walks through real-world flows: binding a repository to a TeamCity project via `teamcity.toml`, command aliases, and browser sign-in with no terminal for scripts.