Teamcity CLI
ClineOfficialPublished by Cline
- Skill
- Tool integration
- Cloud and DevOps
- Apache-2.0
- No issues found
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
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/cline/teamcity-cli/downloadUnzip 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 diagnosticsDo 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-changesexcludes Kotlin DSL — push.teamcity/changes before running.TEAMCITY_URLalone bypasses stored auth — set bothTEAMCITY_URLandTEAMCITY_TOKEN, or leave unset.Logs: use
--rawand dump to a temp file. Builds: use--watchwhen starting them.VCS triggers aren't always wired up — after pushing a fix you may need to start builds manually.
pipeline pushdoes not validate — alwaysteamcity pipeline validatefirst.GitHub VCS roots: use a GitHub App connection. Never paste a PAT via
--auth password. See workflows.
Core Commands
| Area | Commands |
|---|---|
| Auth | auth login, logout, status |
| Builds | run list, view, start, watch, log, cancel, restart, tests, changes, tree |
| Artifacts | run artifacts, run download |
| Metadata | run pin/unpin, run tag/untag, run comment |
| Jobs | job list, view, create, tree, pause/resume, step list/view/add/delete, param list/get/set/delete, settings list/get/set |
| Projects | project list, view, create, tree, param, token put/get, settings export/status |
| VCS/Conn | project vcs list/view/create/delete, project connection list/create/authorize/delete |
| Queue | queue list, approve, remove, top |
| Agents | agent list, view, enable/disable, authorize/deauthorize, exec, term, reboot, move |
| Pools | pool list, view, link/unlink |
| Pipelines | pipeline list, view, create, validate, pull, push, schema, delete |
| API | teamcity api <endpoint> — raw REST access |
| Link | teamcity 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> --failedDebug build chain:
run tree <id>→ drill to deepest failed childFix and verify: edit → push →
run start --watch(use--local-changesfor personal builds)Pipeline lifecycle:
pipeline pull <id>→ edit →pipeline validate→pipeline push <id>,pipeline schemato get the actual schema from the serverGitHub 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
Command reference — all commands and flags
Workflows — failure investigation, build chains, connections, pipelines
Output formats — JSON, plain text, scripting
Files
- ATTRIBUTION.mdAdded by AutoGineer830 B
- LICENSELicence file added by AutoGineer10.5 KiB
- SKILL.md4.3 KiB
- _agents/babysit-build.md1.7 KiB
- references/commands.md21.6 KiB
- references/output.md4.6 KiB
- references/workflows.md30.2 KiB
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)
| Command | Description |
|---|---|
teamcity auth login -s <url> | Authenticate with TeamCity server |
teamcity auth logout | Log out from current server |
teamcity auth status | Show 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_TOKENshould be set together when overriding auth in scriptsTEAMCITY_URLalone bypasses storedteamcity auth logincredentialsTEAMCITY_HEADER_*adds an HTTP header to every request:TEAMCITY_HEADER_FOO_BAR=bazsendsFoo-Bar: baz. Use this for proxies that gate access (Cloudflare Access, Google IAP). Values are redacted in--verboseoutput.
Builds/Runs (teamcity run)
| Command | Description |
|---|---|
teamcity run list | List 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,f2for 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)
| Command | Description |
|---|---|
teamcity job create <name> | Create a job |
teamcity job list | List 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 (orTEAMCITY_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,f2for 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 onlydependentsordependencies
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 viateamcity 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)
| Command | Description |
|---|---|
teamcity project list | List 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,f2for 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,f2for 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 outputPositional argument: optional filesystem path to
.teamcity(not a project ID/name; there is no--dirflag)
Flags for teamcity project token put
--stdin- Read value from stdin
Queue (teamcity queue)
| Command | Description |
|---|---|
teamcity queue list | List 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,f2for specific)-n, --limit <n>- Maximum number of queued runs
Flags for teamcity queue remove
-y, --yes- Skip confirmation prompt
Agents (teamcity agent)
| Command | Description |
|---|---|
teamcity agent list | List 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,f2for 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)
| Command | Description |
|---|---|
teamcity pool list | List 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,f2for 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.
| Command | Description |
|---|---|
teamcity pipeline list | List 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,f2for 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)
| Command | Description |
|---|---|
teamcity config list | List 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_serverDirect 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.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download teamcity-cli.zip