TeamCity On-Premises 2025.11 Help

Authentication

TeamCity CLI supports several authentication methods. This page covers interactive login, guest access, token-based authentication for CI/CD, multi-server setup, and automatic authentication within TeamCity builds.

Interactive login

The standard way to authenticate is with the teamcity auth login command:

teamcity auth login

This starts an interactive flow:

  1. Enter your TeamCity server URL (for example, https://teamcity.example.com).

  2. If the server supports PKCE authentication, the CLI opens your browser to approve access directly — no token copying needed.

  3. Otherwise, the CLI opens the TeamCity Access Tokens page for you to create and paste a token manually.

  4. The CLI validates the token and stores it securely.

To authenticate with a specific server URL:

teamcity auth login --server https://teamcity.example.com

To skip browser-based authentication and enter a token manually:

teamcity auth login --no-browser

To pass the token directly (for example, from a password manager):

teamcity auth login --server https://teamcity.example.com --token <token>

Browser-based login (PKCE)

When PKCE is enabled on the TeamCity server, teamcity auth login authenticates via the browser automatically:

  1. The CLI starts a temporary local server on your machine.

  2. Your browser opens a TeamCity authorization page.

  3. After you approve, the browser redirects back to the CLI with an authorization code.

  4. The CLI exchanges the code for an access token.

This flow follows the OAuth 2.0 PKCE standard (RFC 7636) and does not require you to copy or paste any tokens.

PKCE tokens have an expiry date. The CLI tracks this and shows a warning when the token is about to expire or has expired:

$ teamcity auth status ✓ Logged in to https://teamcity.example.com User: John Doe (john.doe) · system keyring ! Token expires 2 hours from now (on Mar 25, 2026)

Check authentication status

View the current authentication state:

teamcity auth status

This displays the server URL, server version, authenticated username, and token storage method.

Log out

Remove stored credentials for the current server:

teamcity auth logout

Guest access

If the TeamCity server has guest access enabled, you can authenticate without a token:

teamcity auth login --guest

With a specific server URL:

teamcity auth login --server https://teamcity.example.com --guest

Guest authentication provides read-only access. It uses the /guestAuth/ API prefix and does not require or store any credentials.

Authenticating with guest access

Guest access via environment variable

For CI/CD environments where guest access is sufficient:

export TEAMCITY_URL="https://teamcity.example.com" export TEAMCITY_GUEST=1

PowerShell:

$env:TEAMCITY_URL = "https://teamcity.example.com" $env:TEAMCITY_GUEST = "1"

CMD:

set TEAMCITY_URL=https://teamcity.example.com set TEAMCITY_GUEST=1

Token storage

TeamCity CLI stores access tokens using the system keyring when available:

Platform

Keyring

macOS

Keychain

Linux

GNOME Keyring (or compatible secret service)

Windows

Credential Manager

If the system keyring is unavailable, the CLI falls back to storing the token in plain text in the configuration file at ~/.config/tc/config.yml. To force plain text storage (for example, in headless environments), use the --insecure-storage flag:

teamcity auth login --insecure-storage

Environment variables

For CI/CD pipelines and scripted environments, use environment variables instead of interactive login:

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

For guest access:

export TEAMCITY_URL="https://teamcity.example.com" export TEAMCITY_GUEST=1

PowerShell:

$env:TEAMCITY_URL = "https://teamcity.example.com" $env:TEAMCITY_GUEST = "1"

CMD:

set TEAMCITY_URL=https://teamcity.example.com set TEAMCITY_GUEST=1

Environment variables take precedence over the configuration file and keyring.

Advanced authentication scenarios

Authentication inside TeamCity builds

When teamcity runs inside a TeamCity build, it automatically authenticates using build-level credentials from the build properties file. No additional configuration is required.

This allows you to use teamcity commands in build steps without storing or managing tokens:

# Inside a TeamCity build step — no auth setup needed teamcity run list --job MyProject_Build --limit 5

Multiple servers

You can authenticate with several TeamCity servers. Each server's credentials are stored separately.

Adding servers

# First server teamcity auth login --server https://teamcity-prod.example.com # Additional server (becomes the new default) teamcity auth login --server https://teamcity-staging.example.com

Switching between servers

There are several ways to target a specific server:

Environment variable (recommended for scripts):

TEAMCITY_URL=https://teamcity-prod.example.com teamcity run list

PowerShell:

$env:TEAMCITY_URL = "https://teamcity-prod.example.com" teamcity run list

CMD:

set TEAMCITY_URL=https://teamcity-prod.example.com teamcity run list

Export for your session:

export TEAMCITY_URL=https://teamcity-prod.example.com teamcity run list # uses teamcity-prod teamcity auth status # shows teamcity-prod

PowerShell:

$env:TEAMCITY_URL = "https://teamcity-prod.example.com" teamcity run list # uses teamcity-prod teamcity auth status # shows teamcity-prod

CMD:

set TEAMCITY_URL=https://teamcity-prod.example.com teamcity run list # uses teamcity-prod teamcity auth status # shows teamcity-prod

Log in again to change the default:

teamcity auth login --server https://teamcity-prod.example.com

Server auto-detection from Kotlin DSL

When working in a project with TeamCity versioned settings, the CLI can detect the server URL from the Kotlin DSL pom.xml. It searches for .teamcity/ or .tc/ directories in the current folder and its parents (or uses TEAMCITY_DSL_DIR if set), and extracts the server URL from the DSL plugins repository URL. This auto-detected server URL is used when TEAMCITY_URL is not set. You still need credentials for that server.

Credential precedence

Server URL resolution order (highest priority first):

  1. TEAMCITY_URL environment variable

  2. Kotlin DSL auto-detection (TEAMCITY_DSL_DIR, .teamcity/, or .tc/)

  3. default_server from ~/.config/tc/config.yml

Authentication resolution order (highest priority first):

  1. Guest authentication (TEAMCITY_GUEST or a server configured with guest access)

  2. TEAMCITY_TOKEN environment variable

  3. Stored token for the resolved server URL (system keyring first, then plain text config if --insecure-storage was used)

  4. Build-level credentials when running inside a TeamCity build

30 March 2026
Getting StartedConfiguration