Configuration

This page describes the configuration file format, environment variables, and shell completion setup for TeamCity CLI.

Configuration file

TeamCity CLI stores its configuration in a YAML file at ~/.config/tc/config.yml. This file is created automatically when you run teamcity auth login.

A typical configuration file looks like this:

default_server: https://teamcity.example.com
servers:
  https://teamcity.example.com:
    user: alice
  https://teamcity-staging.example.com:
    user: alice
    guest: true
  https://teamcity-prod.example.com:
    user: alice
    ro: true
aliases:
  rl: 'run list'
  rw: 'run view $1 --web'
  mine: 'run list --user=@me'

Configuration fields

Field	Description
`default_server`	The server URL used when no `TEAMCITY_URL` environment variable is set. Updated automatically when you run `teamcity auth login`.
`servers`	A map of server URLs to their settings. Each entry stores the `user` field (username on that server) and optionally `guest: true` for guest access or `ro: true` for read-only mode. Tokens are stored in the system keyring, not in this file, unless `--insecure-storage` was used during login.
`aliases`	A map of alias names to their expansions. See Aliases for details.

Environment variables

Environment variables override configuration file settings and are the recommended way to configure the CLI in CI/CD pipelines.

Variable	Description
`TEAMCITY_URL`	TeamCity server URL. Takes precedence over `default_server` in the config file.
`TEAMCITY_TOKEN`	Access token for authentication. Takes precedence over the keyring and config file token.
`TEAMCITY_GUEST`	Set to `1` to use guest authentication (read-only, no token needed). The CLI must be able to resolve the server URL (via `TEAMCITY_URL`, DSL detection, or the config file).
`TEAMCITY_RO`	Set to `1`, `true`, or `yes` to enable read-only mode. When enabled, all non-GET API requests (POST, PUT, DELETE) are blocked, preventing any modifications to the TeamCity server. Useful for monitoring scripts and dashboards. Can also be set per server in the config file with `ro: true`.
`TEAMCITY_DSL_DIR`	Path to the Kotlin DSL directory. Overrides automatic detection of `.teamcity/` or `.tc/` directories.
`NO_COLOR`	Disable colored output. Follows the NO_COLOR standard.

Examples:

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

PowerShell:

$env:TEAMCITY_URL = "https://teamcity.example.com"
$env:TEAMCITY_TOKEN = "your-access-token"

CMD:

set TEAMCITY_URL=https://teamcity.example.com
set TEAMCITY_TOKEN=your-access-token

Setting TERM=dumb also disables colored output. Color is automatically disabled when output is not a terminal (for example, when piping to another command).

Global flags

These flags are available on every command:

Flag	Description
`-h`, `--help`	Show help for the command.
`-v`, `--version`	Show the CLI version.
`--no-color`	Disable colored output.
`-q`, `--quiet`	Suppress non-essential output. Mutually exclusive with `--verbose`.
`--verbose`	Show detailed output, including debug information. Mutually exclusive with `--quiet`.
`--no-input`	Disable interactive prompts. The CLI uses sensible defaults when a prompt would otherwise appear.

Shell completion

TeamCity CLI supports tab completion for Bash, Zsh, Fish, and PowerShell. Completion covers commands, subcommands, flags, and in some cases values such as project and job IDs.

teamcity completion bash > /etc/bash_completion.d/teamcity

If you do not have write access to /etc/bash_completion.d/, write to a user-level location and source it from your .bashrc:

teamcity completion bash > ~/.teamcity-completion.bash
echo 'source ~/.teamcity-completion.bash' >> ~/.bashrc

teamcity completion zsh > "${fpath[1]}/_teamcity"

Ensure your ~/.zshrc includes compinit:

autoload -Uz compinit && compinit

teamcity completion fish > ~/.config/fish/completions/teamcity.fish

teamcity completion powershell > teamcity.ps1
. ./teamcity.ps1

To load completion automatically, add the output to your PowerShell profile.

24 February 2026