AutoGineer
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
Download ZIP

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/output.md

Output Formats

Most commands support multiple output formats for different use cases.

Available Formats

FormatFlagUse Case
Table (default)noneHuman-readable, colored output
Plain text--plainScripting, parsing
JSON--jsonProgrammatic access
No color--no-colorLogs, CI environments
No header--no-headerClean output for piping

JSON Output

Default JSON (all fields):

teamcity run list --json

List available fields:

teamcity run list --json=

Select specific fields:

teamcity run list --json=id,status,webUrl

Nested fields (dot notation):

teamcity run list --json=id,buildType.name,triggered.user.username

Available JSON Fields by Command

CommandExample fields
run listid, number, status, state, branchName, buildTypeId, buildType.name, buildType.projectName, triggered.type, triggered.user.name, agent.name, startDate, finishDate, webUrl
job listid, name, projectName, projectId, paused, href, webUrl
project listid, name, description, parentProjectId, href, webUrl
queue listid, buildTypeId, state, branchName, queuedDate, buildType.name, triggered.user.name, webUrl
agent listid, name, connected, enabled, authorized, pool.name, webUrl
pool listid, name, maxAgents
pipeline listid, name, webUrl, parentProject.id, parentProject.name, headBuildType.id, jobs.count

Run teamcity <command> --json= to see all available fields for that command.

Scripting Examples

Get build IDs of failed builds:

teamcity run list --status failure --plain --no-header | awk '{print $2}'

JSON with jq:

teamcity run list --json | jq '.[] | {id, status, branch}'

Get build IDs that failed (JSON):

teamcity run list --status failure --json=id | jq -r '.[].id'

Export runs to CSV:

teamcity run list --json=id,status,branchName | jq -r '.[] | [.id,.status,.branchName] | @csv'

Filter builds by pattern:

teamcity run list --json | jq '.[] | select(.branch | contains("feature"))'

Count builds by status:

teamcity run list --json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

Get web URLs for queued builds:

teamcity queue list --json=webUrl | jq -r '.[].webUrl'

Environment Variables

For non-interactive use (CI/CD, scripts):

export TEAMCITY_URL="https://teamcity.example.com"
export TEAMCITY_TOKEN="your-api-token"

# Commands will use these automatically
teamcity run list

Environment variables always take precedence over config file settings.

Other supported variables:

  • TEAMCITY_GUEST=1 — use guest authentication

  • TEAMCITY_RO=1 — read-only mode (block write operations)

  • TEAMCITY_NO_UPDATE=1 — disable automatic update checks

  • NO_COLOR or TEAMCITY_NO_COLOR — disable colored output

Combining with Other Tools

Open in browser:

teamcity run view <id> -w

Pipe to less with color:

teamcity run list | less -R

Watch and notify:

teamcity run watch <id> && notify-send "Build complete"

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