Managing Projects

Projects organize build configurations and subprojects in TeamCity. The teamcity project command group lets you browse projects, manage VCS roots, manage parameters, handle secure tokens for versioned settings, and export or validate project configuration.

Listing projects

View all TeamCity projects:

teamcity project list

Filter by parent project:

teamcity project list --parent MyProject

Limit results and output as JSON:

teamcity project list --limit 20
teamcity project list --json
teamcity project list --json=id,name,parentProjectId,webUrl

project list flags

Flag	Description
`-p`, `--parent`	Filter by parent project ID
`-n`, `--limit`	Maximum number of projects to display
`--json`	Output as JSON. Use `--json=` to list available fields, `--json=f1,f2` for specific fields.

Project tree

Display the project hierarchy as a tree, including subprojects and build configurations:

teamcity project tree

Show a specific subtree:

teamcity project tree MyProject

Hide build configurations to see only the project structure:

teamcity project tree --no-jobs

Limit the tree depth:

teamcity project tree --depth 2

project tree flags

Flag	Description
`--no-jobs`	Hide build configurations, show only projects
`-d`, `--depth`	Limit tree depth (0 = unlimited)

Creating a project

Create a new project under the Root project:

teamcity project create MyProject

Create with an explicit ID:

teamcity project create "My Project" --id MyProject

Create under a parent project:

teamcity project create MyProject --parent ParentProject

Output the created project as JSON (useful for scripting):

teamcity project create MyProject --json

project create flags

Flag	Description
`--id`	Explicit project ID. Defaults to an ID auto-generated by TeamCity from the name.
`-p`, `--parent`	Parent project ID. Defaults to `_Root`.
`--json`	Output as JSON
`-w`, `--web`	Open the new project in the browser after creating

Viewing project details

View details of a project:

teamcity project view MyProject

Open the project page in your browser:

teamcity project view MyProject --web

Output as JSON:

teamcity project view MyProject --json

Managing VCS roots

VCS roots define the connection between TeamCity and your version control repository. They are project-level entities, visible to child projects through inheritance.

Listing VCS roots

teamcity project vcs list --project MyProject
teamcity project vcs list --project MyProject --json
teamcity project vcs list --project MyProject --plain

Viewing VCS root details

teamcity project vcs view MyProject_GitHubRepo
teamcity project vcs view MyProject_GitHubRepo --json
teamcity project vcs view MyProject_GitHubRepo --web

The view command shows all VCS root properties with human-readable labels. Secure properties (passwords, passphrases) are masked as ********.

Creating a VCS root

Create a Git VCS root with an interactive wizard or flags:

teamcity project vcs create --project MyProject

The wizard prompts for the repository URL, display name, and authentication method. Six auth methods are supported:

# Anonymous (public repos)
teamcity project vcs create --url https://github.com/org/repo.git --auth anonymous

# Password / Personal Access Token
teamcity project vcs create --url https://github.com/org/repo.git \
  --auth password --username oauth2 --password ghp_xxx

# SSH key uploaded to TeamCity
teamcity project vcs create --url git@github.com:org/repo.git \
  --auth ssh-key --ssh-key-name my-deploy-key

# SSH key from the build agent's default key
teamcity project vcs create --url git@github.com:org/repo.git --auth ssh-agent

# SSH key at a custom path on the build agent
teamcity project vcs create --url git@github.com:org/repo.git \
  --auth ssh-file --key-path /path/to/key

# Access token via a project connection
teamcity project vcs create --url https://github.com/org/repo.git \
  --auth token --connection-id PROJECT_EXT_1

By default, the command tests the connection before creating. Skip with --no-test:

teamcity project vcs create --url https://github.com/org/repo.git --auth anonymous --no-test

vcs create flags

Flag	Description
`--url`	Repository URL
`--name`	Display name (auto-generated from URL if omitted)
`-p`, `--project`	Project ID (default: _Root)
`--auth`	Auth method: `password`, `ssh-key`, `ssh-agent`, `ssh-file`, `token`, `anonymous`
`--username`	Username (for password auth)
`--password`	Password or personal access token
`--stdin`	Read password from stdin
`--ssh-key-name`	Name of SSH key uploaded to TeamCity
`--key-path`	Path to SSH key file on the build agent
`--passphrase`	SSH key passphrase
`--connection-id`	OAuth connection ID
`--branch`	Default branch (default: `refs/heads/main`)
`--branch-spec`	Branch specification
`--no-test`	Skip connection test before creating

Testing a VCS root connection

Test whether an existing VCS root can connect to the repository:

teamcity project vcs test MyProject_GitHubRepo

Deleting a VCS root

teamcity project vcs delete MyProject_GitHubRepo
teamcity project vcs delete MyProject_GitHubRepo --yes  # skip confirmation

Managing SSH keys

SSH keys uploaded to a project can be used for VCS root authentication (TEAMCITY_SSH_KEY auth method). Keys are inherited by child projects.

Listing SSH keys

teamcity project ssh list --project MyProject
teamcity project ssh list --project MyProject --json

Generating an SSH key pair

Generate an ed25519 or RSA key pair directly in TeamCity and print the public key:

teamcity project ssh generate --name deploy-key --project MyProject
teamcity project ssh generate --name deploy-key --type rsa --project MyProject

Add the printed public key as a deploy key in your Git hosting provider.

Uploading an SSH key

teamcity project ssh upload ~/.ssh/id_ed25519 --project MyProject
teamcity project ssh upload key.pem --name my-deploy-key --project MyProject

Deleting an SSH key

teamcity project ssh delete my-deploy-key --project MyProject
teamcity project ssh delete my-deploy-key --project MyProject --yes

Project connections

Connections (OAuth providers, Docker registries, cloud integrations) are configured at the project level. They let TeamCity talk to external services without storing credentials in individual jobs, and the CLI can list, create, authorize, and delete them.

See Configuring Connections for the full TeamCity reference.

Listing connections

teamcity project connection list --project MyProject
teamcity project connection list --project MyProject --json

The first column shows the connection ID (for example, PROJECT_EXT_42). That ID is what authorize, delete, and vcs create --auth token consume.

Creating a GitHub App connection

Register a GitHub App in a project. A GitHub App authenticates as itself (no per-user token), which is the right choice for CI workflows that don't need user-context OAuth.

In interactive mode, the CLI registers a brand-new App via GitHub's manifest flow — it opens a browser, you click Create, and the credentials come back automatically:

teamcity project connection create github-app -p Backend
teamcity project connection create github-app -p Backend --owner my-org

If you already have a GitHub App, pass --no-manifest and supply the credentials yourself:

teamcity project connection create github-app -p Backend --no-manifest \
    --name "Backend" --app-id 1234567 --client-id Iv1.abc \
    --private-key-file ./key.pem --stdin <<<"$CLIENT_SECRET"

After creation the CLI prompts to run authorize so the current user gets a token bound to the App. Skip the prompt with --no-authorize.

Creating a Docker registry connection

teamcity project connection create docker -p Backend

In non-interactive setups (CI/CD), feed the password through stdin:

echo "$DOCKER_TOKEN" | teamcity project connection create docker -p Backend \
    --name GHCR --url https://ghcr.io --username my-org --stdin

Authorizing a connection

OAuth-style connections (GitHub App, Bitbucket, GitLab, …) need a per-user authorization step before TeamCity can call upstream as that user. This is required, for example, before vcs create --auth token can verify a repository over the connection.

teamcity project connection authorize PROJECT_EXT_42 -p Backend

The command opens a browser to complete the OAuth flow and stores the resulting token against the current user. Connection types without a user OAuth flow (Docker, AWS) return an error.

Deleting a connection

teamcity project connection delete PROJECT_EXT_42 -p Backend
teamcity project connection delete PROJECT_EXT_42 -p Backend --force

Pass --force (or -f) to skip the interactive confirmation prompt — useful in scripts.

Managing project parameters

Project parameters are inherited by all build configurations within the project. They work identically to job parameters.

Listing parameters

teamcity project param list MyProject
teamcity project param list MyProject --json

Getting a parameter value

teamcity project param get MyProject VERSION

Setting a parameter

teamcity project param set MyProject VERSION "2.0.0"
teamcity project param set MyProject SECRET_KEY "my-secret-value" --secure

Deleting a parameter

teamcity project param delete MyProject MY_PARAM

Secure tokens

Secure tokens allow you to reference sensitive values (passwords, API keys) in versioned settings without storing them in version control. The actual values are kept securely in TeamCity and referenced using credentialsJSON:<token> identifiers.

Storing a secure token

Store a sensitive value and receive a token reference:

# Interactive prompt for the value
teamcity project token put MyProject

# Pass the value directly
teamcity project token put MyProject "my-secret-password"

# Read from stdin (useful for piping)
echo -n "my-secret" | teamcity project token put MyProject --stdin

The command returns a token in the format credentialsJSON:<uuid>. Use this token in your versioned settings configuration files.

Retrieving a secure token value

Retrieve the original value for a secure token:

teamcity project token get MyProject "credentialsJSON:abc123-def456..."
teamcity project token get MyProject "abc123-def456..."

Versioned settings

Exporting project settings

Export project settings as a ZIP archive containing Kotlin DSL or XML configuration:

# Export as Kotlin DSL (default)
teamcity project settings export MyProject

# Export as Kotlin DSL explicitly
teamcity project settings export MyProject --kotlin

# Export as XML
teamcity project settings export MyProject --xml

# Save to a specific file
teamcity project settings export MyProject -o settings.zip

# Use relative IDs in the export
teamcity project settings export MyProject --relative-ids

The exported archive can be used to version control your CI/CD configuration, migrate settings between TeamCity instances, or review settings as code.

settings export flags

Flag	Description
`--kotlin`	Export as Kotlin DSL (default)
`--xml`	Export as XML
`-o`, `--output`	Output file path (default: `projectSettings.zip`)
`--relative-ids`	Use relative IDs in the exported settings (enabled by default)

Viewing versioned settings sync status

Check the synchronization status of versioned settings for a project:

teamcity project settings status MyProject
teamcity project settings status MyProject --json

This displays whether versioned settings are enabled, the current sync state, last successful sync timestamp, VCS root and format information, and any errors from the last sync attempt.

Validating Kotlin DSL

Validate Kotlin DSL configuration by running the TeamCity configuration generator:

teamcity project settings validate
teamcity project settings validate ./path/to/.teamcity
teamcity project settings validate --verbose

The command auto-detects the .teamcity directory in the current directory or its parents. It requires Maven (mvn) or uses the Maven wrapper (mvnw) if present in the DSL directory.

06 May 2026