📣
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 Command Line Interface Overview

The TiDB Cloud Command Line Interface—ti—is the new CLI for managing TiDB Cloud Starter databases and TiDB Cloud Filesystem. It is designed for repeatable automation: commands are non-interactive except for configuration, structured output is JSON by default, and database and Filesystem credentials have separate security boundaries.

When to use TiDB Cloud CLI

Use the TiDB Cloud CLI when a workflow needs to manage TiDB Cloud from a terminal, script, CI job, or AI agent environment. Typical scenarios include:

  • Automate Starter database lifecycle operations. Create a cluster or branch, wait until it is ready, inspect it as JSON, and delete only the resource identified by your workflow.
  • Separate SQL privileges by task. Give an agent read-only access for inspection, read-write access for application work, or admin access for schema and privilege management without passing database passwords in every command.
  • Keep sandbox work after the sandbox disappears. Provision a Filesystem on a trusted machine, then pass only its token, region, and name to an ephemeral environment.
  • Share one workspace across machines and interfaces. Read and write the same remote namespace through direct data-plane commands or a FUSE or WebDAV mount.
  • Start large Git workspaces sooner. Expose a repository file tree while clean Git data continues hydrating in the background.
  • Record and delegate agent work. Store append-only workflow events in journals and grant temporary, scoped access to selected vault fields.

For a visual, interactive workflow, use the TiDB Cloud console instead. For TiDB Cloud Essential or CLI operations that the TiDB Cloud CLI does not provide, use ticloud.

TiDB Cloud CLI, ticloud, and the TiDB Cloud console

TiDB Cloud currently has two command-line interfaces with different product scopes. ti is the new CLI for Starter and TiDB Cloud Filesystem. ticloud remains the CLI for Essential and also supports existing Starter workflows.

InterfaceUse it forInteraction model
ti (Preview)New TiDB Cloud Starter automation and TiDB Cloud Filesystem workflowsPredictable commands, JSON output by default, and non-interactive operation except for ti configure
ticloudTiDB Cloud Essential and operations not available in the TiDB Cloud CLI, such as import, export, and audit-log commandsTraditional CLI workflows with interactive and non-interactive modes
TiDB Cloud consoleVisual resource inspection, guided setup, and manual operationsBrowser-based and interactive

New Starter and Filesystem automation should use the TiDB Cloud CLI. Use ticloud for Essential and any command that has no TiDB Cloud CLI equivalent. The TiDB Cloud CLI replaces ticloud only for the Starter workflows it supports; the TiDB Cloud CLI does not replace ticloud for Essential.

What TiDB Cloud CLI manages

The TiDB Cloud CLI covers the following functional areas:

  • Starter cluster and branch lifecycle operations;
  • read-only, read-write, and admin SQL users, connection strings, and one-statement SQL execution;
  • Filesystem provisioning, direct file operations, and FUSE or WebDAV mounts;
  • Filesystem layers, packs, Git workspaces, journals, and vault operations;
  • profiles, regional endpoint selection, local credentials, updates, structured output, and JMESPath queries.

The ti executable has a two-level command model:

ti <service> <operation>

Examples include ti db list-db-clusters --db-cluster-type starter, ti fs copy-file, and ti fs-journal verify-journal. The top-level ti configure and ti update commands configure and maintain the CLI.

TiDB Cloud Filesystem runtime

Drive9 is the data-plane runtime used by TiDB Cloud Filesystem. The TiDB Cloud CLI installs and manages this runtime as a bundled companion executable named ti-drive9. It is an implementation component of the TiDB Cloud Filesystem experience, not a separate product that you need to select or install.

The ti executable owns profile selection, TiDB Cloud credentials, region and Filesystem selection, output formatting, and CLI error behavior. The bundled runtime implements Filesystem data-plane semantics, FUSE and WebDAV mounts, layers, pack and unpack, Git workspace acceleration, journals, and vault operations. You do not need to configure or invoke ti-drive9 separately for normal TiDB Cloud CLI workflows.

Find the right documentation

Follow the Quick Start to install the TiDB Cloud CLI and complete your first Starter or Filesystem workflow. Use these guides for task-oriented instructions:

Scenario references

Use scenarios to follow a complete workflow that combines multiple commands and features:

For users and automation:

For AI agents:

Reference

To report a problem or suggest an improvement, create an issue in the TiDB Cloud CLI GitHub repository.

Was this page helpful?