Skip to main content
Version: 2.4

Install and connect

This guide installs tsm and connects it to your tSM environment. It takes about 5 minutes.

You need the URL of your tSM environment and your account there. You can download the CLI from the environment itself, without a GitLab account, or from GitLab with an access token.

1. Install the CLI​

From your environment (no GitLab token)​

The environment serves the installers and the CLI of its own release. This needs an environment running a tSM release that includes the CLI distribution; releases up to 2.4.15 do not, and there you install from GitLab (see below). In the tSM GUI open your user detail, tab API Keys, and click Connect CLI: the dialog shows both commands with the address of your environment filled in. You can also type them yourself and replace <environment> with the URL, for example https://tsm-dev.k8s.datalite.cz.

Linux and macOS (Apple silicon, when the environment offers it):

curl -fsSL https://<environment>/cli/install.sh | TSM_URL=https://<environment> sh && export PATH="$HOME/.local/bin:$PATH"

Windows (PowerShell):

$env:TSM_URL = 'https://<environment>'; & ([scriptblock]::Create((irm "$env:TSM_URL/cli/install.ps1"))); $env:Path = "$env:LOCALAPPDATA\tsm\bin;$env:Path"

The installer verifies the SHA-256 checksum, installs tsm into ~/.local/bin (Windows: %LOCALAPPDATA%\tsm\bin) and adds that folder to the PATH of the current terminal. Add it to your shell profile or user PATH (Windows: the PATH command in the GitLab route below) to keep tsm in new terminals. Then continue with 2. Connect to your environment.

From GitLab​

This route needs a GitLab access token with the read_api scope (in GitLab: avatar → Edit profile → Access tokens).

Windows​

Run in PowerShell:

$env:TSM_UPGRADE_TOKEN = '<your GitLab token>'
$installer = Invoke-RestMethod -Headers @{ 'PRIVATE-TOKEN' = $env:TSM_UPGRADE_TOKEN } 'https://gitlab.datalite.cz/api/v4/projects/tsm%2Ftsm-config/repository/files/tsm-cli%2Finstall.ps1/raw'
& ([scriptblock]::Create($installer))

The installer puts tsm.exe into %LOCALAPPDATA%\tsm\bin. Add that folder to your PATH once:

$bin = "$env:LOCALAPPDATA\tsm\bin"
[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', 'User') + ";$bin", 'User')

Open a new terminal and check the installation:

tsm --version

Linux​

export TSM_UPGRADE_TOKEN='<your GitLab token>'
curl -fsSL -H "PRIVATE-TOKEN: $TSM_UPGRADE_TOKEN" 'https://gitlab.datalite.cz/api/v4/projects/tsm%2Ftsm-config/repository/files/tsm-cli%2Finstall.sh/raw' | sh
tsm --version

The installer puts tsm into ~/.local/bin. If tsm is not found, add that folder to PATH in your shell profile.

macOS​

The GitLab releases may not contain a macOS binary. Install from your environment (above), ask the tSM team for one, or build it from tsm-config.

2. Connect to your environment​

With a one-time code​

The Connect CLI dialog of your environment also shows a one-time code (valid 5 minutes by default; Issue a new code gives another). It needs the same kind of environment as the installation above (a release with the CLI distribution; not available up to 2.4.15). Run:

tsm cli setup https://<environment> <code>

The command checks that the CLI is new enough for the environment, registers the environment and a context named after the installation (for example datalite-dev), lets the environment issue an API key for your user, stores it in the operating system's credential store and makes the context your default. The key is listed on the API Keys tab as tsm-cli <computer>@<context> <date> and can be revoked there. With your own API key use tsm cli setup https://<environment> --api-key-stdin instead of the code. Then continue with 3. Check the connection.

Step by step​

For a configuration Git checkout, use the shorter quick start with tsm context create. The explicit steps below are also supported.

Log in to tSM in the browser and create an API key on your user detail, tab API Keys. Then run the following commands. Replace the URL with your environment; the names tsm, dev and personal are your own labels and you can choose different ones.

tsm cli config project add tsm
tsm cli config environment add dev --project tsm --endpoint https://tsm-dev.k8s.datalite.cz
tsm context create dev --project tsm --env dev --account personal --no-login --non-interactive --use none
tsm context use dev --global
tsm auth login --method api-key

The last command asks for the API key. To log in with a username and password instead, use tsm auth login --method basic --user <username>.

What the commands did:

  • registered the project tsm and its environment dev with the URL,
  • created the context dev (environment + account + tenant default) and made it your default,
  • saved the API key as account personal. The key is stored in the operating system's credential store (Windows Credential Manager, macOS Keychain, Linux Secret Service via secret-tool), not in a plain file.

3. Check the connection​

tsm auth whoami
tsm app entity types

auth whoami shows who you are logged in as. app entity types lists the entity types of the application; an empty list is fine on a new tenant.

If a command fails, tsm doctor checks the configuration, the connection and the login step by step.

You are ready. Continue with Concepts, or go straight to the guide for your task.

Good to know​

  • Update the CLI: tsm cli upgrade downloads the release from the environment of the active context, or from GitLab when TSM_UPGRADE_TOKEN is set. tsm cli upgrade --check only checks for a newer version.
  • Configuration file: ~/.config/tsm/config.yaml (on Windows %USERPROFILE%\.config\tsm\config.yaml). It contains no passwords or keys. See Configuration.
  • Log out: tsm auth logout deletes the saved key from this computer. It does not revoke the API key in tSM.
  • Manual download: binaries are also on the CLI releases page. The installers check the SHA-256 checksum automatically; when downloading manually, compare the file hash with the .sha256 file next to it.