📣
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 TiDB Cloud Filesystems. 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.

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-east-1). 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 db list-db-clusters --db-cluster-type starter --output text

      Example output:

      {
  "profile": "default",
  "region_code": "aws-us-east-1",
  "credentials_stored": true
}

    Step 3. Choose a workflow

    Complete either of the following workflows.

    Option A: Create and use a Filesystem

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

    1. Create a Filesystem, wait until it is ready, and save its server-assigned ID:

      export TI_FS_FILE_SYSTEM_ID="$(ti fs create-file-system \
  --wait \
  --query file_system_id \
  --output text)"

      ti stores the Filesystem credential locally, so you do not need to provide it for subsequent file operations.

    2. Write a file to the Filesystem, and then read the file:

      printf 'hello from ti\n' | ti fs copy-file \
  --from-stdin \
  --to-remote /hello.txt

ti fs read-file \
  --path /hello.txt

      Expected output:

      hello from ti

    3. Delete the Filesystem:

      ti fs delete-file-system \
  --file-system-id "$TI_FS_FILE_SYSTEM_ID"
unset TI_FS_FILE_SYSTEM_ID

    Option B: Create a TiDB Cloud Starter instance and query the database

    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. Delete the TiDB Cloud Starter instance:

      ti db delete-db-cluster \
  --db-cluster-id "$TI_DB_CLUSTER_ID" \
  --wait
unset TI_DB_CLUSTER_ID

    What's next

    Was this page helpful?