Command Line Remote Run Tool

General Info

Plugin Description

TeamCity Command Line Remote Run tool allows running Personal Builds from the command line (Windows, Linux, Mac are supported, provided there is a JRE installed).

The tool has no integration with a version control. It's function is to start a personal build for the supplied list of files.
The server supports running personal builds for the sources stored under Subversion, CVS, Perforce and Git. Experimental support for ClearCase is also available.

The preferred way to start personal builds is to use IDE plugins, which integrate with version control and also provide ability to do pre-tested commits after successful personal build.

Since TeamCity 6.5 for Git and Mercurial you should really consider using remote run on branches, rather than this tool. If you still prefer the tool to remote run on branches, please make sure to drop us a line on that.

Download

Plugin is available for different TeamCity versions. You can download them directly from the public TeamCity server:

2018.1.x-compatible version    

2017.2.x-compatible version                              

2017.1.x-compatible version

10.0.x-compatible version

9.1.x-compatible version

9.0.x-compatible version

8.1.x-compatible version

Documentation

Installation instructions

1. Put command.line.zip into <TeamCity Data Directory>/plugins folder.
2. Restart the server.
   
   

After installation, navigate to the  My Settings&Tools page (available on clicking the arrow next to your username in the top right corner of the TeamCity web UI) . The TeamCity Tools side panel should contain Command Line Remote Run.

Plugin usage

1. Make sure  Java JRE 1.5.+ is installed on your working machine.
2. After installing the plugin, navigate to  My Settings&Tools| TeamCity Tools side panel | Command Line Remote Run and click download to save the tcc.jar file to your file system.
   The tool is run with the 'java -jar <path to tcc.jar> <command> <options>' command.
   The list of available commands is available upon 'java -jar <path to tcc.jar> help'. 
   To get  commands description, run 'java -jar <path to tcc.jar> help <command>'
3. Next, create the .teamcity-mappings.properties configuration file which maps local directory paths in your project workspace to VCS settings in TeamCity. For details see the section below.

4. Login to TeamCity with command line runner tool:

   You will be prompted to enter the password. The "login" command persists credentials for the target host to avoid authorization options for subsequent starts. The last logged in <server URL> is treated as the default one and will be used if the "--host" key is omitted. You will need to specify the server URL for the 'run' command only.

5. To run a remote build, the tool also requires:
   1. The external ID of the target build configuration on the server. The buildTypeID is displayed in the drop-down list of available build configurations on the configuration web UI page of the Command Line Remote Run tool.
   2. A comment to the personal build.
   3. The path to the changed files to be included in a personal build. You can provide the path either to the directory with modified files or to a file with the list of changed files (such file can be prepared with help of the VCS own tools).

   Collect the required information and run a remote build on the specified list of files for the selected build configuration:

   By default the "run" command will wait for the build to finish and returns the code corresponding to the status of the build. This exit code can be used to perform a commit.

Сonfiguring plugin via UI options

The plugin provides a web UI configuration page which helps to create the .teamcity-mapping.properties file.

1. To open the tool's settings page, navigate to the  My Settings&Tools page| TeamCity Tools side panel | Command Line Remote Run and click configure.
2. Create a mapping configuration file: select a build configuration to run your personal build on from the dropdown with and click Add.

3. The mappings contain pairs of paths to local directories with changed files and remote VCS Root's prefixes. A local path can be absolute or relative to the location of the mapping file folder. Check the mappings table and edit it if needed. 

4. When done, copy the resulting content of the configuration file to your .teamcity-mappings.properties file.
5. Put the configuration file in any the following directories:

• root directory of the project sources to be sent to remote run (recommended)

• %HOME%/.TeamCity-CommandLine default directory

Feedback/Support

If you believe you've faced a bug: Issue Tracker (project: TeamCity)
If you want to ask a question or discuss: Forum

Development links

Sources in JetBrains Subversion repository.
Trunk builds at JetBrains public TeamCity instance.