From 706cfebe66fd771cc56079c163a6a5a63eadb56d Mon Sep 17 00:00:00 2001 From: Guanglei Bao Date: Tue, 22 Sep 2026 23:45:44 +0800 Subject: [PATCH 01/10] refine ti-cli quick start --- ai/ti/ti-quick-start.md | 66 ++++++++++++++++------------------------- 1 file changed, 26 insertions(+), 40 deletions(-) diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md index 4a3317d4fb559..c202e759b4b84 100644 --- a/ai/ti/ti-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -1,11 +1,11 @@ --- title: Get Started with TiDB Cloud CLI -summary: Install and configure TiDB Cloud CLI, then create and use a TiDB Cloud Filesystem or query a TiDB Cloud Starter database. +summary: Install and configure TiDB Cloud CLI, then create and use a TiDB Cloud Filesystem or manage and query a TiDB Cloud Starter database. --- # Get Started with TiDB Cloud CLI -[TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) instances and [TiDB Cloud Filesystems](/ai/ti/ti-overview.md#tidb-cloud-filesystem). It supports both interactive use and automation, with JSON as the default output format for commands. +[TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) instances and [TiDB Cloud Filesystem](/ai/ti/ti-overview.md#tidb-cloud-filesystem) file systems. TiDB Cloud CLI supports both interactive and automated use. By default, command output is in JSON format, making it agent friendly. 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](/ai/ti/ti-overview.md). @@ -86,73 +86,58 @@ Depending on your operating system, take the following steps to install TiDB Clo 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](/ai/ti/reference/ti-regions-security-and-limitations.md#supported-regions). + - 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](/ai/ti/reference/ti-regions-security-and-limitations.md#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: ```bash - ti db list-db-clusters --db-cluster-type starter --output text + ti fs list-file-systems ``` Example output: ```bash { - "profile": "default", - "region_code": "aws-us-east-1", - "credentials_stored": true + "region_code": "aws-us-west-2", + "file_systems": [] } ``` ## Step 3. Choose a workflow -Complete either of the following workflows. +Please proceed with either of the following workflows based on your needs. Would you like to use TiDB Cloud Filesystem or Starter? -- [Option A: Create and use a Filesystem](/ai/ti/ti-quick-start.md#option-a-create-and-use-a-filesystem) -- [Option B: Create a TiDB Cloud Starter instance and query the database](/ai/ti/ti-quick-start.md#option-b-create-a-tidb-cloud-starter-instance-and-query-the-database) +- [Option A: TiDB Cloud Filesystem](/ai/ti/ti-quick-start.md#option-a-create-and-use-a-filesystem) +- [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-create-a-tidb-cloud-starter-instance-and-query-the-database) -### Option A: Create and use a Filesystem +### Option A: TiDB Cloud 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: +1. Create a file system and obtain the access token (typically performed outside the sandbox): ```bash - export TI_FS_FILE_SYSTEM_ID="$(ti fs create-file-system \ - --wait \ - --query file_system_id \ - --output text)" + export TI_FS_TOKEN="$(ti fs create-file-system --file-system-name agent-workspace --wait --query fs_token --output text --region aws-us-west-2)" ``` - `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: +2. Mount the filesystem to a local path and use it as a normal POSIX-compliant filesystem (typically performed within the sandbox): ```bash - printf 'hello from ti\n' | ti fs copy-file \ - --from-stdin \ - --to-remote /hello.txt - - ti fs read-file \ - --path /hello.txt - ``` - - Expected output: - - ```text - hello from ti + export TI_FS_TOKEN=$TI_FS_TOKEN + mkdir ~/mnt-test + ti fs mount-file-system --file-system-name agent-workspace --mount-path ~/mnt-test --region aws-us-west-2 + echo 'Hello Sandbox Workspace' >> ~/mnt-test/hello.txt + ls -l ~/mnt-test/hello.txt ``` -3. Delete the Filesystem: +3. Unmount the file system to release the workspace before passing it to another sandbox (typicall performed within the sandbox): ```bash - ti fs delete-file-system \ - --file-system-id "$TI_FS_FILE_SYSTEM_ID" - unset TI_FS_FILE_SYSTEM_ID + ti fs unmount-file-system --mount-path ~/mnt-test --region aws-us-west-2 ``` -### Option B: Create a TiDB Cloud Starter instance and query the database +### Option B: TiDB Cloud Starter 1. Create a TiDB Cloud Starter instance and save its ID: @@ -180,13 +165,14 @@ A TiDB Cloud Filesystem is a persistent, shareable cloud file system that you ca 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: +3. Generate the connection string: ```bash - ti db delete-db-cluster \ + DATABASE_URL=$(ti db format-db-connection-string \ --db-cluster-id "$TI_DB_CLUSTER_ID" \ - --wait - unset TI_DB_CLUSTER_ID + --read-write --query connection_string \ + --output text) + echo $DATABASE_URL ``` ## What's next From adedd4661ff990660fc13c7dc44f0388f0545e68 Mon Sep 17 00:00:00 2001 From: Guanglei BAO Date: Wed, 23 Sep 2026 17:19:51 +0800 Subject: [PATCH 02/10] Apply batched suggestions from code review Co-authored-by: Grace Cai --- ai/ti/ti-quick-start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md index c202e759b4b84..514192ed60f1a 100644 --- a/ai/ti/ti-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -5,7 +5,7 @@ summary: Install and configure TiDB Cloud CLI, then create and use a TiDB Cloud # Get Started with TiDB Cloud CLI -[TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) instances and [TiDB Cloud Filesystem](/ai/ti/ti-overview.md#tidb-cloud-filesystem) file systems. TiDB Cloud CLI supports both interactive and automated use. By default, command output is in JSON format, making it agent friendly. +[TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) instances and [file systems in TiDB Cloud Filesystem](/ai/ti/ti-overview.md#tidb-cloud-filesystem). TiDB Cloud CLI supports both interactive and automated use. By default, command output is in JSON format, making it agent friendly. 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](/ai/ti/ti-overview.md). From a66c7076c732ccbfe43d6e1f6b7bb36dde1d9ca1 Mon Sep 17 00:00:00 2001 From: Guanglei BAO Date: Wed, 23 Sep 2026 17:20:06 +0800 Subject: [PATCH 03/10] Apply batched suggestions from code review Co-authored-by: Grace Cai --- ai/ti/ti-quick-start.md | 364 ++++++++++++++++++++-------------------- 1 file changed, 182 insertions(+), 182 deletions(-) diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md index 514192ed60f1a..d77a76a24b242 100644 --- a/ai/ti/ti-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -1,183 +1,183 @@ ---- -title: Get Started with TiDB Cloud CLI -summary: Install and configure TiDB Cloud CLI, then create and use a TiDB Cloud Filesystem or manage and query a TiDB Cloud Starter database. ---- - -# Get Started with TiDB Cloud CLI - +--- +title: Get Started with TiDB Cloud CLI +summary: Install and configure TiDB Cloud CLI, then create and use a TiDB Cloud Filesystem or manage and query a TiDB Cloud Starter database. +--- + +# Get Started with TiDB Cloud CLI + [TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) instances and [file systems in TiDB Cloud Filesystem](/ai/ti/ti-overview.md#tidb-cloud-filesystem). TiDB Cloud CLI supports both interactive and automated use. By default, command output is in JSON format, making it agent friendly. - -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](/ai/ti/ti-overview.md). - -> **Note:** -> -> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. - -## Prerequisites - -Before you begin, obtain a TiDB Cloud API public key and private key from the [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys) page in the [TiDB Cloud console](https://tidbcloud.com/). 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: - - ```bash - 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: - - ```bash - 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: - - ```bash - echo 'export PATH="$HOME/.ti/bin:$PATH"' >> ~/.zshrc - source ~/.zshrc - ``` - -
- -
- -1. On Windows PowerShell, run the following command to install TiDB Cloud CLI: - - ```powershell - $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: - - ```powershell - $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: - - ```powershell - $tiBin = "$HOME\.ti\bin" - [Environment]::SetEnvironmentVariable("Path", "$tiBin;$([Environment]::GetEnvironmentVariable('Path', 'User'))", "User") - ``` - -
- - -## Step 2. Configure TiDB Cloud CLI - -1. Run the interactive configuration: - - ```bash - 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](/ai/ti/reference/ti-regions-security-and-limitations.md#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: - - ```bash - ti fs list-file-systems - ``` - - Example output: - - ```bash - { - "region_code": "aws-us-west-2", - "file_systems": [] - } - ``` - -## Step 3. Choose a workflow - -Please proceed with either of the following workflows based on your needs. Would you like to use TiDB Cloud Filesystem or Starter? - -- [Option A: TiDB Cloud Filesystem](/ai/ti/ti-quick-start.md#option-a-create-and-use-a-filesystem) -- [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-create-a-tidb-cloud-starter-instance-and-query-the-database) - -### Option A: TiDB Cloud 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 file system and obtain the access token (typically performed outside the sandbox): - - ```bash - export TI_FS_TOKEN="$(ti fs create-file-system --file-system-name agent-workspace --wait --query fs_token --output text --region aws-us-west-2)" - ``` - -2. Mount the filesystem to a local path and use it as a normal POSIX-compliant filesystem (typically performed within the sandbox): - - ```bash - export TI_FS_TOKEN=$TI_FS_TOKEN - mkdir ~/mnt-test - ti fs mount-file-system --file-system-name agent-workspace --mount-path ~/mnt-test --region aws-us-west-2 - echo 'Hello Sandbox Workspace' >> ~/mnt-test/hello.txt - ls -l ~/mnt-test/hello.txt - ``` - -3. Unmount the file system to release the workspace before passing it to another sandbox (typicall performed within the sandbox): - - ```bash - ti fs unmount-file-system --mount-path ~/mnt-test --region aws-us-west-2 - ``` - -### Option B: TiDB Cloud Starter - -1. Create a TiDB Cloud Starter instance and save its ID: - - ```bash - 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: - - ```bash - 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: - - ```bash - DATABASE_URL=$(ti db format-db-connection-string \ - --db-cluster-id "$TI_DB_CLUSTER_ID" \ - --read-write --query connection_string \ - --output text) - echo $DATABASE_URL - ``` - -## What's next - -- Read the [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) to understand what `ti` manages and when to use it. -- Follow the task guides to manage [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) or [Filesystem resources](/tidb-cloud-filesystem/manage-filesystem-resources.md). -- Explore the [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) for command groups, global options, and shared CLI behavior. -- Learn about [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) to set up multiple profiles or non-interactive authentication. + +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](/ai/ti/ti-overview.md). + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Prerequisites + +Before you begin, obtain a TiDB Cloud API public key and private key from the [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys) page in the [TiDB Cloud console](https://tidbcloud.com/). 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: + + ```bash + 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: + + ```bash + 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: + + ```bash + echo 'export PATH="$HOME/.ti/bin:$PATH"' >> ~/.zshrc + source ~/.zshrc + ``` + +
+ +
+ +1. On Windows PowerShell, run the following command to install TiDB Cloud CLI: + + ```powershell + $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: + + ```powershell + $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: + + ```powershell + $tiBin = "$HOME\.ti\bin" + [Environment]::SetEnvironmentVariable("Path", "$tiBin;$([Environment]::GetEnvironmentVariable('Path', 'User'))", "User") + ``` + +
+ + +## Step 2. Configure TiDB Cloud CLI + +1. Run the interactive configuration: + + ```bash + 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](/ai/ti/reference/ti-regions-security-and-limitations.md#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: + + ```bash + ti fs list-file-systems + ``` + + Example output: + + ```bash + { + "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](/ai/ti/ti-quick-start.md#option-a-create-and-use-a-filesystem) +- [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-create-a-tidb-cloud-starter-instance-and-query-the-database) + +### Option A: TiDB Cloud 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 file system and obtain the access token (typically performed outside the sandbox): + + ```bash + export TI_FS_TOKEN="$(ti fs create-file-system --file-system-name agent-workspace --wait --query fs_token --output text --region aws-us-west-2)" + ``` + +2. Mount the filesystem to a local path and use it as a normal POSIX-compliant filesystem (typically performed within the sandbox): + + ```bash + export TI_FS_TOKEN=$TI_FS_TOKEN + mkdir ~/mnt-test + ti fs mount-file-system --file-system-name agent-workspace --mount-path ~/mnt-test --region aws-us-west-2 + echo 'Hello Sandbox Workspace' >> ~/mnt-test/hello.txt + ls -l ~/mnt-test/hello.txt + ``` + +3. Unmount the file system to release the workspace before passing it to another sandbox (typicall performed within the sandbox): + + ```bash + ti fs unmount-file-system --mount-path ~/mnt-test --region aws-us-west-2 + ``` + +### Option B: TiDB Cloud Starter + +1. Create a TiDB Cloud Starter instance and save its ID: + + ```bash + 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: + + ```bash + 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: + + ```bash + DATABASE_URL=$(ti db format-db-connection-string \ + --db-cluster-id "$TI_DB_CLUSTER_ID" \ + --read-write --query connection_string \ + --output text) + echo $DATABASE_URL + ``` + +## What's next + +- Read the [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) to understand what `ti` manages and when to use it. +- Follow the task guides to manage [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) or [Filesystem resources](/tidb-cloud-filesystem/manage-filesystem-resources.md). +- Explore the [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) for command groups, global options, and shared CLI behavior. +- Learn about [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) to set up multiple profiles or non-interactive authentication. From 7d2f8566333563a59f5f95013fc399e41f764bd9 Mon Sep 17 00:00:00 2001 From: qiancai Date: Wed, 23 Sep 2026 17:25:05 +0800 Subject: [PATCH 04/10] Update ti-quick-start.md --- ai/ti/ti-quick-start.md | 366 ++++++++++++++++++++-------------------- 1 file changed, 183 insertions(+), 183 deletions(-) diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md index d77a76a24b242..885a581e89250 100644 --- a/ai/ti/ti-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -1,183 +1,183 @@ ---- -title: Get Started with TiDB Cloud CLI -summary: Install and configure TiDB Cloud CLI, then create and use a TiDB Cloud Filesystem or manage and query a TiDB Cloud Starter database. ---- - -# Get Started with TiDB Cloud CLI - -[TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) instances and [file systems in TiDB Cloud Filesystem](/ai/ti/ti-overview.md#tidb-cloud-filesystem). TiDB Cloud CLI supports both interactive and automated use. By default, command output is in JSON format, making it agent friendly. - -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](/ai/ti/ti-overview.md). - -> **Note:** -> -> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. - -## Prerequisites - -Before you begin, obtain a TiDB Cloud API public key and private key from the [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys) page in the [TiDB Cloud console](https://tidbcloud.com/). 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: - - ```bash - 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: - - ```bash - 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: - - ```bash - echo 'export PATH="$HOME/.ti/bin:$PATH"' >> ~/.zshrc - source ~/.zshrc - ``` - -
- -
- -1. On Windows PowerShell, run the following command to install TiDB Cloud CLI: - - ```powershell - $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: - - ```powershell - $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: - - ```powershell - $tiBin = "$HOME\.ti\bin" - [Environment]::SetEnvironmentVariable("Path", "$tiBin;$([Environment]::GetEnvironmentVariable('Path', 'User'))", "User") - ``` - -
- - -## Step 2. Configure TiDB Cloud CLI - -1. Run the interactive configuration: - - ```bash - 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](/ai/ti/reference/ti-regions-security-and-limitations.md#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: - - ```bash - ti fs list-file-systems - ``` - - Example output: - - ```bash - { - "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](/ai/ti/ti-quick-start.md#option-a-create-and-use-a-filesystem) -- [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-create-a-tidb-cloud-starter-instance-and-query-the-database) - -### Option A: TiDB Cloud 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 file system and obtain the access token (typically performed outside the sandbox): - - ```bash - export TI_FS_TOKEN="$(ti fs create-file-system --file-system-name agent-workspace --wait --query fs_token --output text --region aws-us-west-2)" - ``` - -2. Mount the filesystem to a local path and use it as a normal POSIX-compliant filesystem (typically performed within the sandbox): - - ```bash - export TI_FS_TOKEN=$TI_FS_TOKEN - mkdir ~/mnt-test - ti fs mount-file-system --file-system-name agent-workspace --mount-path ~/mnt-test --region aws-us-west-2 - echo 'Hello Sandbox Workspace' >> ~/mnt-test/hello.txt - ls -l ~/mnt-test/hello.txt - ``` - -3. Unmount the file system to release the workspace before passing it to another sandbox (typicall performed within the sandbox): - - ```bash - ti fs unmount-file-system --mount-path ~/mnt-test --region aws-us-west-2 - ``` - -### Option B: TiDB Cloud Starter - -1. Create a TiDB Cloud Starter instance and save its ID: - - ```bash - 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: - - ```bash - 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: - - ```bash - DATABASE_URL=$(ti db format-db-connection-string \ - --db-cluster-id "$TI_DB_CLUSTER_ID" \ - --read-write --query connection_string \ - --output text) - echo $DATABASE_URL - ``` - -## What's next - -- Read the [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) to understand what `ti` manages and when to use it. -- Follow the task guides to manage [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) or [Filesystem resources](/tidb-cloud-filesystem/manage-filesystem-resources.md). -- Explore the [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) for command groups, global options, and shared CLI behavior. -- Learn about [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) to set up multiple profiles or non-interactive authentication. +--- +title: Get Started with TiDB Cloud CLI +summary: Install and configure TiDB Cloud CLI, then create and use a TiDB Cloud Filesystem or manage and query a TiDB Cloud Starter database. +--- + +# Get Started with TiDB Cloud CLI + +[TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) instances and [file systems in TiDB Cloud Filesystem](/ai/ti/ti-overview.md#tidb-cloud-filesystem). TiDB Cloud CLI supports both interactive and automated use. By default, command output is in JSON format, making it agent friendly. + +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](/ai/ti/ti-overview.md). + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Prerequisites + +Before you begin, obtain a TiDB Cloud API public key and private key from the [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys) page in the [TiDB Cloud console](https://tidbcloud.com/). 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: + + ```bash + 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: + + ```bash + 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: + + ```bash + echo 'export PATH="$HOME/.ti/bin:$PATH"' >> ~/.zshrc + source ~/.zshrc + ``` + +
+ +
+ +1. On Windows PowerShell, run the following command to install TiDB Cloud CLI: + + ```powershell + $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: + + ```powershell + $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: + + ```powershell + $tiBin = "$HOME\.ti\bin" + [Environment]::SetEnvironmentVariable("Path", "$tiBin;$([Environment]::GetEnvironmentVariable('Path', 'User'))", "User") + ``` + +
+ + +## Step 2. Configure TiDB Cloud CLI + +1. Run the interactive configuration: + + ```bash + 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](/ai/ti/reference/ti-regions-security-and-limitations.md#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: + + ```bash + ti fs list-file-systems + ``` + + Example output: + + ```bash + { + "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](/ai/ti/ti-quick-start.md#option-a-create-and-use-a-filesystem) +- [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-create-a-tidb-cloud-starter-instance-and-query-the-database) + +### Option A: TiDB Cloud 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 file system and obtain the access token (typically performed outside the sandbox): + + ```bash + export TI_FS_TOKEN="$(ti fs create-file-system --file-system-name agent-workspace --wait --query fs_token --output text --region aws-us-west-2)" + ``` + +2. Mount the filesystem to a local path and use it as a normal POSIX-compliant filesystem (typically performed within the sandbox): + + ```bash + export TI_FS_TOKEN=$TI_FS_TOKEN + mkdir ~/mnt-test + ti fs mount-file-system --file-system-name agent-workspace --mount-path ~/mnt-test --region aws-us-west-2 + echo 'Hello Sandbox Workspace' >> ~/mnt-test/hello.txt + ls -l ~/mnt-test/hello.txt + ``` + +3. Unmount the file system to release the workspace before passing it to another sandbox (typicall performed within the sandbox): + + ```bash + ti fs unmount-file-system --mount-path ~/mnt-test --region aws-us-west-2 + ``` + +### Option B: TiDB Cloud Starter + +1. Create a TiDB Cloud Starter instance and save its ID: + + ```bash + 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: + + ```bash + 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: + + ```bash + DATABASE_URL=$(ti db format-db-connection-string \ + --db-cluster-id "$TI_DB_CLUSTER_ID" \ + --read-write --query connection_string \ + --output text) + echo $DATABASE_URL + ``` + +## What's next + +- Read the [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) to understand what `ti` manages and when to use it. +- Follow the task guides to manage [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/?plan=starter#starter) or [Filesystem resources](/tidb-cloud-filesystem/manage-filesystem-resources.md). +- Explore the [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) for command groups, global options, and shared CLI behavior. +- Learn about [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) to set up multiple profiles or non-interactive authentication. From 72e0d821de64897f55f3e2772a1e00a36260ea3e Mon Sep 17 00:00:00 2001 From: Guanglei BAO Date: Wed, 23 Sep 2026 17:29:18 +0800 Subject: [PATCH 05/10] Apply suggestion from @guangleibao --- ai/ti/ti-quick-start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md index 885a581e89250..7239d21f8e3d2 100644 --- a/ai/ti/ti-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -115,7 +115,7 @@ Proceed with either of the following workflows based on your needs: 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 file system and obtain the access token (typically performed outside the sandbox): +1. Create a file system and obtain the default access token (typically performed outside the sandbox): ```bash export TI_FS_TOKEN="$(ti fs create-file-system --file-system-name agent-workspace --wait --query fs_token --output text --region aws-us-west-2)" From 5f1c4e7394d4b6c98465c42f1c0f6749c7a59658 Mon Sep 17 00:00:00 2001 From: Guanglei BAO Date: Wed, 23 Sep 2026 17:30:17 +0800 Subject: [PATCH 06/10] Apply suggestion from @coderabbitai[bot] Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- ai/ti/ti-quick-start.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md index 7239d21f8e3d2..6032c27796d40 100644 --- a/ai/ti/ti-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -108,8 +108,8 @@ Depending on your operating system, take the following steps to install TiDB Clo Proceed with either of the following workflows based on your needs: -- [Option A: TiDB Cloud Filesystem](/ai/ti/ti-quick-start.md#option-a-create-and-use-a-filesystem) -- [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-create-a-tidb-cloud-starter-instance-and-query-the-database) +- [Option A: TiDB Cloud Filesystem](/ai/ti/ti-quick-start.md#option-a-tidb-cloud-filesystem) +- [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-tidb-cloud-starter) ### Option A: TiDB Cloud Filesystem From 0ef25c7b37231f8f0a4745e850953aa60a31069e Mon Sep 17 00:00:00 2001 From: Guanglei BAO Date: Wed, 23 Sep 2026 17:30:32 +0800 Subject: [PATCH 07/10] Apply suggestion from @guangleibao --- ai/ti/ti-quick-start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md index 6032c27796d40..e18f072038963 100644 --- a/ai/ti/ti-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -118,7 +118,7 @@ A TiDB Cloud Filesystem is a persistent, shareable cloud file system that you ca 1. Create a file system and obtain the default access token (typically performed outside the sandbox): ```bash - export TI_FS_TOKEN="$(ti fs create-file-system --file-system-name agent-workspace --wait --query fs_token --output text --region aws-us-west-2)" + 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. Mount the filesystem to a local path and use it as a normal POSIX-compliant filesystem (typically performed within the sandbox): From 969cec7219421ad877ea32a552e19dcebd622259 Mon Sep 17 00:00:00 2001 From: Guanglei BAO Date: Wed, 23 Sep 2026 17:31:03 +0800 Subject: [PATCH 08/10] Apply suggestion from @coderabbitai[bot] Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- ai/ti/ti-quick-start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md index e18f072038963..d25bd712e1b72 100644 --- a/ai/ti/ti-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -131,7 +131,7 @@ A TiDB Cloud Filesystem is a persistent, shareable cloud file system that you ca ls -l ~/mnt-test/hello.txt ``` -3. Unmount the file system to release the workspace before passing it to another sandbox (typicall performed within the sandbox): +3. Unmount the file system to release the workspace before passing it to another sandbox (typically performed within the sandbox): ```bash ti fs unmount-file-system --mount-path ~/mnt-test --region aws-us-west-2 From 6e3ce4277b82d5f723565ff5ece01461978adab2 Mon Sep 17 00:00:00 2001 From: Guanglei BAO Date: Wed, 23 Sep 2026 17:31:17 +0800 Subject: [PATCH 09/10] Apply suggestion from @guangleibao --- ai/ti/ti-quick-start.md | 1 - 1 file changed, 1 deletion(-) diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md index d25bd712e1b72..10dcc41f0cf94 100644 --- a/ai/ti/ti-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -172,7 +172,6 @@ A TiDB Cloud Filesystem is a persistent, shareable cloud file system that you ca --db-cluster-id "$TI_DB_CLUSTER_ID" \ --read-write --query connection_string \ --output text) - echo $DATABASE_URL ``` ## What's next From 4805ca10ba5587f78869ff0aac99736b64c4a34e Mon Sep 17 00:00:00 2001 From: qiancai Date: Wed, 23 Sep 2026 17:42:11 +0800 Subject: [PATCH 10/10] Update ti-quick-start.md --- ai/ti/ti-quick-start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md index 9652268e8ff37..7e083b76af0fe 100644 --- a/ai/ti/ti-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -111,7 +111,7 @@ Proceed with either of the following workflows based on your needs: - [Option A: TiDB Cloud Filesystem](/ai/ti/ti-quick-start.md#option-a-tidb-cloud-filesystem) - [Option B: TiDB Cloud Starter](/ai/ti/ti-quick-start.md#option-b-tidb-cloud-starter) -### Option A: Create and use a file system +### 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.