Managing Projects

Projects organize build configurations and subprojects in TeamCity. The teamcity project command group lets you browse projects, 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)

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

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.

23 February 2026