Configuration

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

Managing configuration with `teamcity config`

The config command lets you view and modify CLI settings without editing the YAML file directly.

List all settings

teamcity config list
teamcity config list --json

Get a setting

teamcity config get default_server
teamcity config get ro --server tc.example.com

Set a setting

# Switch default server
teamcity config set default_server tc.example.com

# Enable read-only mode for a specific server
teamcity config set ro true --server tc.example.com

# Enable guest auth for the default server
teamcity config set guest true

Available keys

Key	Scope	Description
`default_server`	Global	The default TeamCity server URL.
`guest`	Per-server	Enable guest authentication (no token needed). Use `--server` to target a specific server.
`ro`	Per-server	Enable read-only mode (blocks all write operations). Use `--server` to target a specific server.
`token_expiry`	Per-server	Token expiry timestamp (RFC 3339). Normally set by `auth login`.
`analytics`	Global	Enable or disable anonymous usage statistics. Default: `true`. Set to `false` to opt out.

Authentication fields (token, user) are managed by teamcity auth login/teamcity auth logout and cannot be set via config set.

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, `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.
`TEAMCITY_NO_COLOR`	App-specific alternative to `NO_COLOR` for disabling colored output.
`TEAMCITY_NO_UPDATE`	Set to `1`, `true`, or `yes` to disable automatic update checks. Update checks are also disabled automatically in CI environments and non-interactive terminals.
`TEAMCITY_HEADER_*`	Add an HTTP header to every outgoing request. The suffix becomes the header name with underscores converted to hyphens, canonical-cased: `TEAMCITY_HEADER_FOO_BAR=baz` sends `Foo-Bar: baz`. Empty values are ignored; values containing CR/LF/NUL are dropped to prevent header injection. Header values are redacted in `--verbose` output.
`DO_NOT_TRACK`	Set to `1`, `true`, `yes`, or `on` to disable anonymous usage statistics. Follows the industry convention. Takes precedence over `TEAMCITY_ANALYTICS` and the config file.
`TEAMCITY_ANALYTICS`	Set to `0`, `false`, `no`, or `off` to disable anonymous usage statistics for this CLI specifically. Takes precedence over the config file.

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).

Extra HTTP headers (corporate proxies)

If your TeamCity server sits behind an authenticating proxy such as Cloudflare Access or Google IAP, the proxy needs its own credentials on every request. TEAMCITY_HEADER_* lets you supply them via env vars without editing the config file. The CLI applies them to every API call, the auth login probe, the PKCE exchange, and the agent terminal WebSocket — anywhere a request might pass through the proxy.

Header names follow these rules:

Suffix is uppercased after the prefix; underscores become hyphens; the result is canonical-cased.
TEAMCITY_HEADER_CF_ACCESS_CLIENT_ID=value → Cf-Access-Client-Id: value.
Empty values are skipped. Values containing CR/LF/NUL are dropped.
Values are redacted in --verbose output, regardless of header name.

Cloudflare Access service token

export TEAMCITY_HEADER_CF_ACCESS_CLIENT_ID="abc123.access"
export TEAMCITY_HEADER_CF_ACCESS_CLIENT_SECRET="$(cat ~/.cf-access-secret)"
teamcity run list

Google IAP

IAP requires a fresh ID token signed by your service account. A small wrapper keeps the token current:

teamcity-iap() {
  export TEAMCITY_HEADER_PROXY_AUTHORIZATION="Bearer $(gcloud auth print-identity-token --audiences=$IAP_AUDIENCE)"
  teamcity "$@"
}

teamcity-iap run list

For repository-scoped configuration, set these in direnv .envrc so they're only present when you cd into the project directory.

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.

06 May 2026