Teamcity Cli
TeamCity from your terminal – or your AI's. Builds, logs, agents, agent terminals, queues.
Last verified:
What is Teamcity Cli?
TeamCity CLI is the official command-line interface for TeamCity CI/CD, developed and maintained by JetBrains TeamCity developers. It is an open-source tool under the Apache 2.0 license that allows developers, DevOps engineers, and CI/CD practitioners to manage TeamCity entirely from the terminal without needing to open a browser. Type teamcity in your terminal to start builds, tail logs, manage agents and queues, and perform over 60 different operations.
Key features include staying in your terminal for all operations, remote agent access via teamcity agent term to shell into any build agent or teamcity agent exec to run commands remotely, real-time log streaming with teamcity run watch --logs, and scriptable output with --json and --plain flags for pipeline integration. The CLI supports multi-server authentication, direct REST API access via teamcity api, and includes a built-in skill for AI coding agents like Claude Code and Cursor that can be installed with teamcity skill install.
The tool is designed for software developers debugging failed builds, DevOps teams managing CI/CD pipelines, SREs monitoring build agents, and AI coding agents automating TeamCity workflows. It enables running personal builds with local changes using teamcity run start --local-changes, managing build queues with priority control, downloading artifacts, exporting project settings as Kotlin DSL or XML, and validating Kotlin DSL configuration.
TeamCity CLI is completely free and open-source under the Apache 2.0 license. There are no paid tiers or subscription plans — the tool is bundled as free software that works with any TeamCity On-Premises instance. The only cost is having a TeamCity server (which has its own licensing), and the CLI itself has no usage restrictions, feature limitations based on payment, or premium tiers.
Teamcity Cli pricing
Pricing model: Freemium
TeamCity CLI is completely free and open-source under the Apache 2.0 license. There are no paid plans, subscription tiers, or feature limitations based on payment. The tool has no usage restrictions and all features are available to everyone. The only requirement is having access to a TeamCity On-Premises server (which has its own separate licensing). Installation methods include Homebrew, Winget, npm, install scripts, Chocolatey, Scoop, deb/rpm packages, or building from source — all free.
Teamcity Cli pros
- Completely free and open-source under Apache 2.0 license
- Stay in terminal — no browser needed for builds, logs, or queue management
- Over 60 commands covering runs, agents, queues, projects, and pipelines
- Remote agent shell access without SSH keys or VPN via teamcity agent term
- Real-time log streaming with teamcity run watch --logs
- Scriptable with --json and --plain output for CI/CD automation
- Direct REST API access via teamcity api for any endpoint
- Multi-server support with easy switching between TeamCity instances
- Built-in AI agent skill for Claude Code, Cursor, and other AI coding assistants
- Run personal builds with local uncommitted changes using --local-changes
- Interactive shell on any build agent if TeamCity server can reach it
- Structured JSON output with field selection for dashboards and scripts
- Supports Homebrew, Winget, npm, Chocolatey, Scoop, deb, rpm installation
- Automatic authentication inside TeamCity builds without token management
- Guest access support for read-only access without credentials
- Export project settings as Kotlin DSL or XML for version control
- Validate Kotlin DSL configuration directly from command line
Teamcity Cli cons
- Not bundled with TeamCity server installers or Docker images — must install separately
- Requires JRE installed for some installation methods (legacy tool reference)
- Plain text token storage fallback in config file if keyring unavailable
- Guest access provides only read-only access, no write operations
- Open-source tool still evolving — some features like pipeline visualization planned but not yet built
- Requires TeamCity server access — cannot function without a TeamCity instance
- Token rights granted to AI agents must be carefully limited for security
- Headless environments require --insecure-storage flag for token storage
Frequently asked questions about Teamcity Cli
What is TeamCity CLI?
TeamCity CLI is the official command-line interface for TeamCity CI/CD. It is an open-source tool developed by JetBrains that lets you start builds, tail logs, manage agents and queues, and perform over 60 operations entirely from your terminal without opening a browser. Type teamcity in your terminal to use it.
Is TeamCity CLI free?
Yes, TeamCity CLI is completely free and open-source under the Apache 2.0 license. There are no paid tiers, subscriptions, or feature restrictions. All features are available to everyone who has access to a TeamCity server.
How do I install TeamCity CLI?
You can install via Homebrew (macOS): brew install jetbrains/utils/teamcity, Winget (Windows): winget install JetBrains.TeamCityCLI, install script (Linux/macOS): curl -fsSL https://jb.gg/tc/install | bash, PowerShell (Windows): irm https://jb.gg/tc/install.ps1 | iex, or npm: npm install -g @jetbrains/teamcity-cli. Other methods include Chocolatey, Scoop, deb/rpm packages, and building from source.
How do I authenticate with TeamCity CLI?
Use teamcity auth login for interactive login — it opens your browser to create an access token which you paste into the terminal. For CI/CD, use environment variables: TEAMCITY_URL and TEAMCITY_TOKEN. For guest access (read-only): teamcity auth login --guest or set TEAMCITY_GUEST=1. Inside TeamCity builds, authentication is automatic using build-level credentials.
Can I use TeamCity CLI with multiple servers?
Yes, you can authenticate with multiple TeamCity servers. Each server's credentials are stored separately. Switch between servers using the TEAMCITY_URL environment variable (recommended for scripts), or log in again with teamcity auth login --server <url> to change the default. Server auto-detection also works from Kotlin DSL when working in a project with versioned settings.
How do I watch a build in real-time?
Use teamcity run start MyProject_Build --branch main --watch to start a build and watch it run, or teamcity run watch <build_id> --logs to stream build output as it happens. You'll see build state changes, step progress, and streaming log output directly in your terminal.
How do I access a build agent remotely?
Use teamcity agent list to see all agents with their status, then teamcity agent term <agent_id> to open an interactive shell session on that agent, or teamcity agent exec <agent_id> "command" to run a specific command remotely. No SSH keys or VPN needed — if your TeamCity server can reach the agent, so can you.
How does AI agent integration work?
TeamCity CLI includes a built-in skill for AI coding agents like Claude Code and Cursor. Run teamcity skill install to auto-detect installed agents and install the skill, or teamcity skill install --project for current project only. The AI agent can then check build status, investigate failures, download artifacts, and manage pipelines. Users should limit token rights granted to agents and check actions the agent intends to execute.
How do I run a personal build with local changes?
Use teamcity run start <build_type> --local-changes to run a personal build with your uncommitted work applied as a patch. This tests your changes with CI before committing — no branch needed, no force-push, no noise in the repo. Your local modified files are matched to the agent checkout directory via a mapping file.
What output formats are available for scripting?
Every list command supports --json with field selection (e.g., --json=id,status,buildType.name) for structured data in dashboards or scripts, and --plain for tab-delimited text output. Use teamcity run list --failed --json=id,status,buildType.name or pipe --plain=id to xargs for automation. The teamcity api command also returns raw REST API responses.