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
- Stay in your terminal – Start builds, check statuses, and view logs without context-switching to a browser
- Remote agent terminal – Open an interactive shell to any build agent with
tc agent term, or run commands remotely withtc agent exec - Stream logs in real-time – Watch builds as they happen with
tc run watch --logs, or fetch logs instantly withtc run log - Scriptable automation – Integrate TeamCity into shell scripts, CI pipelines, and git hooks with simple commands
- Manage at scale – List, filter, and batch-operate on runs, jobs, agents, and pools across projects
- JSON output – Pipe to
jqfor custom filtering; use--plainfor awk/grep-friendly output - Full API access –
tc apigives you direct REST API access when you need it
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-cliThe skill is located in skills/teamcity-cli/ and follows the Agent Skills specification.
Homebrew (recommended):
brew install jetbrains/utils/tcInstall script:
curl -fsSL https://jb.gg/tc/install | bashDebian/Ubuntu:
curl -fsSLO https://github.com/JetBrains/teamcity-cli/releases/latest/download/tc_linux_amd64.deb
sudo dpkg -i tc_linux_amd64.debRHEL/Fedora:
sudo rpm -i https://github.com/JetBrains/teamcity-cli/releases/latest/download/tc_linux_amd64.rpmArch 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.zstInstall script:
curl -fsSL https://jb.gg/tc/install | bashScoop:
scoop bucket add jetbrains https://github.com/JetBrains/scoop-utils
scoop install tcgo install github.com/JetBrains/teamcity-cli/tc@latestgit clone https://github.com/JetBrains/teamcity-cli.git
cd teamcity-cli
go build -o tc ./tc# 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| 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 is stored in ~/.config/tc/config.yml:
default_server: https://teamcity.example.com
servers:
https://teamcity.example.com:
token: <your-token>
user: usernameYou 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.comSwitching 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.comExample 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: aliceCI/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# 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-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
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.usernameField 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'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"
When running inside a TeamCity build, authentication is automatic using build-level credentials from the build properties file.
Options:
-s, --server– TeamCity server URL-t, --token– Access token
Log out from a TeamCity server
Show authentication status
Cancel a running or queued run.
tc run cancel 12345
tc run cancel 12345 --comment "Cancelling for hotfix"
tc run cancel 12345 --forceOptions:
--comment– Comment for cancellation-f, --force– Skip confirmation prompt
Show the VCS changes (commits) included in a run.
tc run changes 12345
tc run changes 12345 --no-files
tc run changes 12345 --jsonOptions:
--json– Output as JSON--no-files– Hide file list, show commits only
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 --deleteOptions:
--delete– Delete the comment
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
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 failureOptions:
-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
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_BuildOptions:
--failed– Show only failed step logs-j, --job– Get log for latest run of this job--raw– Show raw log without formatting
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
Restart a run with the same configuration.
tc run restart 12345
tc run restart 12345 --watchOptions:
--watch– Watch the new run after restarting-w, --web– Open run in browser
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-runOptions:
--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)--no-push– Skip auto-push of branch to remote-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
Add one or more tags to a run for categorization and filtering.
tc run tag 12345 release
tc run tag 12345 release v1.0 productionShow 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_BuildOptions:
--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
Remove the pin from a run, allowing it to be cleaned up by retention policies.
tc run unpin 12345Remove one or more tags from a run.
tc run untag 12345 release
tc run untag 12345 release v1.0View run details
tc run view 12345
tc run view 12345 --web
tc run view 12345 --jsonOptions:
--json– Output as JSON-w, --web– Open in browser
Watch a run in real-time until it completes.
tc run watch 12345
tc run watch 12345 --interval 10
tc run watch 12345 --logsOptions:
-i, --interval– Refresh interval in seconds--logs– Stream build logs while watching
List jobs
tc job list
tc job list --project Falcon
tc job list --json
tc job list --json=id,name,webUrlOptions:
--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
Delete a parameter from a job.
tc job param delete MyID MY_PARAMGet the value of a specific job parameter.
tc job param get MyID MY_PARAM
tc job param get MyID VERSIONList all parameters for a job.
tc job param list MyID
tc job param list MyID --jsonOptions:
--json– Output as JSON
Set or update a job parameter value.
tc job param set MyID MY_PARAM "my value"
tc job param set MyID SECRET_KEY "****" --secureOptions:
--secure– Mark as secure/password parameter
Pause a job to prevent new runs from being triggered.
tc job pause Falcon_BuildResume a paused job to allow new runs.
tc job resume Falcon_BuildView job details
tc job view Falcon_Build
tc job view Falcon_Build --webOptions:
--json– Output as JSON-w, --web– Open in browser
List all TeamCity projects.
tc project list
tc project list --parent Falcon
tc project list --json
tc project list --json=id,name,webUrlOptions:
--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
Delete a parameter from a project.
tc project param delete MyID MY_PARAMGet the value of a specific project parameter.
tc project param get MyID MY_PARAM
tc project param get MyID VERSIONList all parameters for a project.
tc project param list MyID
tc project param list MyID --jsonOptions:
--json– Output as JSON
Set or update a project parameter value.
tc project param set MyID MY_PARAM "my value"
tc project param set MyID SECRET_KEY "****" --secureOptions:
--secure– Mark as secure/password parameter
Export project settings as a ZIP archive containing Kotlin DSL or XML configuration.
The exported archive can be used to:
- Version control your CI/CD configuration
- Migrate settings between TeamCity instances
- Review settings as code
By default, exports in Kotlin DSL format.
# Export as Kotlin DSL (default)
tc project settings export MyProject
# Export as Kotlin DSL explicitly
tc project settings export MyProject --kotlin
# Export as XML
tc project settings export MyProject --xml
# Save to specific file
tc project settings export MyProject -o settings.zipOptions:
--kotlin– Export as Kotlin DSL (default)-o, --output– Output file path (default: projectSettings.zip)--relative-ids– Use relative IDs in exported settings--xml– Export as XML
Show the synchronization status of versioned settings for a project.
Displays:
- Whether versioned settings are enabled
- Current sync state (up-to-date, pending changes, errors)
- Last successful sync timestamp
- VCS root and format information
- Any warnings or errors from the last sync attempt
tc project settings status MyProject
tc project settings status MyProject --jsonOptions:
--json– Output as JSON
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..."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
View details of a TeamCity project.
tc project view Falcon
tc project view Falcon --webOptions:
--json– Output as JSON-w, --web– Open in browser
Approve a queued run that requires manual approval before it can run.
tc queue approve 12345List 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,webUrlOptions:
-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
Remove a queued run from the TeamCity queue.
tc queue remove 12345
tc queue remove 12345 --forceOptions:
-f, --force– Skip confirmation prompt
Move a queued run to the top of the queue, giving it highest priority.
tc queue top 12345Authorize an agent to allow it to connect and run builds.
tc agent authorize 1Deauthorize an agent to revoke its permission to connect.
tc agent deauthorize 1Disable an agent to prevent it from running builds.
tc agent disable 1Enable an agent to allow it to run builds.
tc agent enable 1Execute a command on a TeamCity build agent and return the output.
tc agent exec 1 "ls -la"
tc agent exec 42 "cat /etc/os-release"
tc agent exec 1 --timeout 10m -- long-running-script.shOptions:
--timeout– Command timeout
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 --jsonOptions:
--incompatible– Show incompatible jobs with reasons--json– Output as JSON
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,enabledOptions:
--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
Move an agent to a different agent pool.
tc agent move 1 0
tc agent move 1 2Open an interactive shell session to a TeamCity build agent.
tc agent term 1
tc agent term 42View agent details
tc agent view 1
tc agent view 1 --web
tc agent view 1 --jsonOptions:
--json– Output as JSON-w, --web– Open in browser
Link a project to an agent pool, allowing the project's builds to run on agents in that pool.
tc pool link 1 MyProjectList agent pools
tc pool list
tc pool list --json
tc pool list --json=id,name,maxAgentsOptions:
--json– Output JSON with fields (use --json= to list, --json=f1,f2 for specific)
Unlink a project from an agent pool, removing the project's access to agents in that pool.
tc pool unlink 1 MyProjectView pool details
tc pool view 0
tc pool view 1 --web
tc pool view 1 --jsonOptions:
--json– Output as JSON-w, --web– Open in browser
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 --slurpOptions:
-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)
Apache-2.0
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
