# Command-Line Client for Teamscale (teamscale-cli
)
This article describes teamscale-cli
, the command-line client for Teamscale.
Among other things, this client can be used to integrate Teamscale with IDEs for which no dedicated IDE plug-in exists.
# Commands
The command-line client exposes its functionality as a set of commands.
You can use the built-in help option, --help
, to list all available commands.
teamscale-cli --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 the Teamscale server 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-cli pre-commit src/com/example/Example.java
teamscale-cli pre-commit src/
Automatically Uploading Only Uncommitted Changes for Analysis: If the files and directories are under version control by a supported system (Git (opens new window), Subversion (opens new window)), you can use the
--only-uncommitted-changes
option to restrict the upload to only those files that have uncommitted changes. For example:teamscale-cli pre-commit --only-uncommited-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-uncommited-changes
is used.)
Pre-Commit Upload Limits
The 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., --omit-links-to-findings
and --log-to-stder
control how and where the findings are reported.
# The open-in-browser
Command
The open-in-browser
(or browse
) command opens the Metrics > Files view in a Web browser, showing the given file or directory as it is known to Teamscale.
For example:
teamscale-cli open-in-browser src/com/example/Example.java
teamscale-cli open-in-browser src/
The Web browser used by teamscale-cli
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 (opens new window) of the bash (opens new window) and zsh (opens new window) Unix shells to recognize teamscale-cli
and offer tab-completion for it.
source <( teamscale-cli generate-completion )
To permanently install tab-completion support for teamscale-cli
, you can either place the above line in your shell's profile (e.g., ~/.bash_profile
) or save the output of teamscale-cli 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-cli
.
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-cli pre-commit --help
# Supplying Server Credentials
Some commands like pre-commit
or open-in-browser
require you to supply your credentials for the Teamscale server, i.e., your username and IDE access key.
You can pass these credentials to the command in several ways:
The
--servers
command-line option:teamscale-cli pre-commit --server https://username:accesskey@example.com/teamscale/ ...
(You can use the
--servers
option multiple times to supply credentials for multiple servers.)The
TEAMSCALE_CLI_SERVERS
environment variable:export TEAMSCALE_CLI_SERVERS="https://username:accesskey@example.com/teamscale/" teamscale-cli pre-commit ...
(You can specify multiple URLs, separated by spaces, to supply credentials for multiple servers.)
Both 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_CLI_SERVERS
variable.
In all cases, credentials for a Teamscale server are given as a credential URL.
If the Teamscale server 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 IDE access key, respectively.
Special Characters in Username and IDE Access Key
Certain characters cannot be used verbatim; they need to be percent-escaped (opens new window).
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
.
Accidentally Exposing the IDE Access Key in Multi-User Environments
Using the --server
option on the command line 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).
To prevent this, place the --server
option in an argument file (e.g., .teamscale-cli.args
) not readable by other users:
--server https://username:accesskey@example.com/teamscale/
Then, include the options from the argument file using the @
-notation:
teamscale-cli pre-commit @.teamscale-cli.args ...
# Overriding Branch Information
Some commands like pre-commit
or 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 (opens new window), Subversion (opens new window)).
If your version-control system is unsupported by teamscale-cli
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 Teamscale server
# 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-cli
.
Optionally, you can refine which information is logged by specifying one or more categories. For example:
teamscale-cli --debug # --debug ALL
teamscale-cli --debug FINDINGS,SERVERS # --debug FINDINGS --debug SERVERS
You can look up the exact list of supported categories using the --help
option.
# Finding Output Format
Commands that report findings (e.g., pre-commit
) do so in the GCC diagnostics format (opens new window):
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.