README
¶
TeamCity CLI
Note: this is an experimental project. Team projects are created by JetBrains employees. These projects include 20% projects, internal hackathons, those that support product development process, and/or benefit the JetBrains developer community. Team Projects are available for all to use in accordance to the licensing terms, despite not being officially supported. However, there are times that Team Projects become Official Projects.
A command-line interface for TeamCity that lets you manage builds, jobs, and projects without leaving your terminal.
TABLE OF CONTENTS
Why tc?
- Stay in your terminal – Start builds, check statuses, and view logs without switching to a browser
- Scriptable automation – Integrate TeamCity into shell scripts, CI pipelines, and git hooks with simple commands
- Quick access to logs – Stream build output or fetch logs with
tc run log, no clicking through UI panels - Manage at scale – List, filter, and batch-operate on runs and jobs across projects
- JSON output – Pipe to
jqfor custom filtering; use--plainfor awk/grep-friendly output - Escape hatch available –
tc apicommand gives you direct REST API access when you need it
For AI Agents
An Agent Skill is available for AI coding assistants like Claude Code. The skill teaches agents how to use tc for common TeamCity workflows - investigating build failures, starting builds, exploring projects, and more.
Claude Code users:
# Add this repository as a plugin marketplace
/plugin marketplace add JetBrains/teamcity-cli
# Install the skill
/plugin install teamcity-cli@teamcity-cli
The skill is located in skills/teamcity-cli/ and follows the Agent Skills specification.
Installation
macOS & Linux
Homebrew (recommended):
brew install jetbrains/utils/tc
Install script:
curl -fsSL https://jb.gg/tc/install | bash
Debian/Ubuntu:
curl -fsSLO https://github.com/JetBrains/teamcity-cli/releases/latest/download/tc_linux_amd64.deb
sudo dpkg -i tc_linux_amd64.deb
RHEL/Fedora:
sudo rpm -i https://github.com/JetBrains/teamcity-cli/releases/latest/download/tc_linux_amd64.rpm
Arch Linux:
curl -fsSLO https://github.com/JetBrains/teamcity-cli/releases/latest/download/tc_linux_amd64.pkg.tar.zst
sudo pacman -U tc_linux_amd64.pkg.tar.zst
Install script:
curl -fsSL https://jb.gg/tc/install | bash
Windows
Scoop:
scoop bucket add jetbrains https://github.com/JetBrains/scoop-utils
scoop install tc
Go
go install github.com/JetBrains/teamcity-cli/tc@latest
Build from source
git clone https://github.com/JetBrains/teamcity-cli.git
cd teamcity-cli
go build -o tc ./tc
Quick Start
# Authenticate with your TeamCity server
tc auth login
# List recent builds
tc run list --limit 10
# Start a build and watch it run
tc run start MyProject_Build --branch main --watch
# View logs from the latest build of a job
tc run log --job MyProject_Build
# Check what's in the queue
tc queue list
Commands
| Command | Description |
|---|---|
| auth | |
tc auth login |
Authenticate with a TeamCity server |
tc auth logout |
Log out from the current server |
tc auth status |
Show authentication status |
| run | |
tc run list |
List recent builds |
tc run start |
Start a new build |
tc run view |
View build details |
tc run watch |
Watch a build in real-time |
tc run log |
View build log output |
tc run changes |
Show commits included in a build |
tc run tests |
Show test results |
tc run cancel |
Cancel a running or queued build |
tc run download |
Download artifacts |
tc run restart |
Restart with same configuration |
tc run pin/unpin |
Pin or unpin a build |
tc run tag/untag |
Add or remove tags |
tc run comment |
Set or view build comment |
| job | |
tc job list |
List build configurations |
tc job view |
View job details |
tc job pause/resume |
Pause or resume a job |
tc job param |
Manage job parameters |
| project | |
tc project list |
List projects |
tc project view |
View project details |
tc project param |
Manage project parameters |
tc project token |
Manage secure tokens |
| queue | |
tc queue list |
List queued builds |
tc queue approve |
Approve a queued build |
tc queue remove |
Remove from queue |
tc queue top |
Move to top of queue |
| api | |
tc api |
Make raw API requests |
Configuration
Configuration is stored in ~/.config/tc/config.yml:
default_server: https://teamcity.example.com
servers:
https://teamcity.example.com:
token: <your-token>
user: username
Multiple Servers
You can authenticate with multiple TeamCity servers. Each server's credentials are stored separately.
Adding servers:
# Log in to your first server
tc auth login --server https://teamcity1.example.com
# Log in to additional servers (becomes the new default)
tc auth login --server https://teamcity2.example.com
Switching between servers:
# Option 1: Use environment variable (recommended for scripts)
TEAMCITY_URL=https://teamcity1.example.com tc run list
# Option 2: Export for your session
export TEAMCITY_URL=https://teamcity1.example.com
tc run list # uses teamcity1
tc auth status # shows teamcity1
# Option 3: Log in again to change the default
tc auth login --server https://teamcity1.example.com
Example multi-server config:
default_server: https://teamcity-prod.example.com
servers:
https://teamcity-prod.example.com:
token: <token>
user: alice
https://teamcity-staging.example.com:
token: <token>
user: alice
https://teamcity-dev.example.com:
token: <token>
user: alice
CI/CD usage:
Environment variables always take precedence over config file settings:
export TEAMCITY_URL="https://teamcity.example.com"
export TEAMCITY_TOKEN="your-access-token"
tc run start MyProject_Build # uses env vars, ignores config file
Shell Completion
# Bash
tc completion bash > /etc/bash_completion.d/tc
# Zsh
tc completion zsh > "${fpath[1]}/_tc"
# Fish
tc completion fish > ~/.config/fish/completions/tc.fish
# PowerShell
tc completion powershell > tc.ps1
Global Flags
-h, --help– Help for command-v, --version– Version information--no-color– Disable colored output-q, --quiet– Suppress non-essential output--verbose– Show detailed output including debug info--no-input– Disable interactive prompts
JSON Output
Commands that list resources (run list, job list, project list, queue list) support a --json flag with field selection:
# Default fields (default selection covering most use cases)
tc run list --json
# List available fields for a command
tc run list --json=
# Select specific fields
tc run list --json=id,status,webUrl
# Use dot notation for nested fields
tc run list --json=id,status,buildType.name,triggered.user.username
Field notation:
Use dot notation to access nested fields. For example, buildType.name retrieves the build configuration name, and triggered.user.username gets the username of who triggered the build.
Available fields by command:
| Command | Example fields |
|---|---|
run list |
id, number, status, state, branchName, buildTypeId, buildType.name, buildType.projectName, triggered.type, triggered.user.name, agent.name, startDate, finishDate, webUrl |
job list |
id, name, projectName, projectId, paused, href, webUrl |
project list |
id, name, description, parentProjectId, href, webUrl |
queue list |
id, buildTypeId, state, branchName, queuedDate, buildType.name, triggered.user.name, webUrl |
Run tc <command> --json= to see all available fields for that command.
Scripting examples:
# Get build IDs that failed
tc run list --status failure --json=id | jq -r '.[].id'
# Export runs to CSV
tc run list --json=id,status,branchName | jq -r '.[] | [.id,.status,.branchName] | @csv'
# Get web URLs for queued builds
tc queue list --json=webUrl | jq -r '.[].webUrl'
Authentication
auth login
Authenticate with a TeamCity server using an access token.
This will:
- Prompt for your TeamCity server URL
- Open your browser to generate an access token
- Validate and store the token securely
For CI/CD, use environment variables instead: export TEAMCITY_URL="https://teamcity.example.com" export TEAMCITY_TOKEN="your-access-token"
Options:
-s, --server– TeamCity server URL-t, --token– Access token
auth logout
Log out from a TeamCity server
auth status
Show authentication status
Runs
run cancel
Cancel a running or queued run.
tc run cancel 12345
tc run cancel 12345 --comment "Cancelling for hotfix"
tc run cancel 12345 --force
Options:
--comment– Comment for cancellation-f, --force– Skip confirmation prompt
run changes
Show the VCS changes (commits) included in a run.
tc run changes 12345
tc run changes 12345 --no-files
tc run changes 12345 --json
Options:
--json– Output as JSON--no-files– Hide file list, show commits only
run comment
Set, view, or delete a comment on a run.
Without a comment argument, displays the current comment. With a comment argument, sets the comment. Use --delete to remove the comment.
tc run comment 12345
tc run comment 12345 "Deployed to production"
tc run comment 12345 --delete
Options:
--delete– Delete the comment
run download
Download artifacts from a completed run.
tc run download 12345
tc run download 12345 --dir ./artifacts
tc run download 12345 --artifact "*.jar"
Options:
-a, --artifact– Artifact name pattern to download-d, --dir– Directory to download artifacts to
run list
List recent runs
tc run list
tc run list --job Falcon_Build
tc run list --status failure --limit 10
tc run list --project Falcon --branch main
tc run list --since 24h
tc run list --json
tc run list --json=id,status,webUrl
tc run list --plain | grep failure
Options:
-b, --branch– Filter by branch name-j, --job– Filter by job ID--json– Output JSON with fields (use --json= to list, --json=f1,f2 for specific)-n, --limit– Maximum number of runs--no-header– Omit header row (use with --plain)--plain– Output in plain text format for scripting-p, --project– Filter by project ID--since– Filter builds finished after this time (e.g., 24h, 2026-01-21)--status– Filter by status (success, failure, running)--until– Filter builds finished before this time (e.g., 12h, 2026-01-22)-u, --user– Filter by user who triggered-w, --web– Open in browser
run log
View the log output from a run.
You can specify a run ID directly, or use --job to get the latest run's log.
Pager: / search, n/N next/prev, g/G top/bottom, q quit. Use --raw to bypass the pager.
tc run log 12345
tc run log 12345 --failed
tc run log --job Falcon_Build
Options:
--failed– Show only failed step logs-j, --job– Get log for latest run of this job--raw– Show raw log without formatting
run pin
Pin a run to prevent it from being automatically cleaned up by retention policies.
tc run pin 12345
tc run pin 12345 --comment "Release candidate"
Options:
-m, --comment– Comment explaining why the run is pinned
run restart
Restart a run with the same configuration.
tc run restart 12345
tc run restart 12345 --watch
Options:
--watch– Watch the new run after restarting-w, --web– Open run in browser
run start
Start a new run
tc run start Falcon_Build
tc run start Falcon_Build --branch feature/test
tc run start Falcon_Build -P version=1.0 -S build.number=123 -E CI=true
tc run start Falcon_Build --comment "Release build" --tag release --tag v1.0
tc run start Falcon_Build --clean --rebuild-deps --top
tc run start Falcon_Build --local-changes # personal build with uncommitted Git changes
tc run start Falcon_Build --local-changes changes.patch # from file
tc run start Falcon_Build --dry-run
Options:
--agent– Run on specific agent (by ID)-b, --branch– Branch to build--clean– Clean sources before run-m, --comment– Run comment-n, --dry-run– Show what would be triggered without running-E, --env– Environment variables (key=value)--json– Output as JSON (for scripting)-l, --local-changes– Include local changes (git, -, or path; default: git)-P, --param– Build parameters (key=value)--personal– Run as personal build--rebuild-deps– Rebuild all dependencies--rebuild-failed-deps– Rebuild failed/incomplete dependencies-S, --system– System properties (key=value)-t, --tag– Run tags (can be repeated)--top– Add to top of queue--watch– Watch run until it completes-w, --web– Open run in browser
run tag
Add one or more tags to a run for categorization and filtering.
tc run tag 12345 release
tc run tag 12345 release v1.0 production
run tests
Show test results from a run.
You can specify a run ID directly, or use --job to get the latest run's tests.
tc run tests 12345
tc run tests 12345 --failed
tc run tests --job Falcon_Build
Options:
--failed– Show only failed tests-j, --job– Get tests for latest run of this job--json– Output as JSON-n, --limit– Maximum number of tests to show
run unpin
Remove the pin from a run, allowing it to be cleaned up by retention policies.
tc run unpin 12345
run untag
Remove one or more tags from a run.
tc run untag 12345 release
tc run untag 12345 release v1.0
run view
View run details
tc run view 12345
tc run view 12345 --web
tc run view 12345 --json
Options:
--json– Output as JSON-w, --web– Open in browser
run watch
Watch a run in real-time until it completes.
tc run watch 12345
tc run watch 12345 --interval 10
tc run watch 12345 --logs
Options:
-i, --interval– Refresh interval in seconds--logs– Stream build logs while watching
Jobs
job list
List jobs
tc job list
tc job list --project Falcon
tc job list --json
tc job list --json=id,name,webUrl
Options:
--json– Output JSON with fields (use --json= to list, --json=f1,f2 for specific)-n, --limit– Maximum number of jobs-p, --project– Filter by project ID
job param delete
Delete a parameter from a job.
tc job param delete MyID MY_PARAM
job param get
Get the value of a specific job parameter.
tc job param get MyID MY_PARAM
tc job param get MyID VERSION
job param list
List all parameters for a job.
tc job param list MyID
tc job param list MyID --json
Options:
--json– Output as JSON
job param set
Set or update a job parameter value.
tc job param set MyID MY_PARAM "my value"
tc job param set MyID SECRET_KEY "****" --secure
Options:
--secure– Mark as secure/password parameter
job pause
Pause a job to prevent new runs from being triggered.
tc job pause Falcon_Build
job resume
Resume a paused job to allow new runs.
tc job resume Falcon_Build
job view
View job details
tc job view Falcon_Build
tc job view Falcon_Build --web
Options:
--json– Output as JSON-w, --web– Open in browser
Projects
project list
List all TeamCity projects.
tc project list
tc project list --parent Falcon
tc project list --json
tc project list --json=id,name,webUrl
Options:
--json– Output JSON with fields (use --json= to list, --json=f1,f2 for specific)-n, --limit– Maximum number of projects-p, --parent– Filter by parent project ID
project param delete
Delete a parameter from a project.
tc project param delete MyID MY_PARAM
project param get
Get the value of a specific project parameter.
tc project param get MyID MY_PARAM
tc project param get MyID VERSION
project param list
List all parameters for a project.
tc project param list MyID
tc project param list MyID --json
Options:
--json– Output as JSON
project param set
Set or update a project parameter value.
tc project param set MyID MY_PARAM "my value"
tc project param set MyID SECRET_KEY "****" --secure
Options:
--secure– Mark as secure/password parameter
project token get
Retrieve the original value for a secure token.
This operation requires CHANGE_SERVER_SETTINGS permission, which is only available to System Administrators.
tc project token get Falcon "credentialsJSON:abc123..."
tc project token get Falcon "abc123..."
project token put
Store a sensitive value and get a secure token reference.
The returned token can be used in versioned settings configuration files as credentialsJSON:. The actual value is stored securely in TeamCity and is not committed to version control.
Requires EDIT_PROJECT permission (Project Administrator role).
# Store a secret interactively (prompts for value)
tc project token put Falcon
# Store a secret from a value
tc project token put Falcon "my-secret-password"
# Store a secret from stdin (useful for piping)
echo -n "my-secret" | tc project token put Falcon --stdin
# Use the token in versioned settings
# password: credentialsJSON:<returned-token>
Options:
--stdin– Read value from stdin
project view
View details of a TeamCity project.
tc project view Falcon
tc project view Falcon --web
Options:
--json– Output as JSON-w, --web– Open in browser
Queues
queue approve
Approve a queued run that requires manual approval before it can run.
tc queue approve 12345
queue list
List all runs in the TeamCity queue.
tc queue list
tc queue list --job Falcon_Build
tc queue list --json
tc queue list --json=id,state,webUrl
Options:
-j, --job– Filter by job ID--json– Output JSON with fields (use --json= to list, --json=f1,f2 for specific)-n, --limit– Maximum number of queued runs
queue remove
Remove a queued run from the TeamCity queue.
tc queue remove 12345
tc queue remove 12345 --force
Options:
-f, --force– Skip confirmation prompt
queue top
Move a queued run to the top of the queue, giving it highest priority.
tc queue top 12345
Agents
agent authorize
Authorize an agent to allow it to connect and run builds.
tc agent authorize 1
agent deauthorize
Deauthorize an agent to revoke its permission to connect.
tc agent deauthorize 1
agent disable
Disable an agent to prevent it from running builds.
tc agent disable 1
agent enable
Enable an agent to allow it to run builds.
tc agent enable 1
agent jobs
List build configurations (jobs) that are compatible or incompatible with an agent.
tc agent jobs 1
tc agent jobs 1 --incompatible
tc agent jobs 1 --json
Options:
--incompatible– Show incompatible jobs with reasons--json– Output as JSON
agent list
List build agents
tc agent list
tc agent list --pool Default
tc agent list --connected
tc agent list --json
tc agent list --json=id,name,connected,enabled
Options:
--authorized– Show only authorized agents--connected– Show only connected agents--enabled– Show only enabled agents--json– Output JSON with fields (use --json= to list, --json=f1,f2 for specific)-n, --limit– Maximum number of agents-p, --pool– Filter by agent pool
agent move
Move an agent to a different agent pool.
tc agent move 1 0
tc agent move 1 2
agent view
View agent details
tc agent view 1
tc agent view 1 --web
tc agent view 1 --json
Options:
--json– Output as JSON-w, --web– Open in browser
Agent Pools
pool link
Link a project to an agent pool, allowing the project's builds to run on agents in that pool.
tc pool link 1 MyProject
pool list
List agent pools
tc pool list
tc pool list --json
tc pool list --json=id,name,maxAgents
Options:
--json– Output JSON with fields (use --json= to list, --json=f1,f2 for specific)
pool unlink
Unlink a project from an agent pool, removing the project's access to agents in that pool.
tc pool unlink 1 MyProject
pool view
View pool details
tc pool view 0
tc pool view 1 --web
tc pool view 1 --json
Options:
--json– Output as JSON-w, --web– Open in browser
API
Make an authenticated HTTP request to the TeamCity REST API.
The endpoint argument should be the path portion of the URL, starting with /app/rest/. The base URL and authentication are handled automatically.
This command is useful for:
- Accessing API features not yet supported by the CLI
- Scripting and automation
- Debugging and exploration
# Get server info
tc api /app/rest/server
# List projects
tc api /app/rest/projects
# Create a resource with POST
tc api /app/rest/buildQueue -X POST -f 'buildType=id:MyBuild'
# Fetch all pages and combine into array
tc api /app/rest/builds --paginate --slurp
Options:
-f, --field– Add a body field as key=value (builds JSON object)-H, --header– Add a custom header (can be repeated)-i, --include– Include response headers in output--input– Read request body from file (use - for stdin)-X, --method– HTTP method to use--paginate– Make additional requests to fetch all pages--raw– Output raw response without formatting--silent– Suppress output on success--slurp– Combine paginated results into a JSON array (requires --paginate)
License
Apache-2.0
Directories