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
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 two ways:
- Explicitly Uploading Files for Analysis: You can upload files or directories (including subdirectories) by passing them on the command line. For example:
teamscale-dev pre-commit src/Example.java
teamscale-dev pre-commit src/
- Automatically Uploading Only Uncommitted Changes for Analysis: If the files and directories are under version control by a supported system (Git, Subversion), you can use the
--only-uncommitted-changes
option to restrict the upload to only those files that have uncommitted changes. For example:
teamscale-dev pre-commit --only-uncommitted-changes src/
This will automatically determine which files below src/
have local changes and only upload those for pre-commit analysis. (Files and directories not version-controlled by a supported system will never be uploaded when --only-uncommitted-changes
is used.)
Pre-Commit Upload Limits
A Teamscale server may have an upload limit configured for the number of files included in a single pre-commit upload. Uploading entire directories is often prone to exceed this limit, even if only a few files therein have actually been changed. Using the --only-uncommitted-changes
option avoids this problem in most cases, i.e., for smaller changes.
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:
- Fetch findings for one or more files: For example:
teamscale-dev fetch-findings src/Example.java src/Utils.java
- 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 four ways:
- The
--user
and--accesskey
Command-Line Options - The
--server
Command-Line Option - The
TEAMSCALE_DEV_SERVERS
Environment Variable - 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 ps
or the Task Manager). Therefore it's highly recommended to either set the TEAMSCALE_DEV_SERVERS
environment variable or supply command-line options via an args file.
The --user
and --accesskey
Command-Line Options
teamscale-dev pre-commit --user username --accesskey accesskey ...
These supply the username and access key to use for all servers referenced in the applicable configuration files (.teamscale.toml
), unless they are configured explicitly using a --server
option or the TEAMSCALE_DEV_SERVERS
environment variable. (If you need to supply different credentials for different server URLs, you have to resort to one of the following alternatives.)
The --server
Command-Line Option
teamscale-dev pre-commit --server https://username:accesskey@example.com/teamscale/ ...
(You can use the --server
option multiple times to supply credential URLs for multiple servers.)
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 flags. 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.
- Click Start button
- Search for
Accounts
- Open User Accounts
- Go to Tasks > Change my environment variables
- 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 --server
, --user
and --accesskey
options from above to avoid access keys visible in your shell history or list of active processes. It's 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 four ways can be used at the same time. If different credentials are given for the same server URL, then the --server
option takes precedence over the TEAMSCALE_DEV_SERVERS
variable. Finally, the --user
and --accesskey
apply to any server whose credentials are not explicitly supplied via a credential URL. The command line options from an args file behave as if they were passed directly in its place.
Credential URL Format
Credential 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 credential 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 credential 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, has to be written as user%40example.com
.
Optionally, the credential 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:
- The
--insecure
command-line option:
teamscale-dev pre-commit --insecure ...
- The
--server
command-line option with#trust-all-certificates
suffix:
teamscale-dev pre-commit --server https://username:accesskey@example.com/teamscale/#trust-all-certificates ...
- 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:
--branch
command-line optionproject.branch
property in your configuration file (.teamscale.toml
)- Branch checked out from version control
- 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
andwarning
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.