### Example: Get Current User Info

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-rest-api-access.html

A simple example demonstrating how to retrieve information about the currently authenticated user.

```bash
# Get current user info
teamcity api '/app/rest/users/current'
```

--------------------------------

### Complete Kotlin DSL Setup for GitHub App Connection and Build

Source: https://www.jetbrains.com/help/teamcity/build-scoped-token.html

This comprehensive example demonstrates the full Kotlin DSL setup, including creating a GitHub App connection with build-scoped token support enabled and configuring a build step to use the generated token for an authorized API request.

```kotlin
version = "2026.1"

project {
    buildType(Build)

    features {
        githubAppConnection {
            id = "PROJECT_EXT_79"
            displayName = "GHA with tokens"
            appId = "APP_ID"
            clientId = "CLIENT_ID"
            clientSecret = "CLIENT_SECRET"
            privateKey = "PRIVATE_KEY"
            ownerUrl = "https://github.com/OWNER"
            useUniqueCallback = true
            allowBuildScopedTokens = true
        }
    }

object Build : BuildType({
    name = "Build"

    params { param("GhaToken", "n/a") }

    steps {
        script {
            id = "simpleRunner_1"
            scriptContent = """
                curl -L \
                  -X POST \
                  -H "Accept: application/vnd.github+json" \
                  -H "Authorization: Bearer %GhaToken%" \
                  -H "X-GitHub-Api-Version: 2026-03-10" \
                  https://api.github.com/repos/OWNER/REPO/pulls \
                  -d '{"title":"Amazing new feature","body":"Please pull these awesome changes in!","head":"new-feature","base":"main"}'
            """.trimIndent()
        }
    }

    features {
        gitHubAppBuildScopedToken {
            parameterName = "GhaToken"
            connectionId = "PROJECT_EXT_79"
            targetRepositories = "REPO"
        }
    }
})

```

--------------------------------

### TeamCity CLI Quick Start Commands

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli.html

A set of essential commands to get started with TeamCity CLI, including authentication, listing builds, starting and watching builds, viewing logs, and checking the queue.

```bash
# Authenticate with your TeamCity server
teamcity auth login

# List recent builds
teamcity run list --limit 10

# Start a build and watch it run
teamcity run start MyProject_Build --branch main --watch

# View logs from the latest build of a job
teamcity run log --job MyProject_Build

# Check what's in the queue
teamcity queue list
```

--------------------------------

### Example AI Agent Command: Start Build

Source: https://www.jetbrains.com/help/teamcity/ai-agent-integration.html

An example of a natural language command an AI agent can use to start a new build in TeamCity.

```text
“Start a new build in TeamCity configuration related to this project.”
```

--------------------------------

### Start Build Agent Service (Windows)

Source: https://www.jetbrains.com/help/teamcity/agent-home-directory.html

Starts the build agent using the previously installed Windows service.

```batch
service.start.bat
```

--------------------------------

### Examples

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-rest-api-access.html

A collection of examples demonstrating various use cases of the `teamcity api` command, including getting user info, listing VCS roots, triggering builds, and downloading artifacts.

```APIDOC
## Examples

```
# Get current user info
teamcity api '/app/rest/users/current'

# List all VCS roots
teamcity api '/app/rest/vcs-roots'

# Get build statistics
teamcity api '/app/rest/builds/12345/statistics'

# Trigger a build with parameters
teamcity api '/app/rest/buildQueue' -X POST \
  --input <(echo '{"buildType":{"id":"MyBuild"},"properties":{"property":[{"name":"version","value":"1.0"}]}}')

# Download a specific artifact
teamcity api '/app/rest/builds/12345/artifacts/content/report.html' --raw > report.html
```
```

--------------------------------

### Jira Cloud Git Path Format Example

Source: https://www.jetbrains.com/help/teamcity/upgrade-notes.html

Illustrates the manual change required for Git URLs when the Jira Cloud API does not recognize the format. Use this if the fixed plugin is not yet installed.

```text
git@<vcs_address>:<workspace_ID>/<repo_name>.git
ssh://git@<vcs_address>/<workspace_ID>/<repo_name>.git
```

--------------------------------

### Example JDK Environment Variables

Source: https://www.jetbrains.com/help/teamcity/upgrade-notes.html

Provides examples of the new `env.JDK_` format for different Java versions, including 64-bit variants.

```text
env.JDK_1_6
env.JDK_1_7
env.JDK_1_8
env.JDK_11_0_x64
```

--------------------------------

### Example Log Output for TFS Changes

Source: https://www.jetbrains.com/help/teamcity/upgrade-notes.html

This log snippet shows potential error messages related to collecting TFS changes, indicating version discrepancies.

```text
Error
  collecting changes
 for
  VCS repository
 ...


 Failed
  to collect TFS changes
 -

  From
  version x
 is
  greater
 then
  current version y
```

--------------------------------

### Whitelist Custom NuGet Executable Path

Source: https://www.jetbrains.com/help/teamcity/upgrade-notes.html

If using a custom NuGet executable with the NuGet dependency trigger, add its path to the whitelist using this internal property. This is an alternative to using NuGet versions installed via the TeamCity UI.

```properties
teamcity.nuget.server.cli.path.whitelist=<disk>: \\<path-to-executable>\\NuGet.exe
```

--------------------------------

### Configure Command Example

Source: https://www.jetbrains.com/help/teamcity/cloud/install-teamcity-agent.html

An example of using the 'configure' command to set up the build agent properties, including server URL, agent name, and authentication token. This is an alternative to manual file editing.

```bash
./bin/agent.sh configure --serverUrl "https://teamcity.example.com" --name "MyAgent" --token "YOUR_TOKEN"
```

--------------------------------

### Get Parameter Values via REST API

Source: https://www.jetbrains.com/help/teamcity/cloud/configuring-build-parameters.html

This example shows how to retrieve initial, starting, and resulting parameter values for a specific build using GET requests to the TeamCity REST API.

```APIDOC
### Track Parameter Values

When a build finishes, you can check out all parameters that were present during this build on the Parameters tab of the Build Results page. TeamCity highlights new parameters and those whose values changed during the build.

To check initial and actual parameter values of the specific build via REST API, send GET requests to the `/app/rest/builds/[{buildLocator}](https://www.jetbrains.com/help/teamcity/rest/buildlocator.html)` endpoint and specify required payload fields according to the Build schema.

* `/app/rest/builds/{buildLocator}?fields=originalProperties(*)` — returns user-defined parameters from the build configuration and their default values.
* `/app/rest/builds/{buildLocator}?fields=startProperties(*)` — returns all parameters reported by an agent and their values at the time the build started.
* `/app/rest/builds/{buildLocator}?fields=resultingProperties(*)` — returns all parameters reported by an agent and their values by the time the build finished.

You can also check initial and final values of the specific parameter. To do this, specify the name of the target parameter:

```bash
curl -L \
  https:<SERVER_URL>/app/rest/builds/<BUILD_LOCATOR>?fields=
    originalProperties($locator(name:(value:(myParam),matchType:matches)),property),
    startProperties($locator(name:(value:(myParam),matchType:matches)),property),
    resultingProperties($locator(name:(value:(myParam),matchType:matches)),property)
```
```

--------------------------------

### Example Build Step Commands

Source: https://www.jetbrains.com/help/teamcity/project-administrator-guide.html

Illustrates common commands that can be used as build steps. These can be single commands or sequences of operations.

```text
mvn test
```

```text
gradle clean build
```

--------------------------------

### Start TeamCity Agent Manually on Linux/macOS

Source: https://www.jetbrains.com/help/teamcity/cloud/start-teamcity-agent.html

Use this command to manually start a TeamCity agent on Linux or macOS. Replace `<installation path>` with the correct installation directory.

```shell
<installation path>/bin/agent.sh start
```

--------------------------------

### Example Matrix Build Parameters

Source: https://www.jetbrains.com/help/teamcity/cloud/matrix-build.html

Illustrates the parameters and their values for a matrix build. This helps visualize the combinations that will be generated.

```text
Browser: Chrome, Safari, Firefox
env.ShouldFail: true, false
Java: 11, 17, 21
```

--------------------------------

### SMB Upload Source Path Examples

Source: https://www.jetbrains.com/help/teamcity/cloud/smb-upload.html

Examples of specifying deployment sources, including Ant-style wildcards and creating target directories. Paths can be newline- or comma-separated.

```text
*.zip => winFiles,unix/distro.tgz => linuxFiles
```

--------------------------------

### Start TeamCity Agent Manually on Windows

Source: https://www.jetbrains.com/help/teamcity/cloud/start-teamcity-agent.html

Use this command to manually start a TeamCity agent on a Windows machine. Ensure you replace `<installation path>` with the actual installation directory.

```batch
<installation path>\bin\agent.bat start
```

--------------------------------

### Example Agent Configuration

Source: https://www.jetbrains.com/help/teamcity/cloud/configure-agent-installation.html

This example demonstrates a typical configuration for the buildAgent.properties file, including server URL, agent name, and directory settings. Ensure the file is writable by the build agent process.

```properties
## The address of the TeamCity server. The same as is used to open the TeamCity web interface in the browser.
## Must include the protocol specification (https:// is recommended).
serverUrl=http://localhost:8111/

## The unique name of the agent used to identify this agent on the TeamCity server
## Use blank name to let server generate it.
## By default, this name would be created from the build agent's host name
name=Default agent

## Container directory to create default checkout directories for the build configurations.
workDir=../work

## Container directory for the temporary directories.
## Please note that the directory may be cleaned between the builds.
tempDir=../temp

## Container directory for agent state files and caches.
## TeamCity agent assumes ownership of the directory and can delete the content inside.
systemDir=../system


######################################
#   Optional Agent Properties        #
######################################
## A token which is used to identify this agent on the TeamCity server for agent authorization purposes.
## It is automatically generated and saved back on the first agent connection to the server.
authorizationToken=1234567890abcdefghijklml
```

--------------------------------

### Start a Cloud Instance from an Image

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-managing-cloud-agents.html

Initiate a new cloud instance from a selected image. The command returns the new instance ID upon successful provisioning. Use the `--json` flag for JSON output.

```bash
teamcity project cloud image start ubuntu-22-large
```

```bash
teamcity project cloud image start ubuntu-22-large --json
```

--------------------------------

### Install Amazon Corretto 21 Java

Source: https://www.jetbrains.com/help/teamcity/install-teamcity-server-on-linux-or-macos.html

Installs Amazon Corretto 21 JDK on Ubuntu using a .deb package. This is an example of how to install a compatible Java version if one is not already present.

```bash
root@ubuntu:/opt# apt install java-common -y
root@ubuntu:/opt# wget https://corretto.aws/downloads/latest/amazon-corretto-21-x64-linux-jdk.deb
root@ubuntu:/opt# dpkg --install amazon-corretto-21-x64-linux-jdk.deb
# verify the installation
root@ubuntu:/opt# java -version
openjdk version "21.0.18" 2025-01-17 LTS
OpenJDK Runtime Environment Corretto-21.0.18.10.1 (build 21.0.18+10-LTS)
OpenJDK 64-Bit Server VM Corretto-21.0.18.10.1 (build 21.0.18+10-LTS, mixed mode)
```

--------------------------------

### Start and Watch a Build

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-managing-runs.html

Initiate a build and follow its progress in real-time. You can also set a timeout or adjust the polling interval.

```bash
teamcity run start MyProject_Build --branch main --watch
```

```bash
teamcity run start MyProject_Build --watch --timeout 30m
```

```bash
teamcity run start MyProject_Build --watch --interval 10
```

--------------------------------

### Start a Build

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-managing-runs.html

Use this command to trigger a new build for a specified build configuration.

```bash
teamcity run start MyProject_Build
```

--------------------------------

### Start TeamCity Agent Service on Windows

Source: https://www.jetbrains.com/help/teamcity/cloud/start-teamcity-agent.html

Use this command to start the TeamCity build agent service on Windows. Ensure the service is installed and configured correctly.

```bash
net start TCBuildAgent
```

--------------------------------

### Start TeamCity Agent on Linux/macOS

Source: https://www.jetbrains.com/help/teamcity/start-teamcity-agent.html

Use this command to manually start the TeamCity agent service on Linux or macOS. Ensure the path points to your TeamCity installation directory.

```shell
./bin/agent.sh start
```

--------------------------------

### Build Step Example

Source: https://www.jetbrains.com/help/teamcity/pipelines-yaml-syntax.html

A build step example using a specific tool or command. Ensure the tool is available in the build environment.

```yaml
build:
  id: "build_project"
  name: "Build Project"
  type: "maven"
  goals: "clean install -DskipTests"
```

--------------------------------

### Start TeamCity Agent on Windows

Source: https://www.jetbrains.com/help/teamcity/start-teamcity-agent.html

Use this command to manually start the TeamCity agent service on a Windows machine. Ensure the path points to your TeamCity installation directory.

```batch
.in\agent.bat start
```

--------------------------------

### Example: Get Build Statistics

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-rest-api-access.html

Fetch statistics for a specific build, identified by its ID.

```bash
# Get build statistics
teamcity api '/app/rest/builds/12345/statistics'
```

--------------------------------

### Enable init.d service on Debian/Ubuntu

Source: https://www.jetbrains.com/help/teamcity/cloud/start-teamcity-agent.html

Configure the build agent service to start on boot for Debian/Ubuntu systems.

```bash
sudo update-rc.d buildAgent defaults
```

--------------------------------

### Useful alias examples: Build workflows

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-aliases.html

Aliases to streamline common build operations like starting, trying, hotfixing, or retrying builds.

```bash
teamcity alias set go       'run start $1 --watch'
```

```bash
teamcity alias set try      'run start $1 --local-changes --watch'
```

```bash
teamcity alias set hotfix   'run start $1 --top --clean --watch'
```

```bash
teamcity alias set retry    'run restart $1 --watch'
```

--------------------------------

### Example: Trigger a Build with Parameters

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-rest-api-access.html

Trigger a build in the queue and provide build parameters using a JSON input. The input can be provided via process substitution or stdin.

```bash
# Trigger a build with parameters
teamcity api '/app/rest/buildQueue' -X POST \
  --input <(echo '{"buildType":{"id":"MyBuild"},"properties":{"property":[{"name":"version","value":"1.0"}]}}')
```

--------------------------------

### Open build configuration page in browser

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-managing-jobs.html

Quickly access the web interface for a specific build configuration using the `--web` flag.

```bash
teamcity job view MyProject_Build --web
```

--------------------------------

### Run Build Commands

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-cli-glossary.html

Commands to list and start builds. Use 'run list' to see all builds and 'run start' with a build configuration name to initiate a build.

```bash
teamcity run list
```

```bash
teamcity run start MyProject_Build
```

--------------------------------

### Access TeamCity Server Info via REST API

Source: https://www.jetbrains.com/help/teamcity/cloud/teamcity-rest-api.html

Open this URL in your browser to get pointers to explore the TeamCity REST API. This is a starting point for understanding the available API endpoints.

```HTTP
http://<TeamCity Server host>:<port>/app/rest/server
```

--------------------------------

### Example Build Step: cURL Commands

Source: https://www.jetbrains.com/help/teamcity/configure-and-run-your-first-build.html

Demonstrates a series of consecutive cURL commands used as a build step to upload a project to an FTP server. Build steps run on the same machine as their neighboring steps.

```shell
curl -T "project.zip" ftp://ftp.example.com/files/project.zip -u user:password
```

--------------------------------

### Getting the VCS Branch Name

Source: https://www.jetbrains.com/help/teamcity/cloud/predefined-build-parameters.html

For Git and Mercurial, this parameter provides the name of the VCS branch known at the moment the build started. It may differ from the logical branch name defined in the branch specification.

```text
teamcity.build.vcs.branch.<VCS_root_ID>
```

--------------------------------

### Example Matrix Build Parameters (UI Configuration)

Source: https://www.jetbrains.com/help/teamcity/cloud/matrix-build.html

Shows how to configure matrix parameters in the TeamCity UI, defining parameter names and their associated values.

```text
Browser: Chrome, Firefox
Java: jdk-17, jdk-21
```

--------------------------------

### Configure init.d for TeamCity Agent on Linux

Source: https://www.jetbrains.com/help/teamcity/cloud/start-teamcity-agent.html

This init.d script provides a basic setup for managing the TeamCity build agent service on Linux systems using the older init system. It includes start and stop actions.

```bash
#!/bin/sh
### BEGIN INIT INFO
# Provides:          TeamCity Build Agent
# Required-Start:    $remote_fs $syslog
# Required-Stop:     $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Start build agent daemon at boot time
# Description:       Enable service provided by daemon.
### END INIT INFO
#Provide the correct user name:
USER="agentuser"

case "$1" in
start)
 su - $USER -c "cd BuildAgent/bin ; ./agent.sh start"
;; 
stop)
 su - $USER -c "cd BuildAgent/bin ; ./agent.sh stop"
;; 
*)
  echo "usage start/stop"
  exit 1
;;

esac

exit 0
```

--------------------------------

### Navigate to init.d directory

Source: https://www.jetbrains.com/help/teamcity/cloud/start-teamcity-agent.html

Change directory to the service scripts location for init.d.

```bash
cd /etc/init.d/
```

--------------------------------

### Retrieve Build Parameters via REST API

Source: https://www.jetbrains.com/help/teamcity/configuring-build-parameters.html

Use GET requests to the `/app/rest/builds/{buildLocator}` endpoint to retrieve initial, start, or resulting parameter values for a specific build. Specify the `fields` parameter to select the desired properties.

```bash
curl -L \
  https:<SERVER_URL>/app/rest/builds/<BUILD_LOCATOR>?fields=
    originalProperties(*),startProperties(*),
    resultingProperties(*)
```

```bash
curl -L \
  https:<SERVER_URL>/app/rest/builds/<BUILD_LOCATOR>?fields=
    originalProperties($locator(name:(value:(myParam),matchType:matches)),property),
    startProperties($locator(name:(value:(myParam),matchType:matches)),property),
    resultingProperties($locator(name:(value:(myParam),matchType:matches)),property)
```

--------------------------------

### String Start/End Check Conditions

Source: https://www.jetbrains.com/help/teamcity/cloud/requirement-conditions.html

Conditions to check if a property value starts or ends with a specific string. Example: `startsWith("teamcity.agent.jvm.os.name", "Mac")` and `endsWith("teamcity.agent.work.dir", "/work")`.

```groovy
startsWith("teamcity.agent.jvm.os.name", "Mac")
```

```groovy
endsWith("teamcity.agent.work.dir", "/work")
```

--------------------------------

### Enable init.d service on Red Hat/CentOS

Source: https://www.jetbrains.com/help/teamcity/cloud/start-teamcity-agent.html

Configure the build agent service to start on boot for Red Hat/CentOS systems.

```bash
sudo chkconfig buildAgent on
```