📣
TiDB Cloud Premium is now in public preview. Unlimited growth, instant elasticity, advanced security for enterprise workloads. Try it out →
​
Sign InStart for Free
AI
Developer
Best Practices
API
​
Sign InStart for Free

Install, Configure, and Update TiDB Cloud CLI

Use this guide to install and configure TiDB Cloud CLI (ti), check for and apply updates, and uninstall the CLI when needed.

Prerequisites

To configure TiDB Cloud CLI, obtain a TiDB Cloud API public key and private key from the TiDB Cloud API Keys page in the TiDB Cloud console first.

Install TiDB Cloud CLI

Depending on your operating system, follow the steps below to install the TiDB Cloud CLI.

    1. On macOS or Linux, run the following command to install the TiDB Cloud CLI:

      curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh -s -- --yes

    2. Add ti to the current shell and verify it:

      export PATH="$HOME/.ti/bin:$PATH"
ti --version

    3. To keep ti available in new terminal sessions, add it to your shell profile. For example, if you use zsh, run the following commands:

      echo 'export PATH="$HOME/.ti/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

      If you use Bash, add the same export command to the startup file used by your terminal, commonly ~/.bashrc on Linux or ~/.bash_profile on macOS.

    1. On Windows PowerShell, run the following command to install the TiDB Cloud CLI:

      $script = "$env:TEMP\install-ti.ps1"
iwr https://github.com/tidbcloud/ti-cli/releases/latest/download/install.ps1 -OutFile $script
powershell -ExecutionPolicy Bypass -File $script -Yes

    2. Add ti to the current PowerShell session and verify it:

      $env:Path = "$HOME\.ti\bin;$env:Path"
ti --version

    3. Add $HOME\.ti\bin to your user PATH to keep ti available in new PowerShell sessions:

      $tiBin = "$HOME\.ti\bin"
[Environment]::SetEnvironmentVariable("Path", "$tiBin;$([Environment]::GetEnvironmentVariable('Path', 'User'))", "User")

    The installer writes to your home directory and does not require elevated privileges.

    The installer also displays a notice about anonymous usage telemetry and how to opt out. Installation does not require you to make a telemetry choice. For details, see Anonymous telemetry.

    Configure a profile

    A profile is a named set of TiDB Cloud API public key, private key, and region code.

    This section describes how to configure a profile for the TiDB Cloud CLI.

    Configure interactively

    By default, ti configure prompts you for the information required to configure a profile:

    ti configure

    ti configure prompts you for your TiDB Cloud API public key and private key, and a default region code. The CLI uses this region for commands unless you override it for an individual command. For available regions, see Supported regions.

    The command validates the input format locally and saves the profile without making a request to TiDB Cloud. Your credentials are verified when you run a command that accesses TiDB Cloud. To change the default profile, run ti configure again. To change a named profile, include its name, for example, ti configure --profile staging.

    Configure a named profile

    Pass --profile to configure a named profile:

    ti configure --profile staging

    Configure for automation

    For CI or another non-interactive environment, prefer environment variables:

    TIDB_CLOUD_PUBLIC_KEY="<public-key>" \
TIDB_CLOUD_PRIVATE_KEY="<private-key>" \
TI_REGION_CODE="aws-us-east-1" \
ti configure --profile ci --non-interactive

    You can also provide --tidb-cloud-public-key, --tidb-cloud-private-key, and --region-code, but secret flags can remain in shell history or process listings.

    Select a profile and override its region

    To use a named profile and override its default region for one command, use the global --profile and --region options:

    ti --profile staging --region aws-us-west-2 db list-db-clusters --db-cluster-type starter

    For detailed profile, credential, and region precedence rules, see TiDB Cloud CLI Configuration and Credentials.

    Get help and check the version

    Use help or --help to inspect commands and --version to check the installed version:

    ti help
ti fs help
ti --version

    For command groups and CLI conventions, see TiDB Cloud CLI Command Reference.

    Update TiDB Cloud CLI

    Check without changing files:

    ti update --check

    In automation, return exit code 1 when a newer version is available:

    ti update --check --fail-if-update-available

    Preview an update:

    ti update --dry-run

    Apply the latest update:

    ti update

    Install a specific release:

    ti update --target-version <version>

    The update command replaces both ti and ti-drive9 in a user-owned installation. It does not modify installations in protected or package-manager-owned locations. To migrate an older /usr/local/bin installation to ~/.ti/bin, run the installer once.

    Migrate from tdc v0.1.x

    If you have never used tdc v0.1.x, skip this section.

    If you previously used tdc v0.1.x, ti can migrate supported local profiles, credentials, preferences, and Filesystem state from ~/.tdc/ to ~/.ti/. Before installing ti, unmount any Filesystem or Vault mounts started by tdc.

    For the complete migration procedure, including migrated and excluded state, directory conflict resolution, and legacy environment variable compatibility, see Migrate from tdc to TiDB Cloud CLI.

    Uninstall TiDB Cloud CLI

    Before uninstalling, stop writers and unmount any active Filesystem or Vault mounts.

    For example, run the command that corresponds to the type of mount:

    # Filesystem mount
ti fs unmount-file-system --mount-path <filesystem-mount-path>

# Vault mount
ti fs-vault unmount-vault --mount-path <vault-mount-path>

    For details, see Mount a TiDB Cloud Filesystem and Manage Filesystem Vault Secrets.

      1. Remove the binaries:

        rm -f "$HOME/.ti/bin/ti" "$HOME/.ti/bin/ti-drive9"

      2. Remove the ~/.ti/bin entry that you added to your shell profile during installation.

      1. Remove the binaries:

        Remove-Item "$HOME\.ti\bin\ti.exe", "$HOME\.ti\bin\ti-drive9.exe"

      2. Remove $HOME\.ti\bin from your user PATH:

        $tiBin = "$HOME\.ti\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = (($userPath -split ";") | Where-Object { $_ -and $_ -ne $tiBin }) -join ";"
[Environment]::SetEnvironmentVariable("Path", $newPath, "User")

      Remove local state

      Removing binaries preserves profiles, credentials, Filesystem registrations, DB SQL credentials, logs, and mount locators.

        On macOS or Linux:

        rm -rf "$HOME/.ti"

        On Windows PowerShell:

        Remove-Item "$HOME\.ti" -Recurse -Force

        See also

        Was this page helpful?