--- url: /reference/cli/teamscale-dev.md --- # 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](../../../howto/integrating-with-your-ide/other-ides/) for which no dedicated IDE plug-in exists. \[\[toc]] ## Installation You can install the `teamscale-dev` command-line client for [Linux](#linux), [Windows](#windows), and [macOS](#macos). ### Linux 1. Download the installation archive for your architecture: :::: tabs key:teamscale-dev-download-linux \== Self-contained (x86) \== Architecture-independent (requires JRE) :::info Java Runtime Environment (JRE) Requirements Starting with version 2024.9, the architecture-independent download requires a JRE running Java 21 or later. Earlier versions require Java 17 or later. (See the [System Requirements](../../system-requirements/#system-requirements-for-ide-plugins)) ::: :::: *Nightly builds are unreleased builds toward the next version and may be unstable.* 2. Extract the archive to `/opt` and link the executable to `/usr/local/bin`: ```bash sudo unzip teamscale-dev*.zip -d /opt/ sudo ln -s /opt/teamscale-dev/bin/teamscale-dev /usr/local/bin/ ``` #### Shell auto-completion {#linux-completion} Optionally, add the following line to your `~/.bashrc` or `~/.zshrc` to enable shell auto-completion via the [`generate-completion`](#the-generate-completion-command) command: ```shell source <( teamscale-dev generate-completion ) ``` ### Windows 1. Download the installation archive for your architecture: :::: tabs key:teamscale-dev-download-windows \== Self-contained (x86) \== Architecture-independent (requires JRE) :::info Java Runtime Environment (JRE) Requirements Starting with version 2024.9, the architecture-independent download requires a JRE running Java 21 or later. Earlier versions require Java 17 or later. (See the [System Requirements](../../system-requirements/#system-requirements-for-ide-plugins)) ::: :::: *Nightly builds are unreleased builds toward the next version and may be unstable.* 2. Extract the archive to `C:\Program Files` 3. Add `C:\Program Files\teamscale-dev\bin` to your `PATH` via *Control Panel > Advanced System Settings > Environment Variables > System Variables*. You can then run the client as `teamscale-dev.bat`. In Command Prompt and PowerShell, you may omit the `.bat` extension. In [Git Bash](https://git-scm.com/install/windows), you must include it. ### macOS On macOS, we recommend to [install via Homebrew](#macos-homebrew). Alternatively, you can [install manually](#macos-manual) from a downloaded installation archive. #### Homebrew (preferred) {#macos-homebrew} To install via the [Homebrew](https://brew.sh/) package manager from our [custom tap](https://homebrew.teamscale.com/), execute the following commands: ```bash brew tap cqse/teamscale https://homebrew.teamscale.com/ brew install teamscale-dev ``` #### Manual install {#macos-manual} 1. Download the installation archive for your architecture: :::: tabs key:teamscale-dev-download-macos \== Self-contained (ARM) \== Self-contained (x86) \== Architecture-independent (requires JRE) :::info Java Runtime Environment (JRE) Requirements Starting with version 2024.9, the architecture-independent download requires a JRE running Java 21 or later. Earlier versions require Java 17 or later. (See the [System Requirements](../../system-requirements/#system-requirements-for-ide-plugins)) ::: :::: *Nightly builds are unreleased builds toward the next version and may be unstable.* 2. Extract the archive to `/opt` and link the executable to `/usr/local/bin`: ```bash sudo unzip teamscale-dev*.zip -d /opt/ sudo ln -s /opt/teamscale-dev/bin/teamscale-dev /usr/local/bin/ ``` #### Shell auto-completion {#macos-completion} Optionally, add the following line to your `~/.zshrc` to enable shell auto-completion via the [`generate-completion`](#the-generate-completion-command) command: ```shell source <( teamscale-dev generate-completion ) ``` :::tip macOS Security Note that the startup of `teamscale-dev` may be blocked on macOS upon the first execution. To allow execution of the executable go to *System Settings > Privacy & Security* and check the *Security* section for an application that was blocked from running. ::: ## 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. :::: tabs key:os \== Linux ```shell teamscale-dev --help ``` \== Windows ```batch teamscale-dev.bat --help ``` \== macOS ```shell teamscale-dev --help ``` :::: The various commands can be further configured by command-line options. Many options are [common](#common-options) 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](../../teamscale-toml/). ### 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](#finding-output-format). You can use this command in three ways: 1. **Automatic Upload 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. :::info 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. ::: :::: tabs key:os \== Linux ```shell teamscale-dev pre-commit src/Example.java ``` ```shell teamscale-dev pre-commit src/ ``` \== Windows ```batch teamscale-dev.bat pre-commit src\Example.java ``` ```batch teamscale-dev.bat pre-commit src\ ``` \== macOS ```shell teamscale-dev pre-commit src/Example.java ``` ```shell teamscale-dev pre-commit src/ ``` :::: :::warning 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](../../admin-settings/server-limits/#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 Upload of Only Uncommitted Files for Analysis:** If the given paths are under version control ([Git] and [Subversion] supported), and the `---upload-uncommitted-files` (or the deprecated `--only-uncommitted-changes`) option is used, only those files that have uncommitted changes will be uploaded. :::: tabs key:os \== Linux ```shell teamscale-dev pre-commit --upload-uncommitted-files src/ ``` \== Windows ```batch teamscale-dev.bat pre-commit --upload-uncommitted-files src\ ``` \== macOS ```shell teamscale-dev pre-commit --upload-uncommitted-files 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 Upload of Files for Analysis:** If the `--upload-all-files` (or the deprecated `--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. :::: tabs key:os \== Linux ```shell teamscale-dev pre-commit --upload-all-files src/Example.java ``` \== Windows ```batch teamscale-dev.bat pre-commit --upload-all-files src\Example.java ``` \== macOS ```shell teamscale-dev pre-commit --upload-all-files src/Example.java ``` :::: :::warning 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](../../admin-settings/server-limits/#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 `--upload-all-files` should hence be restricted to uploading single files. ::: If no paths are specified, the current working directory is used. Further options, e.g., `--show-links-to-findings` and `--findings-to-stderr` control how and where the findings are reported. :::info Server Credentials Required This command requires that you [supply server credentials](#supplying-server-credentials). ::: #### Cleaning the Pre-Commit Branch Uploads accumulate on the pre-commit branch. Files from earlier uploads stay there and keep producing findings. Pass `--clean` to empty the branch before the upload, so that it holds only the files uploaded by this command. :::: tabs key:os \== Linux ```shell teamscale-dev pre-commit --clean src/Example.java ``` \== Windows ```batch teamscale-dev.bat pre-commit --clean src\Example.java ``` \== macOS ```shell teamscale-dev pre-commit --clean src/Example.java ``` :::: :::warning Requires Teamscale Server 2026.2 or Newer `--clean` requires a Teamscale server of version 2026.2 or newer. ::: ### The `fetch-findings` Command The `fetch-findings` command fetches findings from Teamscale for one or more paths and displays them in a [common format](#finding-output-format). Unlike the [`pre-commit`](#the-pre-commit-command), `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: :::: tabs key:os \== Linux ```shell teamscale-dev fetch-findings src/Example.java src/Utils.java ``` \== Windows ```batch teamscale-dev.bat fetch-findings src\Example.java src\Utils.java ``` \== macOS ```shell teamscale-dev fetch-findings src/Example.java src/Utils.java ``` :::: 2. **Fetch findings for one or more directories:** For example: :::: tabs key:os \== Linux ```shell teamscale-dev fetch-findings src/main/java src/test/java ``` \== Windows ```batch teamscale-dev.bat fetch-findings src\main\java src\test\java ``` \== macOS ```shell 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. If no paths are specified, the current working directory is used. :::info Server Credentials Required This command requires that you [supply server credentials](#supplying-server-credentials). ::: ### The `fetch-impacted-tests` Command The `fetch-impacted-tests` command fetches from Teamscale the tests [impacted](../../../glossary/index.md#test-impact-analysis) by the last commit on the currently checked-out branch (i.e., the commit range `HEAD~1..HEAD`) and displays their [uniform paths](../../../glossary/index.md#uniform-path), one per line. The `PATH` argument must point to a checked-out project containing a [`.teamscale.toml` configuration file](../../teamscale-toml/); it is used only to determine which Teamscale project and branch the request applies to. The impacted tests themselves are always computed for the entire last commit on that branch. For example: :::: tabs key:os \== Linux ```shell teamscale-dev fetch-impacted-tests src/ ``` \== Windows ```batch teamscale-dev.bat fetch-impacted-tests src\ ``` \== macOS ```shell teamscale-dev fetch-impacted-tests src/ ``` :::: If no path is specified, the current working directory is used. #### Selecting the Impact Strategy By default, Teamscale determines the impacted tests automatically based on what is available on the server: [Testwise Coverage](../../../glossary/index.md#testwise-coverage) if any coverage partitions are available, source-code similarity otherwise. You can override this default by passing `--strategy` explicitly: :::: tabs key:os \== Linux ```shell teamscale-dev fetch-impacted-tests --strategy SIMILARITY src/ ``` \== Windows ```batch teamscale-dev.bat fetch-impacted-tests --strategy SIMILARITY src\ ``` \== macOS ```shell teamscale-dev fetch-impacted-tests --strategy SIMILARITY src/ ``` :::: The supported strategies are: * `AUTO` (default): Uses `COVERAGE` if any [testwise coverage partitions](../../../glossary/index.md#partition) are available on the Teamscale server; falls back to `SIMILARITY` otherwise. * `COVERAGE`: Selects tests based on which production code they cover, using [Testwise Coverage](../../../glossary/index.md#testwise-coverage) recorded by a [coverage profiler](../../coverage-profilers/). * `SIMILARITY` : Selects tests based on source-code similarity between the changed production code and the test code. #### Restricting the Coverage Partitions When the applied strategy is `COVERAGE` (i.e., explicitly `--strategy COVERAGE`, or `AUTO` resolving to `COVERAGE`), you can restrict the [partitions](../../../glossary/index.md#partition) from which testwise coverage is considered using the `--only-partition` option. For example, to only consider coverage from the partitions `Unit Tests` and `Integration Tests`: :::: tabs key:os \== Linux ```shell teamscale-dev fetch-impacted-tests --only-partition "Unit Tests" --only-partition "Integration Tests" src/ ``` \== Windows ```batch teamscale-dev.bat fetch-impacted-tests --only-partition "Unit Tests" --only-partition "Integration Tests" src\ ``` \== macOS ```shell teamscale-dev fetch-impacted-tests --only-partition "Unit Tests" --only-partition "Integration Tests" src/ ``` :::: The option may be given multiple times or, equivalently, once with a comma-separated list of partition names. If `--only-partition` is omitted, all partitions available on the server are considered. The option is silently ignored when `--strategy SIMILARITY` is used. #### Limiting the Number of Results Use the `-n` (or `--max-count`) option to display only the `N` most relevant impacted tests. For example, to display only the top 10 most-impacted tests: :::: tabs key:os \== Linux ```shell teamscale-dev fetch-impacted-tests -n 10 src/ ``` \== Windows ```batch teamscale-dev.bat fetch-impacted-tests -n 10 src\ ``` \== macOS ```shell teamscale-dev fetch-impacted-tests -n 10 src/ ``` :::: #### Pre-Commit Branches If the last commit you want to analyze has been uploaded to the corresponding pre-commit branch (e.g., as a result of an earlier [`pre-commit`](#the-pre-commit-command) upload) instead of the currently checked-out branch itself, use `--on-pre-commit-branch`: :::: tabs key:os \== Linux ```shell teamscale-dev fetch-impacted-tests --on-pre-commit-branch src/ ``` \== Windows ```batch teamscale-dev.bat fetch-impacted-tests --on-pre-commit-branch src\ ``` \== macOS ```shell teamscale-dev fetch-impacted-tests --on-pre-commit-branch src/ ``` :::: The corresponding pre-commit branch is derived from the currently checked-out branch and your username. :::info Server Credentials Required This command requires that you [supply server credentials](#supplying-server-credentials). ::: ### The `open-in-browser` Command The `open-in-browser` (or `browse`) command opens the [*Metrics*](../../ui/metrics/) > *Files* view in a Web browser, showing the given files and directories as they are known to Teamscale. For example: :::: tabs key:os \== Linux ```shell teamscale-dev open-in-browser src/Example.java ``` ```shell teamscale-dev open-in-browser src/ ``` \== Windows ```batch teamscale-dev.bat open-in-browser src\Example.java ``` ```batch teamscale-dev.bat open-in-browser src\ ``` \== macOS ```shell teamscale-dev open-in-browser src/Example.java ``` ```shell teamscale-dev open-in-browser src/ ``` :::: If no paths are specified, the current working directory is used. The Web browser used by `teamscale-dev` is your desktop's default browser. Consult your operating system's documentation for how to change this. :::info Server Credentials Required This command requires that you [supply server credentials](#supplying-server-credentials) to look up the username associated with a server URL. ::: ### The `verify-configuration` Command The `verify-configuration` (or `verify-config`) command validates the [`.teamscale.toml` IDE configuration files](../../teamscale-toml/) for a given directory. It checks whether the configuration is well-formed and whether the configured Teamscale server and project can be successfully accessed. This is useful for troubleshooting configuration issues before attempting to use other commands. For example: :::: tabs key:os \== Linux ```shell teamscale-dev verify-configuration src/ ``` \== Windows ```batch teamscale-dev.bat verify-configuration src\ ``` \== macOS ```shell teamscale-dev verify-configuration src/ ``` :::: If no directory is specified, the current working directory is used. You can use the `--quiet` option to suppress the success message and only display errors and warnings. :::info Server Credentials Required This command requires that you [supply server credentials](#supplying-server-credentials) to verify that the configured Teamscale server and project are accessible. ::: ### The `generate-completion` Command The `generate-completion` command outputs a script that configures the [programmable completion](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion) of the [bash](https://www.gnu.org/software/bash) and [zsh](https://www.zsh.org/) Unix shells to recognize `teamscale-dev` and offer tab-completion for it. ```shell 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. ### The `mcp` Command The `mcp` command runs `teamscale-dev` as a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server, exposing a subset of `teamscale-dev`'s functionality as MCP tools. This allows MCP-aware clients (e.g., AI coding assistants) to invoke Teamscale operations directly. Communication with the MCP client happens over the [stdio transport](https://modelcontextprotocol.io/specification/draft/basic/transports#stdio), so this command is intended to be launched by an MCP client rather than invoked directly from a shell. :::: tabs key:os \== Linux ```shell teamscale-dev mcp ``` \== Windows ```batch teamscale-dev.bat mcp ``` \== macOS ```shell teamscale-dev mcp ``` :::: The following MCP tools are offered to the connected client: * `teamscale-dev_pre-commit` : Uploads files to Teamscale to perform a static analysis for quality and security issues and returns the findings. Corresponds to the [`pre-commit`](#the-pre-commit-command) command. * `teamscale-dev_fetch-impacted-tests` : Asks the Teamscale server which tests are impacted by the last commit on the currently checked-out branch and returns their names. Corresponds to the [`fetch-impacted-tests`](#the-fetch-impacted-tests-command) command. * `teamscale-dev_open-in-browser` : Opens a file or directory on the Teamscale server in a Web browser. Corresponds to the [`open-in-browser`](#the-open-in-browser-command) command. The exact input schema of each tool is advertised by the server itself; consult your MCP client to inspect it. :::info Server Credentials Required The tools exposed by this command connect to a Teamscale server and hence require that you [supply server credentials](#supplying-server-credentials). As the `mcp` command is launched by an MCP client rather than invoked directly from a shell, credentials are typically supplied either via the [`TEAMSCALE_DEV_USER` and `TEAMSCALE_DEV_ACCESSKEY`](#the-teamscale-dev-user-and-teamscale-dev-accesskey-environment-variables) or [`TEAMSCALE_DEV_SERVERS`](#the-teamscale-dev-servers-environment-variable) environment variables, or by passing the corresponding command-line options (e.g., via [an args file](#supplying-command-line-options-via-an-args-file)) in the client's MCP server configuration. ::: ## 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: :::: tabs key:os \== Linux ```shell teamscale-dev pre-commit --help ``` \== Windows ```batch teamscale-dev.bat pre-commit --help ``` \== macOS ```shell teamscale-dev pre-commit --help ``` :::: ### Supplying Server Credentials Some commands like [`pre-commit`](#the-pre-commit-command), [`fetch-findings`](#the-fetch-findings-command) or [`open-in-browser`](#the-open-in-browser-command) require you to supply your credentials for a Teamscale server, i.e., your *username* and [*access key*](../../../glossary/index.md#access-key). You can pass these credentials to the commands in five ways: 1. [The `--user` and `--accesskey` Command-Line Options](#the-user-and-accesskey-command-line-options) 2. [The `--server` Command-Line Option](#the-server-command-line-option) 3. [The `TEAMSCALE_DEV_USER` and `TEAMSCALE_DEV_ACCESSKEY` Environment Variables](#the-teamscale-dev-user-and-teamscale-dev-accesskey-environment-variables) 4. [The `TEAMSCALE_DEV_SERVERS` Environment Variable](#the-teamscale-dev-servers-environment-variable) 5. [Supplying Command-Line Options via an Args File](#supplying-command-line-options-via-an-args-file) :::danger Accidentally Exposing the Access Key in Multi-User Environments Passing the [`--accesskey`](#the-user-and-accesskey-command-line-options) or [`--server`](#the-server-command-line-option) 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 is **highly recommended** to either set [the `TEAMSCALE_DEV_USER` and `TEAMSCALE_DEV_ACCESSKEY` environment variables](#the-teamscale-dev-user-and-teamscale-dev-accesskey-environment-variables), set [the `TEAMSCALE_DEV_SERVERS` environment variable](#the-teamscale-dev-servers-environment-variable), or [supply command-line options via an args file](#supplying-command-line-options-via-an-args-file). ::: #### The `--user` and `--accesskey` Command-Line Options :::: tabs key:os \== Linux ```shell teamscale-dev pre-commit --user username --accesskey accesskey ... ``` \== Windows ```batch teamscale-dev.bat pre-commit --user username --accesskey accesskey ... ``` \== macOS ```shell 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`)](../../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 :::: tabs key:os \== Linux ```shell teamscale-dev pre-commit --server https://username:accesskey@example.com/teamscale/ ... ``` \== Windows ```batch teamscale-dev.bat pre-commit --server https://username:accesskey@example.com/teamscale/ ... ``` \== macOS ```shell 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](#credentials-url-format). 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](#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). :::: tabs key:os \== Linux ```shell export TEAMSCALE_DEV_USER="username" export TEAMSCALE_DEV_ACCESSKEY="accesskey" ``` \== macOS ```shell 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 ::::tip 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](#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). :::: tabs key:os \== Linux ```shell export TEAMSCALE_DEV_SERVERS="https://username:accesskey@example.com/teamscale/" ``` \== macOS ```shell 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//.teamscale-dev.args` on Linux, `C:\\Users\` on Windows, `/Users//.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: :::: tabs key:os \== Linux ```shell teamscale-dev pre-commit @"${HOME}/.teamscale-dev.args" ... ``` \== Windows ```batch teamscale-dev.bat pre-commit @%HOMEPATH%\.teamscale-dev.args ... ``` \== macOS ```shell 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 option](#the-server-command-line-option) takes precedence over [the `TEAMSCALE_DEV_SERVERS` environment variable](#the-teamscale-dev-servers-environment-variable). If no credentials are associated with a particular server URL, [the `--user` and `--accesskey` command-line options](#the-user-and-accesskey-command-line-options) apply and take precedence over [the `TEAMSCALE_DEV_USER` and `TEAMSCALE_DEV_ACCESSKEY` environment variables](#the-teamscale-dev-user-and-teamscale-dev-accesskey-environment-variables). Any [command-line options supplied via an args file](#supplying-command-line-options-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`)](../../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. :::warning Special Characters in Username and Access Key Certain characters cannot be used verbatim in credentials URLs; they need to be [percent-escaped](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding). 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](#disabling-tls-certificate-validation) for the server in question. ### Disabling TLS Certificate Validation :::danger 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`](#the-pre-commit-command) and [`fetch-findings`](#the-fetch-findings-command) 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:** :::: tabs key:os \== Linux ```shell teamscale-dev pre-commit --insecure ... ``` \== Windows ```batch teamscale-dev.bat pre-commit --insecure ... ``` \== macOS ```shell teamscale-dev pre-commit --insecure ... ``` :::: 2\. **The `--server` command-line option with `#trust-all-certificates` suffix:** :::: tabs key:os \== Linux ```shell teamscale-dev pre-commit --server https://username:accesskey@example.com/teamscale/#trust-all-certificates ... ``` \== Windows ```batch teamscale-dev.bat pre-commit --server https://username:accesskey@example.com/teamscale/#trust-all-certificates ... ``` \== macOS ```shell 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:** :::: tabs key:os \== Linux ```shell export TEAMSCALE_DEV_SERVERS="https://username:accesskey@example.com/teamscale/#trust-all-certificates" teamscale-dev pre-commit ... ``` \== Windows ```batch setx TEAMSCALE_DEV_SERVERS "https://username:accesskey@example.com/teamscale/#trust-all-certificates" teamscale-dev.bat pre-commit ... ``` \== macOS ```shell export TEAMSCALE_DEV_SERVERS="https://username:accesskey@example.com/teamscale/#trust-all-certificates" teamscale-dev pre-commit ... ``` :::: ### Overriding Server, Project and Branch Information Some commands like [`pre-commit`](#the-pre-commit-command), [`fetch-findings`](#the-fetch-findings-command), and [`open-in-browser`](#the-open-in-browser-command) need to know which Teamscale server to contact, and which project and branch on it your files belong to. All three are normally taken from your [configuration file (`.teamscale.toml`)](../../teamscale-toml/), but each can be overridden on the command line, by an option named after the property whose value it replaces. This is useful for temporarily pointing `teamscale-dev` at a second Teamscale server, for example while your team is migrating to a new one, or at a project analyzing the same code with a different [analysis profile](../../../glossary/index.md#analysis-profile), without having to edit your configuration file and undo that edit afterwards. The **server URL** is determined, in order of precedence, from these two sources: 1. `--override-server-url URL` command-line option 2. [`server.url`](../../teamscale-toml/#server-url) property in your configuration file The **project ID** is determined, in order of precedence, from these two sources: 1. `--override-project-id PROJECT_ID` command-line option 2. [`project.id`](../../teamscale-toml/#project-id) property in your configuration file The **branch** is determined, in order of precedence, from these four sources: 1. `--override-project-branch BRANCH` command-line option Versions prior to 2026.7 used the spelling `-b`/`--branch`, which is still accepted. 2. [`project.branch`](../../teamscale-toml/#project-branch) property in your configuration file 3. Branch checked out from the version-control system, if it is a supported one ([Git], [Subversion]) 4. Default branch of the respective Teamscale server Three limitations apply: * The overrides replace values in an otherwise valid configuration file; they cannot stand in for a missing or incomplete one. A `.teamscale.toml` is still required, as it is what anchors the local directory from which a file's [uniform path](../../../glossary/index.md#uniform-path) is computed. * `--override-server-url` must not include credentials, and does not supply them either. Pointing at a different server therefore usually means [supplying its credentials](#supplying-server-credentials) via environment variables or command-line options. * `--override-project-id` does not change a file's uniform path, which is still derived from the [`project.path`](../../teamscale-toml/#project-path) property. The given project must therefore analyze your files under the same uniform path as the configured one. To check that a command's overrides resolve as you expect before relying on them, pass the same options to [`verify-configuration`](#the-verify-configuration-command). ### Finding Output Format Commands that report findings (e.g., [`pre-commit`](#the-pre-commit-command) or [`fetch-findings`](#the-fetch-findings-command)) do so in the [GCC diagnostics format](https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html): ``` 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](../../ui/findings/#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: :::: tabs key:os \== Linux ```shell teamscale-dev --debug # --debug ALL ``` ```shell teamscale-dev --debug FINDINGS,SERVERS # --debug FINDINGS --debug SERVERS ``` \== Windows ```batch teamscale-dev.bat --debug & :: --debug ALL ``` ```batch teamscale-dev.bat --debug FINDINGS,SERVERS & :: --debug FINDINGS --debug SERVERS ``` \== macOS ```shell teamscale-dev --debug # --debug ALL ``` ```shell 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](https://www.apache.org/licenses/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. [Git]: https://git-scm.com/ [Subversion]: https://subversion.apache.org/