Command-Line Client for Developers (teamscale-dev)

This article describes teamscale-dev, the Teamscale command-line client for developers. Among other things, this client can be used to integrate Teamscale with IDEs for which no dedicated IDE plug-in exists.

• Installation
• Commands
  • The pre-commit Command
  • The fetch-findings Command
  • The open-in-browser Command
  • The generate-completion Command
• Common Options
  • Supplying Server Credentials
  • Disabling TLS Certificate Validation
  • Overriding Branch Information
  • Finding Output Format
  • Logging (--debug, --trace)
• License

Installation

The CQSE website offers both platform-specific (for Windows, Linux, macOS) and platform-independent downloads for installation.

Commands

The command-line client for developers exposes its functionality as a set of commands. You can use the built-in help option, --help, to list all available commands.

teamscale-dev --help

The various commands can be further configured by command-line options. Many options are common to most if not all commands, while others are specific to a command and explained in the following alongside their respective command. Additional configuration is taken from .teamscale.toml IDE configuration files.

The pre-commit Command

The pre-commit (or precommit) command uploads files to Teamscale for pre-commit analysis and, once the analysis is finished, displays findings for them in a common format.

You can use this command in three ways:

1. Automatic Selection of Files for Analysis (default):

   By default, the pre-commit command will automatically determine whether the given paths are under version control (Git and Subversion supported). If so, only those files that have uncommitted changes will be uploaded. If not, all files and directories (including subdirectories) are uploaded to the Teamscale server.

   Mixture of Versioned and Unversioned Paths

   If only some paths are under version control, a warning is displayed, as this may not be what the user intended: Version-controlled files are uploaded only if they contain uncommitted changes, whereas unversioned files are uploaded regardless.

   teamscale-dev pre-commit src/Example.java

   teamscale-dev pre-commit src/

   Large Uploads

   Uploading a large number of files at once can take a long time and increase the server load. It is hence common (in fact, the default) that a Teamscale server has pre-commit limits configured, limiting the number and size of files included in a single pre-commit upload. Uploads exceeding these limits are rejected.

2. Automatic Selection of Uncommitted Changes for Analysis:

   If the given paths are under version control (Git and Subversion supported), and the --only-uncommitted-changes option is used, only those files that have uncommitted changes will be uploaded.

   teamscale-dev pre-commit --only-uncommitted-changes src/

   If not all the given paths are under version control, the pre-commit command will fail instead of uploading unchanged files. To make your intention explicit and safeguard against such accidental uploads, we hence recommend to always use this option if you believe that the paths in question are under version control.

3. Explicit Selection of Files for Analysis:

   If the --no-change-detection option is used, all given files and directories (including subdirectories) are uploaded to the Teamscale server, even if they are under version control and, according to the version-control system, unchanged.

   teamscale-dev pre-commit --no-change-detection src/Example.java

   Large Uploads

   Uploading a large number of files at once can take a long time and increase the server load. It is hence common (in fact, the default) that a Teamscale server has pre-commit limits configured, limiting the number and size of files included in a single pre-commit upload. Uploads exceeding these limits are rejected.

   Using --no-change-detection should hence be restricted to uploading single files.

Further options, e.g., --show-links-to-findings and --findings-to-stderr control how and where the findings are reported.

The fetch-findings Command

The fetch-findings command fetches findings from Teamscale for one or more paths and displays them in a common format. Unlike the pre-commit, fetch-findings does not upload local files to Teamscale; it shows the findings as they exist on the remote server.

You can use this command in two ways:

1. Fetch findings for one or more files: For example:

teamscale-dev fetch-findings src/Example.java src/Utils.java

2. Fetch findings for one or more directories: For example:

teamscale-dev fetch-findings src/main/java src/test/java

A mixture of files and directories in the same fetch-findings command is not supported at the moment.

The open-in-browser Command

The open-in-browser (or browse) command opens the Metrics > Files view in a Web browser, showing the given files and directories as they are known to Teamscale. For example:

teamscale-dev open-in-browser src/Example.java

teamscale-dev open-in-browser src/

The Web browser used by teamscale-dev is your desktop's default browser. Consult your operating system's documentation for how to change this.

The generate-completion Command

The generate-completion command outputs a script that configures the programmable completion of the bash and zsh Unix shells to recognize teamscale-dev and offer tab-completion for it.

source <( teamscale-dev generate-completion )

To permanently install tab-completion support for teamscale-dev, you can either place the above line in your shell's profile (e.g., ~/.bash_profile) or save the output of teamscale-dev generate-completion to a file and execute it from there (e.g., by placing it in a bash-completion.d directory). Consult your operating system's documentation for the exact details.

Common Options

Many command-line options are common to most if not all commands offered by teamscale-dev. These are described in the following.

In particular, you can use the help option, --help, built into all commands to list their respective options. For example:

teamscale-dev pre-commit --help

Supplying Server Credentials

Some commands like pre-commit, fetch-findings or open-in-browser require you to supply your credentials for a Teamscale server, i.e., your username and access key. You can pass these credentials to the commands in five ways:

1. The --user and --accesskey Command-Line Options
2. The --server Command-Line Option
3. The TEAMSCALE_DEV_USER and TEAMSCALE_DEV_ACCESSKEY Environment Variables
4. The TEAMSCALE_DEV_SERVERS Environment Variable
5. Supplying Command-Line Options via an Args File

Accidentally Exposing the Access Key in Multi-User Environments

Passing the --accesskey or --server options directly may accidentally expose your access key if other users on the same machine can inspect the command line of running commands (e.g., using Linux/macOS ps or the Windows Task Manager). Therefore, it ss highly recommended to either set the TEAMSCALE_DEV_SERVERS environment variable, set the TEAMSCALE_DEV_USER and TEAMSCALE_DEV_ACCESSKEY environment variables, or supply command-line options via an args file.

The --user and --accesskey Command-Line Options

teamscale-dev pre-commit --user username --accesskey accesskey ...

Together, the --user and --accesskey options supply the credentials to use for all servers referenced in the applicable configuration files (.teamscale.toml), unless they are explicitly associated with a server URL using either a --server option or the TEAMSCALE_DEV_SERVERS environment variable.

The --server Command-Line Option

teamscale-dev pre-commit --server https://username:accesskey@example.com/teamscale/ ...

The --server options associate credentials with a particular server URL, encoded as a so-called credentials URL. As it can occur multiple times, it allows you to supply different credentials to different servers.

The TEAMSCALE_DEV_USER and TEAMSCALE_DEV_ACCESSKEY Environment Variables

You can set the environment variables TEAMSCALE_DEV_USER and TEAMSCALE_DEV_ACCESSKEY to supply the information from the --user and --accesskey command-line options. Note that it is not possible to mix the use of environment variables and command-line options for the user and access key.

On Linux and macOS add the following line to your shell environment configuration file (e.g. .bashrc or .zshrc file in your user home directory).

export TEAMSCALE_DEV_USER="username"
export TEAMSCALE_DEV_ACCESSKEY="accesskey"

On Windows follow these steps to set up a user-specific environment variable.

1. Click Start button
2. Search for Accounts
3. Open User Accounts
4. Go to Tasks > Change my environment variables
5. Add a new environment called TEAMSCALE_DEV_USER with value of your username.
6. Add a new environment called TEAMSCALE_DEV_ACCESSKEY with the value of your access key.

The TEAMSCALE_DEV_SERVERS Environment Variable

Recommended for Terminal Usage

Setting up the environment variable for your user is the most convenient option for usage of the CLI in a terminal since it allows you to omit any command-line options for credentials when using teamscale-dev.

You can set the TEAMSCALE_DEV_SERVERS environment variable for your user to supply the information from the --server command-line option. It may contain multiple values of the --server command-line option separated by spaces.

On Linux and macOS add the following line to shell environment configuration file (e.g. .bashrc or .zshrc file in your user home directory).

export TEAMSCALE_DEV_SERVERS="https://username:accesskey@example.com/teamscale/"

On Windows follow these steps to set up a user specific environment variable.

1. Click Start button
2. Search for Accounts
3. Open User Accounts
4. Go to Tasks > Change my environment variables
5. Add a new environment called TEAMSCALE_DEV_SERVERS with the following value:

   https://username:accesskey@example.com/teamscale/

Supplying Command-Line Options via an Args File

You can use a so-called args file containing the --user, --accesskey, and --server options from above to avoid access keys being visible in your shell history or list of active processes. It is recommended to create this file in the user home directory of your operating system (i.e. /home/<username>/.teamscale-dev.args on Linux, C:\\Users\<username> on Windows, /Users/<username>/.teamscale-dev.args on MacOS) to allow re-using it across multiple repositories.

Example content of .teamscale-dev.args:

--server https://username:accesskey@example.com/teamscale/

Then, include the options from the argument file using the @-notation:

teamscale-dev pre-commit @"${HOME}/.teamscale-dev.args" ...

Credentials Precedence

All five ways to supply credentials can be used at the same time. For a particular server URL, the --server command-line pption takes precedence over the TEAMSCALE_DEV_SERVERS environment variable. If no credentials are associated with a particular server URL, the --user and --accesskey command-line options apply and take precedence over the TEAMSCALE_DEV_USER and TEAMSCALE_DEV_ACCESSKEY environment variables. Any command-line options supplied via an args file behave as if they were passed directly in its place.

Credentials URL Format

Credentials URLs associate your username and accesskey with a Teamscale server's URL. They are constructed as follows:

If the Teamscale server's URL in your configuration file (.teamscale.toml) is, for example, https://example.com/teamscale/, then the corresponding credentials URL would look like https://username:accesskey@example.com/teamscale/, with username and accesskey replaced by your username and access key, respectively.

Special Characters in Username and Access Key

Certain characters cannot be used verbatim in credentials URLs; they need to be percent-escaped. In particular, this applies to the colon (%3A) and @-sign (%40). A username of user@example.com, for example, should be written as user%40example.com. To correct this common error, however, teamscale-dev uses a heuristic and automatically escapes @-signs in usernames. (Other reserved characters still need to be escaped.)

Optionally, the credentials URL can end with a #trust-all-certificates suffix, which disables TLS certificate validation for the server in question.

Disabling TLS Certificate Validation

Risk of Man-in-the-Middle Attacks

Disabling TLS certificate validation is insecure and increases the risk of successful man-in-the-middle attacks. It should only be done as a method of last resort or in testing environments.

Some commands like pre-commit and fetch-findings connect to a Teamscale server. Such a connection may fail with a certificate-validation error when, for example, the server uses a self-signed certificate. In this case, you can disable TLS certificate validation in several ways:

1. The --insecure command-line option:

teamscale-dev pre-commit --insecure ...

2. The --server command-line option with #trust-all-certificates suffix:

teamscale-dev pre-commit --server https://username:accesskey@example.com/teamscale/#trust-all-certificates ...

3. The TEAMSCALE_DEV_SERVERS environment variable with #trust-all-certificates suffix:

export TEAMSCALE_DEV_SERVERS="https://username:accesskey@example.com/teamscale/#trust-all-certificates"
teamscale-dev pre-commit ...

Overriding Branch Information

Some commands like pre-commit, fetch-findings, and open-in-browser need to determine which branch has been checked out from the version-control system. This happens automatically for supported version-control systems (Git, Subversion). If your version-control system is unsupported by teamscale-dev or if you need to override the branch that has been automatically determined, you can override it explicitly.

In order of precedence, the branch is determined from these sources:

1. --branch command-line option
2. project.branch property in your configuration file (.teamscale.toml)
3. Branch checked out from version control
4. Default branch of the respective Teamscale server

Finding Output Format

Commands that report findings (e.g., pre-commit or fetch-findings) do so in the GCC diagnostics format:

Path:Line:Column: (error|warning): Message

• Path is an absolute path to the (local) file for which findings are reported
• Line (starting with 1) and Column (always 1) numbers denote the first position within the file where the finding is found.
• error and warning corresponding to red and yellow findings, respectively.
• Message is the finding's descriptive message

If the --show-links-to-findings command-line option is used, an extended format is used:

Path:Line:Column: (error|warning): Message | (Link)

• Link is a URL to open the Findings Detail view in a Web browser.

By default, findings are reported to stdout but can be redirected to stderr by using the --findings-to-stderr command-line option.

Logging (--debug, --trace)

In case any problems arise or you need to report an issue to our support, you can log debug or trace information by using the --debug or --trace options, respectively. These options are supported by all subcommands of teamscale-dev.

Optionally, you can refine which information is logged by specifying one or more categories. For example:

teamscale-dev --debug # --debug ALL

teamscale-dev --debug FINDINGS,SERVERS # --debug FINDINGS --debug SERVERS

You can look up the exact list of supported categories using the --help option.

License

The teamscale-dev tool is licensed under the Apache License 2.0.

Some third-party libraries included in the distribution may be subject to different license terms. For a full list of included libraries and their licenses, please refer to the legal/ directory in the teamscale-dev distribution package.