tdc

tdc is the command-line interface for TiDB Cloud Filesystem and TiDB Cloud Starter.

tdc is currently in Preview. Its features and command-line interface might change without prior notice.

• TiDB Cloud Filesystem is a distributed file system designed specifically for AI coding agent workloads, with zero infrastructure.
• TiDB Cloud Starter provides distributed database clusters that are fully compatible with MySQL, with zero infrastructure.

Your Agent's Toolbelt

Always-on, zero infrastructure file system for sandboxes — The 3-Command Superpower

An agent can persist state between sessions, share files across sandboxes, snapshot its workspace before attempting a risky operation, and roll back on failure — all through a CLI with POSIX compatibility.

1. Create a filesystem resource and get the returning token (one-time, out of the sandbox)

export TDC_FS_TOKEN="$(tdc fs create-file-system --file-system-name agent-workspace --region <REGION_CODE> --wait --query fs_token --output text)"

2. Mount the filesystem and use just like any regular POSIX-compliant filesystem (inside the sandbox environment)

export TDC_FS_TOKEN="<FS_TOKEN>"
tdc fs mount-file-system --file-system-name agent-workspace --mount-path /path_to_workspace --region <REGION_CODE>
echo "Hello Sandbox Workspace!" >> /path_to_workspace/hello.txt

3. Unmount to safely release the workspace before handing off to another sandbox (inside the sandbox environment)

tdc fs unmount-file-system --mount-path /path_to_workspace --region <REGION_CODE>

Always-on, zero infrastructure MySQL — The 3-Command Superpower

An agent can go from zero to live HTAP SQL (Hybrid Transaction / Analytical Processing) in three commands:

1. Provision a serverless MySQL-compatible cluster, wait until it is active, and capture its ID

export CLUSTER_ID="$(tdc db create-db-cluster --db-cluster-type starter --db-cluster-name my-app-db --wait --query id --output text)"

2. Create the SQL users it needs to connect

tdc db create-db-sql-users --db-cluster-id "$CLUSTER_ID"

3. Retrieve the database connection string for your agent and share it across sandboxes as needed

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

Install

macOS and Linux users:

curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes

After installation, add tdc to the current shell and verify it:

export PATH="$HOME/.tdc/bin:$PATH"
tdc --version

The installer writes tdc and tdc-drive9 to ~/.tdc/bin without sudo. Add the export PATH=... line to your shell profile to make it persistent.

Windows users:

$script = "$env:TEMP\install-tdc.ps1"
iwr https://github.com/tidbcloud/tdc/releases/latest/download/install.ps1 -OutFile $script
powershell -ExecutionPolicy Bypass -File $script -Yes

After installation, add tdc to the current PowerShell session and verify it:

$env:Path = "$HOME\.tdc\bin;$env:Path"
tdc --version

Add $HOME\.tdc\bin to your user PATH to keep tdc available in new PowerShell sessions.

Quick Start Guide

Configure

Configure tdc with a TiDB Cloud Public Key and Private Key from the TiDB Cloud console. Supported region codes are aws-us-east-1, aws-us-west-2, aws-eu-central-1, aws-ap-northeast-1, aws-ap-southeast-1, and ali-ap-southeast-1.

tdc configure --non-interactive --region-code <TDC_REGION_CODE> --tdc-public-key <TDC_PUBLIC_KEY> --tdc-private-key <TDC_PRIVATE_KEY>

Configure verifies the API key by listing all accessible projects, requires exactly one project with type = "tidbx_virtual", and stores its ID as the profile's default project_id in ~/.tdc/config. API credentials remain in ~/.tdc/credentials. Configuration fails without changing the profile when project discovery fails.

[default]
region_code = "aws-us-east-1"
project_id = "1372813089454645969"

TiDB Cloud Filesystem

Supported regions: aws-us-east-1 and aws-ap-southeast-1.

mkdir ~/my-workspace
tdc fs create-file-system --file-system-name my-workspace --wait
tdc fs mount-file-system --mount-path ~/my-workspace

Automatic mounting uses FUSE on Linux and WebDAV on macOS and Windows. macOS users can install macFUSE and explicitly add --driver fuse for the full FUSE experience.

One profile can manage multiple file systems. The first created file system becomes the profile default; later resources can be selected explicitly or made the default:

tdc fs create-file-system --file-system-name scratch
tdc fs list-file-systems
tdc fs describe-file-system --file-system-name scratch

create-file-system returns an file system token (fs_token) in its JSON result. This is the file system owner credential and should be handled as a secret. A configured machine can provision a file system and capture the token without printing the full result:

export TDC_FS_TOKEN="$(tdc fs create-file-system --file-system-name agent-workspace --wait --query fs_token --output text)"

Without --wait, file system creation returns after Drive9 accepts provisioning. With the flag, tdc waits up to 10 minutes until the file system root is readable through the public Drive9 data-plane CLI. A timeout or interruption leaves the file system and its locally stored credentials intact.

An agent sandbox can then use that existing file system without running tdc configure or providing TiDB Cloud API keys:

export TDC_FS_TOKEN="<FS_TOKEN>"
tdc fs mount-file-system --file-system-name agent-workspace --mount-path /path_to_workspace --region aws-us-east-1

TiDB Cloud Starter

tdc db create-db-cluster --db-cluster-name my-distributed-mysql --db-cluster-type starter --wait

Cluster creation uses the configured project_id by default. Use optional --project-id <project-id> to create in another accessible project. An explicit empty --project-id is rejected instead of falling back to the profile.

Without --wait, cluster creation returns as soon as TiDB Cloud accepts the asynchronous create request. With the flag, tdc waits up to 12 minutes and returns the final ACTIVE cluster. A timeout or interruption leaves the created cluster intact and reports its ID for inspection.

Branch creation and cluster deletion have equivalent explicit wait modes:

tdc db create-db-cluster-branch --db-cluster-id <CLUSTER_ID> --db-cluster-branch-name development --wait
tdc db delete-db-cluster --db-cluster-id <CLUSTER_ID> --wait

Branch waiting lasts up to 5 minutes. Cluster deletion waiting lasts up to 12 minutes and succeeds when the API reports DELETED or the deleted cluster is no longer accessible.

Organization Projects

tdc organization list-projects

Each project includes a type: tidbx identifies a regular project and tidbx_virtual identifies a virtual project.

Commands

Run tdc help, tdc <command> help, or tdc <command> <subcommand> help for flags and examples.

All commands

tdc configure
tdc update
tdc organization list-projects

tdc db create-db-cluster
tdc db list-db-clusters
tdc db describe-db-cluster
tdc db update-db-cluster
tdc db delete-db-cluster
tdc db create-db-cluster-branch
tdc db list-db-cluster-branches
tdc db describe-db-cluster-branch
tdc db delete-db-cluster-branch
tdc db create-db-sql-users
tdc db format-db-connection-string
tdc db execute-sql-statement

tdc fs create-file-system
tdc fs delete-file-system
tdc fs list-file-systems
tdc fs describe-file-system
tdc fs set-default-file-system
tdc fs unset-default-file-system
tdc fs check-file-system
tdc fs copy-file
tdc fs read-file
tdc fs list-files
tdc fs describe-file
tdc fs move-file
tdc fs delete-file
tdc fs create-directory
tdc fs chmod-file
tdc fs create-symlink
tdc fs create-hardlink
tdc fs search-file-content
tdc fs find-files
tdc fs create-layer
tdc fs list-layers
tdc fs describe-layer
tdc fs diff-layer
tdc fs create-layer-checkpoint
tdc fs rollback-layer
tdc fs commit-layer
tdc fs pack-file-system
tdc fs unpack-file-system
tdc fs mount-file-system
tdc fs drain-file-system
tdc fs unmount-file-system

tdc fs-git clone-git-workspace
tdc fs-git hydrate-git-workspace
tdc fs-git add-git-worktree
tdc fs-git remove-git-worktree

tdc fs-journal create-journal
tdc fs-journal append-journal-entries
tdc fs-journal read-journal-entries
tdc fs-journal search-journal-entries
tdc fs-journal verify-journal

tdc fs-vault create-secret
tdc fs-vault replace-secret
tdc fs-vault read-secret
tdc fs-vault list-secrets
tdc fs-vault delete-secret
tdc fs-vault create-grant
tdc fs-vault delete-grant
tdc fs-vault list-audit-events
tdc fs-vault run-with-secret
tdc fs-vault mount-vault
tdc fs-vault unmount-vault

Filesystem aliases are cp, cat, ls, stat, mv, rm, mkdir, chmod, symlink, hardlink, grep, find, mount, drain, and umount. Aliases keep the canonical command's long flags.

Update

tdc update --check
tdc update --dry-run
tdc update
tdc update --target-version v0.1.1

tdc update downloads and verifies both tdc and its tdc-drive9 companion before replacing either binary in the user-writable install directory. It never requests sudo. Legacy installations under /usr/local/bin must run the installer once to migrate to ~/.tdc/bin.

Documentation

• English Preview documentation
• 中文预览文档

Build from source

Requirements:

• Go 1.26.5 or newer
• make
• GoReleaser, only for make release-snapshot or release publishing

Build the local binary:

make build

The binary is written to:

bin/tdc

Test

Run local unit and black-box tests without live cloud credentials:

make test
make e2e

Run one live command family against the live-e2e profile:

make live-e2e-configure
make live-e2e-organization
make live-e2e-db
make live-e2e-fs
make live-e2e-fs-git
make live-e2e-fs-journal
make live-e2e-fs-vault

Run the complete live suite in one test process:

make live-e2e

Set LIVE_E2E_PROFILE=<profile> to use a profile other than live-e2e. The DB and FS suites perform real cloud mutations and clean up only resources created by the test run.