This article follows the official documentation. We haven’t tested this tool for a hands-on review.
When a coding agent needs to check a continuous integration run, it can use TeamCity CLI, a command-line tool, to ask a TeamCity server for information from a shell. Continuous integration, or CI, runs checks such as builds and tests when code changes. The CLI runs as teamcity and lets an agent inspect runs, logs, queues, agents, and artifacts without opening TeamCity in a browser. A run is the CLI’s term for a TeamCity build.
For example, an agent investigating a failed check can list recent runs and report their statuses. Those commands read data from the server; they do not change a build configuration. The official CLI documentation and JetBrains repository cover installation, authentication, commands, and options.
Install and sign in
If you have Node.js and npm, the official repository documents this installation method:
npm install -g @jetbrains/teamcity-cli
The repository also covers Homebrew, Linux packages and Windows installers. Use one method for the machine where your agent runs.
Sign in with:
teamcity auth login
The command connects the CLI to a TeamCity server and starts the sign-in flow. The CLI remembers which server you signed in to. You can sign in to multiple servers. It also accepts TEAMCITY_URL to select a server for a command. Follow the login prompt for the authentication method your server supports. Keep credentials in the CLI’s authentication flow or another approved secret store; do not put a token in an agent prompt.
An agent skill is available to teach supported coding agents how to use the CLI. Install it with teamcity skill install; the TeamCity agent integration instructions explain how to target a particular agent or install the skill at project level.
List runs without changing TeamCity
After signing in, an agent can list runs in JSON format:
TEAMCITY_RO=1 teamcity run list --limit 10 --json
TEAMCITY_RO=1 enables the CLI’s read-only mode for this command. teamcity run list requests up to ten runs from the configured server, and --json formats the result for programs and agents to parse. The response has run data from TeamCity; its exact contents depend on the server and the available runs. The CLI also supports field selection and tab-delimited output with --plain for list commands.
This is a network request to TeamCity. It does not edit local files or start, cancel, or reconfigure a run. An agent can use the returned statuses and identifiers to find a failure worth investigating, then consult the CLI command reference for the relevant log or run-inspection command.
For example, an agent prompt could say: “List recent TeamCity runs in read-only mode. Report any failed run IDs and statuses. Do not start, cancel, or modify runs.” The prompt limits the agent’s task, while the environment variable adds a restriction enforced by the CLI.
Understand the safety boundary
Read-only mode blocks write commands and remote agent shells, including teamcity agent exec and teamcity agent term. However, the account’s permissions on the TeamCity server still determine what the agent can do. JetBrains advises limiting the rights granted to an agent and checking the actions it intends to take. Use an account with only the access needed for the task; do not treat TEAMCITY_RO=1 as a substitute for server permissions.
The child builds do the actual work, so a composite build can have empty logs. If a composite run does not show a useful failure, inspect its child runs. When builds depend on one another in a chain, the deepest failed dependency is often the root cause; the CLI’s teamcity run tree command shows the chain. The CLI can also call the TeamCity REST API directly through teamcity api when a wrapped command does not cover a needed operation.
Coding agents use TeamCity CLI from a shell to inspect CI data and, with the right permissions, perform other TeamCity operations. For an investigation task, start with teamcity run list --json under read-only mode and grant the agent no more server access than its task requires. Find more developer command-line tools in the Awesome CLI directory.