TeamCity CLI for kotlinx-rpc

Interact with the kotlinx-rpc TeamCity project via the teamcity CLI (expected to be installed at /opt/homebrew/bin/teamcity).

For local Gradle builds and tests, use running_gradle_builds / running_gradle_tests skills instead.

Agent workflow override

When this skill is invoked from the fix-issue skill (autonomous issue-fixing workflow), never run teamcity auth status or teamcity auth login. Instead, prefix every teamcity command with TEAMCITY_TOKEN=$TEAMCITY_AGENT_TOKEN. The fix-issue skill's Authentication section has full details. Outside of fix-issue, the defaults below apply.

Prerequisites

Before running any commands, verify authentication:

teamcity auth status

If not authenticated, the user needs to log in interactively -- suggest they run ! teamcity auth login in the prompt so the browser-based auth flow works in their session.

TeamCity Project Structure

The root project is kRPC. It has two main branches:

• Build (Build_kRPC) -- CI builds triggered on PRs and commits
• Release (Release_kRPC) -- Publication to Maven Central, Space, GitHub

Reference Files

Read these as needed -- don't load them all upfront:

• references/build-ids.md -- Full catalog of build configuration IDs (composite builds, platform builds, quality checks, compiler plugin builds, special/scheduled builds). Read when you need to look up a specific build ID.
• references/remote-verification-table.md -- Decision table mapping changed file paths to the minimal set of TeamCity builds to trigger. Read when deciding which builds to run for a set of changes.
• references/release-builds.md -- Release pipeline build IDs for Sonatype, Space EAP, and Space gRPC. Read only during release workflows.

Common Workflows

Trigger a build on a branch

teamcity run start Build_kRPC_All --branch feature/my-branch

Add --watch to stream progress in real-time. Without it, the command returns immediately after queuing.

To trigger with custom parameters (e.g., override Kotlin version):

teamcity run start Build_kRPC_All --branch main -E KOTLIN_COMPILER_VERSION_ENV=2.3.20

Check recent build status

# Recent failures across all builds
teamcity run list --status failure --since 24h

# Recent builds for a specific configuration
teamcity run list --job Build_kRPC_All --limit 10

# Recent builds on a specific branch
teamcity run list --job Build_kRPC_All --branch main --limit 5

# Only running builds
teamcity run list --status running

Investigate a build failure

# View build details
teamcity run view <build-id>

# Show failure summary (most useful for quick diagnosis)
teamcity run log <build-id> --failed

# Stream full build log (opens in pager)
teamcity run log <build-id>

# Show test results
teamcity run tests <build-id>

# Show VCS changes that triggered the build
teamcity run changes <build-id>

Cancel or restart builds

# Cancel a running or queued build
teamcity run cancel <build-id> --comment "Cancelling: wrong branch"

# Restart a failed build
teamcity run restart <build-id>

Download build artifacts

# List artifacts
teamcity run artifacts <build-id>

# Download artifacts
teamcity run download <build-id>

View project/job hierarchy

# List all projects
teamcity project list

# View project tree
teamcity project tree kRPC

# List jobs in a project
teamcity job list --project Build_kRPC

# View snapshot dependency tree for a build config
teamcity job tree Build_kRPC_All

Dry-run (preview without triggering)

teamcity run start Build_kRPC_All --branch main --dry-run

JSON output for scripting

# Full JSON
teamcity run list --json --limit 5

# Specific fields
teamcity run list --json=id,status,webUrl --limit 5

# Plain text (for grep/awk)
teamcity run list --plain --limit 10

Build Configuration DSL

The TeamCity Kotlin DSL configs live in the sibling repository:

../kotlinx-rpc-build/.teamcity/src/

Ensure that the repository is cloned and up-to-date before running commands. Remote: https://git.jetbrains.team/krpc/krpc-build.git If not cloned - notify the user to clone it.

Key files when you need to understand or modify build configs:

Read these files from ../kotlinx-rpc-build/ when the user asks about how a specific build is configured or wants to modify CI behavior.

Tips

• Build IDs are case-sensitive -- use them exactly as listed in references/build-ids.md.
• For composite builds (like Build_kRPC_All), failures in any dependency build will show in the composite. Use run log <id> --failed on the specific dependency build that failed, not the composite.
• Use --since and --until with durations like 24h, 7d, 1h for time-based filtering.
• The teamcity api command can make raw REST API calls for anything the CLI doesn't directly support: teamcity api /app/rest/builds?locator=...