Generated banner for Teamcity CLI
Generated logo for Teamcity CLI

Teamcity CLI

ClineOfficialPublished by Cline

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • No issues found

From the author

Use when working with TeamCity CI/CD or when a user provides a TeamCity build URL — drives the `teamcity` CLI for builds, logs, jobs, queues, agents, pools, projects, and pipelines.
— the description by Cline

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The teamcity-cli skill provides a comprehensive interface to interact with TeamCity servers directly from the terminal. It enables developers and DevOps engineers to manage the full lifecycle of CI/CD operations, including triggering builds, monitoring logs, managing build configurations, and overseeing agent pools. The tool supports various output formats, including JSON for programmatic integration, and provides specific commands for investigating build failures and managing pipeline configurations.

What it does

  • Authenticates with TeamCity servers and manages session status
  • Lists, starts, watches, and cancels build runs
  • Retrieves build logs, test results, and artifacts
  • Manages build jobs, project settings, and VCS connections
  • Monitors and controls build queues and agent pools
  • Validates and deploys pipeline configurations

When to use it

  • When you need to investigate failed builds or build chains
  • When automating CI/CD tasks via scripts or shell commands
  • When managing TeamCity infrastructure like agents and pools
  • When you need to quickly check the status of a build or queue
  • When performing pipeline configuration management

Advantages

  • Provides direct terminal access to TeamCity functionality
  • Supports JSON output for easy integration with tools like jq
  • Enables deep diagnostics for build failures and dependency trees
  • Allows for non-interactive scripting via environment variables
  • Simplifies management of complex build chains and pipelines

Usage examples

“Find all failed builds in the last 24 hours”
The agent runs teamcity run list --status failure --since 24h to display a list of recent failed builds.
“Show me the logs for build ID 12345”
The agent executes teamcity run log 12345 --raw to retrieve and display the full build log.
“Get the status of all build agents”
The agent runs teamcity agent list to provide a table of all connected agents and their status.
“Validate my pipeline configuration before pushing”
The agent runs teamcity pipeline validate to ensure the local configuration is correct before deployment.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/cline/teamcity-cli/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip teamcity-cli.zip -d .agents/skills

Documentation by Cline

TeamCity CLI (teamcity)

Quick Start

teamcity auth status                    # Check authentication
teamcity run list --status failure      # Find failed builds
teamcity run log <id> --failed --raw    # Full failure diagnostics

Do not guess flags or syntax. Use the command reference or teamcity <command> --help. Builds are runs (teamcity run); build configurations are jobs (teamcity job). Never use --count — use --limit (or -n).

Gotchas

  • Composite builds have empty logs — drill into child builds for the actual failure.

  • Build chains fail bottom-up — deepest failed dependency is the root cause. Use teamcity run tree <id>.

  • --local-changes excludes Kotlin DSL — push .teamcity/ changes before running.

  • TEAMCITY_URL alone bypasses stored auth — set both TEAMCITY_URL and TEAMCITY_TOKEN, or leave unset.

  • Logs: use --raw and dump to a temp file. Builds: use --watch when starting them.

  • VCS triggers aren't always wired up — after pushing a fix you may need to start builds manually.

  • pipeline push does not validate — always teamcity pipeline validate first.

  • GitHub VCS roots: use a GitHub App connection. Never paste a PAT via --auth password. See workflows.

Core Commands

AreaCommands
Authauth login, logout, status
Buildsrun list, view, start, watch, log, cancel, restart, tests, changes, tree
Artifactsrun artifacts, run download
Metadatarun pin/unpin, run tag/untag, run comment
Jobsjob list, view, create, tree, pause/resume, step list/view/add/delete, param list/get/set/delete, settings list/get/set
Projectsproject list, view, create, tree, param, token put/get, settings export/status
VCS/Connproject vcs list/view/create/delete, project connection list/create/authorize/delete
Queuequeue list, approve, remove, top
Agentsagent list, view, enable/disable, authorize/deauthorize, exec, term, reboot, move
Poolspool list, view, link/unlink
Pipelinespipeline list, view, create, validate, pull, push, schema, delete
APIteamcity api <endpoint> — raw REST access
Linkteamcity link — bind repo via teamcity.toml

Quick Workflows

See Workflows for full details on each.

  • Investigate failure: run list --status failure → run log <id> --failed --raw → run tests <id> --failed

  • Debug build chain: run tree <id> → drill to deepest failed child

  • Fix and verify: edit → push → run start --watch (use --local-changes for personal builds)

  • Pipeline lifecycle: pipeline pull <id> → edit → pipeline validate → pipeline push <id>, pipeline schema to get the actual schema from the server

  • GitHub VCS: connection create github-app → connection authorize → install App on repo → vcs create --auth token --connection-id <id>

  • Docker registry: echo $TOKEN | connection create docker -p <id> --name X --url https://ghcr.io --username U --stdin

References

Files

references/commands.md

Command Reference

Contents

  • Authentication (teamcity auth)

  • Builds/Runs (teamcity run)

  • Jobs (teamcity job)

  • Projects (teamcity project)

  • Queue (teamcity queue)

  • Agents (teamcity agent)

  • Agent Pools (teamcity pool)

  • Pipelines (teamcity pipeline)

  • Configuration (teamcity config)

  • Direct API (teamcity api)

  • Global Flags

  • List Output Flags

Authentication (teamcity auth)

CommandDescription
teamcity auth login -s <url>Authenticate with TeamCity server
teamcity auth logoutLog out from current server
teamcity auth statusShow auth status and server info

Login options:

  • -s, --server <url> - TeamCity server URL

  • -t, --token <token> - Access token

  • --insecure-storage - Store token in plain text config file instead of system keyring

Environment override note:

  • TEAMCITY_URL + TEAMCITY_TOKEN should be set together when overriding auth in scripts

  • TEAMCITY_URL alone bypasses stored teamcity auth login credentials

  • TEAMCITY_HEADER_* adds an HTTP header to every request: TEAMCITY_HEADER_FOO_BAR=baz sends Foo-Bar: baz. Use this for proxies that gate access (Cloudflare Access, Google IAP). Values are redacted in --verbose output.

Builds/Runs (teamcity run)

CommandDescription
teamcity run listList recent builds
teamcity run view <id>View build details
teamcity run start <job-id>Start a new build
teamcity run cancel <id>Cancel a build
teamcity run restart <id>Restart a build
teamcity run watch <id>Watch build in real-time
teamcity run log <id>View build log
teamcity run tests <id>View test results
teamcity run changes <id>View VCS changes
teamcity run artifacts <id>List artifacts
teamcity run download <id>Download artifacts
teamcity run pin <id>Pin build
teamcity run unpin <id>Unpin build
teamcity run tag <id> <tags>Add tags
teamcity run untag <id> <tags>Remove tags
teamcity run comment <id>Manage comments
teamcity run tree <id>Show snapshot dependency tree for a run
Flags for teamcity run list

Shows all branches and all build states (including canceled, personal, composite sub-builds) by default — matching the TeamCity UI. Use --branch to narrow to a specific branch, or --branch @this to use the current git branch.

  • -j, --job <id> - Filter by job

  • -b, --branch <name> - Filter by branch (@this = current git branch)

  • --status <status> - Filter: success, failure, running, queued, error, unknown

  • -u, --user <name> - Filter by user

  • --favorites - Show favorite builds for the current user

  • -p, --project <id> - Filter by project

  • -n, --limit <n> - Limit results (default: 30)

  • --since <time> - Since time (e.g., 24h, 7d, 2w, 2026-01-01)

  • --until <time> - Until time (e.g., 12h, 7d, 2026-01-02)

  • --json - JSON output (use --json= to list fields, --json=f1,f2 for specific)

  • --plain - Plain text output for scripting

  • --no-header - Omit header row (use with --plain)

  • -w, --web - Open in browser

Flags for teamcity run start
  • -b, --branch <name> - Branch to build

  • --revision <sha> - Pin build to a specific Git commit SHA

  • -P, --param <k=v> - Build parameter (repeatable)

  • -S, --system <k=v> - System property (repeatable)

  • -E, --env <k=v> - Environment variable (repeatable)

  • -t, --tag <tag> - Add tag (repeatable)

  • -m, --comment <text> - Run comment

  • --watch - Watch after starting

  • -i, --interval <s> - Refresh interval in seconds when watching (default: 3)

  • --timeout <duration> - Timeout when watching (e.g., 30m, 1h); implies --watch

  • --clean - Clean checkout

  • --agent <id> - Run on specific agent

  • --personal - Run as personal build

  • -l, --local-changes - Include local changes (git, -, or path)

  • --no-push - Skip auto-push of branch to remote

  • --rebuild-deps - Rebuild all dependencies

  • --rebuild-failed-deps - Rebuild failed/incomplete dependencies

  • --reuse-deps <id,...> - Reuse existing builds as snapshot dependencies (comma-separated IDs)

  • --top - Add to top of queue

  • --dry-run - Show what would be triggered without running

  • --json - Output as JSON (for scripting)

  • -w, --web - Open run in browser

Flags for teamcity run log
  • --failed - Show failure summary (problems and failed tests)

  • -j, --job <id> - Get log for latest run of this job

  • -f, --follow - Stream log output in real-time until build finishes

  • --tail <N> - Show last N log messages

  • --raw - Show raw log without formatting

  • --json - Output as JSON

  • -w, --web - Open build log in browser

Flags for teamcity run watch
  • -i, --interval <s> - Refresh interval in seconds

  • --logs - Stream build logs while watching

  • --quiet - Minimal output, show only state changes and result

  • --json - Wait for completion and output result as JSON

  • --timeout <duration> - Timeout duration (e.g., 30m, 1h)

Flags for teamcity run view
  • --json - Output as JSON

  • -w, --web - Open in browser

Flags for teamcity run tests
  • --failed - Show only failed tests, excluding muted failures

  • --muted - Show only muted failed tests

  • -j, --job <id> - Get tests for latest run of this job

  • --json - Output as JSON

  • -n, --limit <n> - Maximum number of tests to show

Flags for teamcity run changes
  • --json - Output as JSON

  • --no-files - Hide file list, show commits only

Flags for teamcity run artifacts
  • -j, --job <id> - List artifacts from latest run of this job

  • -p, --path <subdir> - Browse artifacts under this subdirectory

  • --json - Output as JSON

Flags for teamcity run download
  • -a, --artifact <pattern> - Artifact name pattern to filter (matches full path and basename)

  • -p, --path <subdir> - Download artifacts under this subdirectory

  • -o, --output <path> - Local directory to save artifacts to

Flags for teamcity run cancel
  • --comment <text> - Comment for cancellation

  • -y, --yes - Skip confirmation prompt

Flags for teamcity run restart
  • --watch - Watch the new run after restarting

  • -i, --interval <s> - Refresh interval in seconds when watching (default: 3)

  • --timeout <duration> - Timeout when watching (e.g., 30m, 1h); implies --watch

  • -w, --web - Open run in browser

Flags for teamcity run pin
  • -m, --comment <text> - Comment explaining why the run is pinned

Flags for teamcity run comment
  • --delete - Delete the comment

Flags for teamcity run tree
  • -d, --depth <n> - Limit tree depth (0 = unlimited)

  • --json - Output as JSON

Jobs (teamcity job)

CommandDescription
teamcity job create <name>Create a job
teamcity job listList build configurations
teamcity job view <id>View job details
teamcity job tree <id>Show snapshot dependency tree
teamcity job pause <id>Pause job
teamcity job resume <id>Resume job
teamcity job param list <id>List parameters
teamcity job param get <id> <name>Get parameter
teamcity job param set <id> <name> <val>Set parameter
teamcity job param delete <id> <name>Delete parameter
teamcity job step list <id>List build steps
teamcity job step view <id> <step-id>View build step details
teamcity job step add <id> --type <r>Add a build step
teamcity job step delete <id> <step-id>Delete a build step
teamcity job settings list <id>List settings
teamcity job settings get <id> <name>Get a setting value
teamcity job settings set <id> <name> <val>Set a setting value
Flags for teamcity job create
  • -p, --project <id> - Parent project ID (or TEAMCITY_PROJECT / linked project)

  • --id <id> - Explicit job ID (default: auto-generated from name)

  • --template <id> - Create from an existing template ID

  • --json - Output as JSON

  • -w, --web - Open in browser after creation

Flags for teamcity job list
  • --json - JSON output (use --json= to list fields, --json=f1,f2 for specific)

  • -n, --limit <n> - Maximum number of jobs

  • -p, --project <id> - Filter by project ID

Flags for teamcity job view
  • --json - Output as JSON

  • -w, --web - Open in browser

Flags for teamcity job tree
  • -d, --depth <n> - Limit tree depth (0 = unlimited)

  • --only <type> - Show only dependents or dependencies

Flags for teamcity job param list
  • --json - Output as JSON

Flags for teamcity job param set
  • --secure - Mark as secure/password parameter

Flags for teamcity job step add
  • --type <runner-id> - Runner type ID as used by the REST API: simpleRunner (Command Line), gradle-runner (Gradle), Maven2 (Maven), ... (required). Find IDs via teamcity job step view.

  • --name <name> - Step name

  • --param <key=value> - Step parameter (repeatable)

  • --json - Output as JSON

The <id> (job) positional is optional when the repo is linked; delete accepts remove/rm aliases.

Projects (teamcity project)

CommandDescription
teamcity project listList projects
teamcity project view <id>View project details
teamcity project create <name>Create a project
teamcity project tree [id]Show project hierarchy tree
teamcity project vcs list --project <id>List VCS roots
teamcity project vcs view <id>View VCS root details
teamcity project vcs create --project <id>Create VCS root (interactive or flag-driven)
teamcity project vcs delete <id>Delete a VCS root
teamcity project connection list -p <id>List project connections
teamcity project connection create github-app -p <id>Register GitHub App (manifest flow)
teamcity project connection create docker -p <id>Register Docker registry credentials
teamcity project connection authorize <conn-id> -p <id>Per-user OAuth dance for an OAuth connection
teamcity project connection delete <conn-id> -p <id>Delete a connection
teamcity project param list <id>List parameters
teamcity project param get <id> <name>Get parameter
teamcity project param set <id> <name> <val>Set parameter
teamcity project param delete <id> <name>Delete parameter
teamcity project token put <id>Store secret, get token
teamcity project token get <id> <token>Retrieve secret
teamcity project settings export <id>Export settings as ZIP
teamcity project settings status <id>Show versioned settings sync
teamcity project settings validate [path]Validate Kotlin DSL config
Flags for teamcity project tree
  • -d, --depth <n> - Limit tree depth (0 = unlimited)

  • --no-jobs - Hide build configurations

Flags for teamcity project list
  • --json - JSON output (use --json= to list fields, --json=f1,f2 for specific)

  • -n, --limit <n> - Maximum number of projects

  • -p, --parent <id> - Filter by parent project ID

Flags for teamcity project view
  • --json - Output as JSON

  • -w, --web - Open in browser

Flags for teamcity project create
  • --id <id> - Explicit project ID (default: auto-generated from name)

  • -p, --parent <id> - Parent project ID (default: _Root)

  • --json - Output as JSON

  • -w, --web - Open in browser after creation

Flags for teamcity project vcs list
  • --json - JSON output (use --json= to list fields, --json=f1,f2 for specific)

  • -n, --limit <n> - Maximum number of VCS roots

  • -p, --project <id> - Project ID (required)

Flags for teamcity project vcs view
  • --json - Output as JSON

  • -w, --web - Open in browser

Flags for teamcity project vcs delete
  • -y, --yes - Skip confirmation prompt

Flags for teamcity project param list
  • --json - Output as JSON

Flags for teamcity project param set
  • --secure - Mark as secure/password parameter

Flags for teamcity project settings export
  • --kotlin - Export as Kotlin DSL (default)

  • --xml - Export as XML

  • -o, --output <path> - Output file path (default: projectSettings.zip)

  • --relative-ids - Use relative IDs in exported settings

Flags for teamcity project settings status
  • --json - Output as JSON

Flags for teamcity project settings validate
  • --verbose - Show full Maven output

  • Positional argument: optional filesystem path to .teamcity (not a project ID/name; there is no --dir flag)

Flags for teamcity project token put
  • --stdin - Read value from stdin

Queue (teamcity queue)

CommandDescription
teamcity queue listList queued builds
teamcity queue remove <id>Remove from queue
teamcity queue top <id>Move to top of queue
teamcity queue approve <id>Approve waiting build
Flags for teamcity queue list
  • -j, --job <id> - Filter by job ID

  • --json - JSON output (use --json= to list fields, --json=f1,f2 for specific)

  • -n, --limit <n> - Maximum number of queued runs

Flags for teamcity queue remove
  • -y, --yes - Skip confirmation prompt

Agents (teamcity agent)

CommandDescription
teamcity agent listList build agents
teamcity agent view <id>View agent details
teamcity agent authorize <id>Authorize agent to run builds
teamcity agent deauthorize <id>Revoke agent authorization
teamcity agent enable <id>Enable agent
teamcity agent disable <id>Disable agent
teamcity agent move <id> <pool>Move agent to different pool
teamcity agent jobs <id>List compatible/incompatible jobs
teamcity agent exec <id> <cmd>Execute command on agent
teamcity agent term <id>Open interactive shell on agent
teamcity agent reboot <id>Reboot a build agent
Flags for teamcity agent list
  • -p, --pool <name> - Filter by agent pool

  • --connected - Show only connected agents

  • --enabled - Show only enabled agents

  • --authorized - Show only authorized agents

  • -n, --limit <n> - Limit results

  • --json - JSON output (use --json= to list fields, --json=f1,f2 for specific)

Flags for teamcity agent view
  • --json - Output as JSON

  • -w, --web - Open in browser

Flags for teamcity agent jobs
  • --incompatible - Show incompatible jobs with reasons

  • --json - Output as JSON

Flags for teamcity agent exec
  • --timeout <duration> - Command timeout

Flags for teamcity agent reboot
  • --graceful - Wait for current build to finish before rebooting

  • -y, --yes - Skip confirmation prompt

Agent Pools (teamcity pool)

CommandDescription
teamcity pool listList agent pools
teamcity pool view <id>View pool details
teamcity pool link <id> <project>Link project to pool
teamcity pool unlink <id> <project>Unlink project from pool
Flags for teamcity pool list
  • --json - JSON output (use --json= to list fields, --json=f1,f2 for specific)

Flags for teamcity pool view
  • --json - Output as JSON

  • -w, --web - Open in browser

Pipelines (teamcity pipeline)

Pipelines are YAML-first build configurations. Each pipeline is a project that can contain multiple jobs defined in a .teamcity.yml file. Pipelines differ from jobs/build configs: they use YAML for configuration and can be stored in VCS or on the server.

CommandDescription
teamcity pipeline listList pipelines
teamcity pipeline view <id>View pipeline details
teamcity pipeline create <name>Create pipeline from YAML
teamcity pipeline validate [file]Validate pipeline YAML against schema
teamcity pipeline pull <id>Download pipeline YAML
teamcity pipeline push <id> [file]Upload pipeline YAML
teamcity pipeline delete <id>Delete a pipeline
Flags for teamcity pipeline list
  • -p, --project <id> - Filter by project ID

  • -n, --limit <n> - Maximum number of items (default: 30)

  • --json - JSON output (use --json= to list fields, --json=f1,f2 for specific)

  • --plain - Plain text output for scripting

  • --no-header - Omit header row

Flags for teamcity pipeline view
  • --json - Output as JSON

  • -w, --web - Open in browser

Flags for teamcity pipeline create
  • -p, --project <id> - Parent project ID (required)

  • --vcs-root <id> - VCS root ID (interactive selection if omitted)

  • -f, --file <path> - Pipeline YAML file (default: .teamcity.yml)

Flags for teamcity pipeline validate
  • --schema <path> - Local JSON schema file (overrides server schema)

  • --refresh-schema - Force re-fetch schema from server

Flags for teamcity pipeline pull
  • -o, --output <path> - Write YAML to file instead of stdout

Flags for teamcity pipeline delete
  • -y, --yes - Skip confirmation prompt

Configuration (teamcity config)

CommandDescription
teamcity config listList all configuration values
teamcity config get <key>Get a configuration value
teamcity config set <key> <value>Set a configuration value

Valid keys: default_server, guest, ro, token_expiry.

Per-server keys (guest, ro, token_expiry) use --server <url> to target a specific server. Without --server, the default server is used.

Flags for teamcity config list
  • --json - Output as JSON

Flags for teamcity config get and set
  • -s, --server <url> - Server URL for per-server settings

Examples
# Switch default server
teamcity config set default_server tc.example.com

# Enable read-only mode
teamcity config set ro true --server tc.example.com

# Check current default server
teamcity config get default_server

Direct API (teamcity api)

For features not covered by specific commands. Endpoints always start with /app/rest/. Pass only the endpoint path as the first argument (never include GET, POST, etc. in the path).

# GET request
teamcity api '/app/rest/server'

# POST request
teamcity api '/app/rest/buildQueue' -X POST -f 'buildType=id:MyBuild'

# With pagination
teamcity api '/app/rest/builds' --paginate --slurp

# Browse artifact subdirectory
teamcity api '/app/rest/builds/id:BUILD_ID/artifacts/children/SUBPATH'
Flags
  • -X, --method <method> - HTTP method

  • -H, --header <h> - Custom header (repeatable)

  • -f, --field <k=v> - Body field (builds JSON)

  • --input <file> - Read body from file (use - for stdin)

  • --paginate - Fetch all pages

  • --slurp - Combine pages into array (requires --paginate)

  • --raw - Output raw response without formatting

  • --silent - Suppress output on success

  • -i, --include - Include response headers in output

Global Flags

Available on all commands:

  • -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

  • -w, --web - Open in browser (on view commands)

List Output Flags

Available on all list commands (run list, agent list, job list, pool list, project list, queue list, project vcs list, pipeline list) and on agent jobs, project param list, job param list:

  • --plain - Tab-separated plain text output for scripting (mutually exclusive with --json)

  • --no-header - Omit header row (use with --plain)

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Cline
Publisher
Cline (Official)
Source
cline/skills · skills/teamcity-cli · commit 2637846
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Cline or Cline.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download teamcity-cli.zip