📣
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

Get Started with TiDB Cloud CLI

TiDB Cloud CLI (ti) is a command-line tool for managing TiDB Cloud Starter instances and file systems in TiDB Cloud Filesystem. It supports both interactive use and automation, with JSON as the default output format for commands.

This guide walks you through installing and configuring TiDB Cloud CLI (ti), and then completing a basic workflow with TiDB Cloud Starter or TiDB Cloud Filesystem. For an overview of the CLI, its capabilities, and supported workflows, see TiDB Cloud Command Line Interface Overview.

Prerequisites

Before you begin, obtain a TiDB Cloud API public key and private key from the TiDB Cloud API Keys page in the TiDB Cloud console. The keys must have the Organization Owner access to your organization.

Step 1. Install TiDB Cloud CLI

Depending on your operating system, take the following steps to install TiDB Cloud CLI.

    1. On macOS or Linux, run the following command to install 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. Add export PATH="$HOME/.ti/bin:$PATH" to your shell profile to keep ti available in new terminals.

      For example, if you use zsh, run the following command:

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

    1. On Windows PowerShell, run the following command to install 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")

    Step 2. Configure TiDB Cloud CLI

    1. Run the interactive configuration:

      ti configure

    2. Provide the following information:

      • A default region for CLI operations, specified as a region code (such as aws-us-west-2). For a list of regions that are supported by TiDB Cloud CLI, see Supported regions.
      • Your TiDB Cloud API public key and private key.

    3. Run a read-only command to verify that the CLI can access TiDB Cloud using the saved credentials:

      ti fs list-file-systems

      Example output:

      {
  "region_code": "aws-us-west-2",
  "file_systems": []
}

    Step 3. Choose a workflow

    Proceed with either of the following workflows based on your needs:

    Option A: TiDB Cloud Filesystem

    TiDB Cloud Filesystem is a persistent, shareable cloud file system that you can use across local machines, CI jobs, sandboxes, and other ephemeral environments.

    The following example shows how you can create a file system in one environment and access it from the same or another environment. For example, you can access it from an AI agent sandbox (a temporary environment that might be discarded after a task).

    1. On your local machine or another environment with your TiDB Cloud API credentials configured, create a file system and obtain its owner token:

      export TI_FS_TOKEN="$(ti fs create-file-system --display-name agent-workspace --wait --query fs_token --output text --region aws-us-west-2)"

    2. In the environment where you want to use the file system, set the owner token from the previous step as TI_FS_TOKEN, and then mount the file system to a local path as follows. This environment can be the same machine where you created the file system, another machine, or an AI agent sandbox.

      # export TI_FS_TOKEN="<owner-token>" # If you are continuing on a different environment as step 1, pass in the TI_FS_TOKEN you get from step 1 here.
mkdir ~/mnt-test
ti fs mount-file-system --mount-path ~/mnt-test --region aws-us-west-2
echo 'Hello from TiDB Cloud Filesystem' >> ~/mnt-test/hello.txt
ls -l ~/mnt-test/hello.txt

      After mounting, you can work with the files using standard local file operations.

    3. After you finish using the mounted file system in that environment, unmount it:

      ti fs unmount-file-system --mount-path ~/mnt-test --region aws-us-west-2

      Unmounting removes the local mount, but the files remain in TiDB Cloud Filesystem and can be accessed again from the same or another environment.

    Option B: TiDB Cloud Starter

    1. Create a TiDB Cloud Starter instance and save its ID:

      export TI_DB_CLUSTER_ID="$(ti db create-db-cluster \
  --db-cluster-type starter \
  --db-cluster-name quickstart-db \
  --wait \
  --query id \
  --output text)"

    2. Create the SQL users and run a read-only query to verify the connection:

      ti db create-db-sql-users \
  --db-cluster-id "$TI_DB_CLUSTER_ID"

ti db execute-sql-statement \
  --db-cluster-id "$TI_DB_CLUSTER_ID" \
  --read-only \
  --sql "SELECT 1 AS ready" \
  --output text

      The ti db execute-sql-statement command executes the query through the HTTPS SQL API. The output includes ready = 1.

    3. Generate the connection string:

      export DATABASE_URL="$(ti db format-db-connection-string \
  --db-cluster-id "$TI_DB_CLUSTER_ID" \
  --read-write --query connection_string \
  --output text)"

    What's next

    Was this page helpful?