📣
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

TiDB Cloud CLI (ti) Overview

TiDB Cloud CLI (ti) is a CLI for managing TiDB Cloud Starter instances and TiDB Cloud Filesystems. It is designed for both interactive use and automation, with structured JSON output by default.

TiDB Cloud Filesystem

A TiDB Cloud Filesystem is a serverless distributed file system designed for AI agents and automation workloads. It provides a persistent, shareable file namespace that stays available independently of the local machine, sandbox, or CI runner that accesses it, making it useful for persistent storage, shared workspaces, and AI agent workflows.

When to use TiDB Cloud CLI (ti)

Use the TiDB Cloud CLI (ti) when you want to manage TiDB Cloud from a terminal, script, CI job, or AI agent environment.

Typical use caseWhat you can do
Automate TiDB Cloud Starter lifecycle operationsCreate and manage TiDB Cloud Starter instances and branches, wait until they are ready, inspect results as JSON, run SQL statements, and delete resources by ID.
Separate SQL privileges by taskUse CLI-managed read-only, read-write, or admin identities for each task without handling database passwords in every command.
Persist and share files across environmentsKeep files available across local machines, CI jobs, sandboxes, and other ephemeral environments, and access the same remote namespace through direct file commands or supported FUSE and WebDAV mounts.
Use Filesystems in ephemeral environmentsProvision a Filesystem on a trusted machine, then give a sandbox its Filesystem token and region code without copying a CLI profile or providing TiDB Cloud API keys.
Start large Git workspaces soonerExpose a repository file tree while clean Git data continues hydrating in the background.
Record and delegate agent workStore append-only, hash-chained workflow events in journals and grant temporary, scoped access to selected vault fields.

For visual, guided workflows, use the TiDB Cloud console. For TiDB Cloud Essential or operations that ti does not support, use ticloud.

What TiDB Cloud CLI manages

The TiDB Cloud CLI covers the following functional areas:

  • TiDB Cloud Starter
    • Instance and branch lifecycle operations
    • SQL users and connection information
    • SQL statement execution
  • TiDB Cloud Filesystem
    • Filesystem lifecycle and file operations
    • FUSE and WebDAV mounts
    • Layers, packs, and Git workspaces
    • Journals and vaults
  • CLI configuration
    • Profiles, regions, and local credentials
    • CLI updates
    • Output formatting and JMESPath queries

Most resource commands follow a two-level command model:

ti <command-group> <operation>

For example, ti db list-db-clusters --db-cluster-type starter, ti fs copy-file, and ti fs-journal verify-journal.

You can also use the top-level ti configure and ti update commands to configure and maintain the CLI.

Differences between ti and ticloud

TiDB Cloud currently provides two CLIs with different scopes: ti and ticloud.

ti is designed for automation with TiDB Cloud Starter and for managing TiDB Cloud Filesystems, while ticloud continues to support TiDB Cloud Essential and additional TiDB Cloud operations that are not available in ti.

CLIBest forKey characteristics
tiSupported TiDB Cloud Starter automation workflows and TiDB Cloud FilesystemsDesigned for automation; outputs JSON by default; commands support non-interactive workflows, while ti configure can also prompt interactively
ticloudTiDB Cloud Essential, existing TiDB Cloud Starter workflows, and operations not available in ti (such as data import, data export, and audit log operations)Supports additional TiDB Cloud operations that are not available in ti, and both interactive and non-interactive modes

ti does not replace ticloud. Choose the CLI based on the resource and operation you need:

  • For new automation workflows with TiDB Cloud Starter, use ti when it supports the operations you need.
  • For managing TiDB Cloud Filesystems, use ti.
  • If you have existing ticloud workflows for TiDB Cloud Starter or TiDB Cloud Essential, you can continue to use them.
  • For TiDB Cloud Essential or operations not available in ti (such as data import, data export, and audit log operations), use ticloud.

Next steps

If you are new to the TiDB Cloud CLI, start with the Quick Start to install ti, configure a profile, and complete a basic TiDB Cloud Starter or Filesystem workflow.

Then continue based on what you want to do:

Was this page helpful?