v0.2.4

TiDB Cloud CLI v0.2.4

This release adds copy-on-write Filesystem layer workflows and tenant-scoped AI provider configuration, improves quota and authentication guidance, and tightens Filesystem authorization boundaries.

What's new

• New ti fs fork-layer, list-layer-chain, and delete-layer commands support parallel copy-on-write workspaces, ancestry inspection, and explicit abandonment of rejected timelines.
• ti fs mount-file-system can mount a writable layer or a read-only historical checkpoint through --layer-ref and --checkpoint-id. Existing checkpoint, diff, rollback, and commit commands complete the versioned workspace workflow.
• New extract and embedding configuration commands let organization administrators inspect, enable, update, and disable tenant-scoped image, audio, video, and embedding providers. Provider secrets are accepted only through TI_FS_AI_PROVIDER_API_KEY and are never persisted or printed by ti.
• Filesystem inventory now includes media quota fields returned by the service.
• ti fs create-file-system recognizes structured free-plan quota errors and links directly to TiDB Cloud billing when a payment method is required.
• Missing TiDB Cloud API credentials now include the API key creation URL in the actionable error.
• Filesystem deletion and token administration consistently require TiDB Cloud API credentials. An FS token grants data-plane use and does not imply resource-administration permission.
• Telemetry ingestion now stores events only in TiDB. Compatibility with both current ti and legacy tdc telemetry clients is retained.

Breaking change

The public --foreground flag has been removed from ti fs mount-file-system and its mount alias. Mounts are background operations managed by ti; use drain-file-system and unmount-file-system to stop them safely.

Upgrade from v0.2.3

Drain and unmount active Filesystem mounts before replacing ti and its bundled ti-drive9 companion, then run:

ti update --check
ti update
ti --version

New installations can use:

curl -fsSL https://github.com/tidbcloud/ti-cli/releases/download/v0.2.4/install.sh | sh -s -- --yes
export PATH="$HOME/.ti/bin:$PATH"
ti --version

Fork a versioned workspace

Fork two independent child layers from a checkpoint and inspect one child's ancestry:

SEED="$(ti fs create-layer-checkpoint \
  --layer-id research-base \
  --checkpoint-id seed \
  --label workspace-seed \
  --query checkpoint_id \
  --output text)"

ti fs fork-layer \
  --parent-layer-ref research-base \
  --layer-name style-brief \
  --checkpoint-id "$SEED"
ti fs fork-layer \
  --parent-layer-ref research-base \
  --layer-name style-analyst \
  --checkpoint-id "$SEED"
ti fs list-layer-chain --layer-ref style-analyst

Mount a historical checkpoint for read-only comparison:

mkdir -p ./peek/v5
ti fs mount-file-system \
  --mount-path ./peek/v5 \
  --remote-path /research/q3-market \
  --driver fuse \
  --layer-ref style-analyst \
  --checkpoint-id v5

Checkpoint mounts require FUSE. Recursive copy-file and --layer-id remain mutually exclusive; seed a directory tree through a writable FUSE layer mount instead.

v0.2.3

TiDB Cloud CLI v0.2.3

This release moves TiDB Cloud Filesystem resource inventory and lifecycle management onto the TiDB Cloud control plane, adds organization-visible metadata, and makes Filesystem region and mount behavior more predictable.

What's new

• ti fs create-file-system, list-file-systems, describe-file-system, and delete-file-system now use the typed TiDB Cloud Filesystem tenant API. Remote inventory is authoritative and remains selected by immutable file_system_id.
• Filesystem creation accepts an optional display name and repeatable labels. List supports display-name and exact-label filters, while list and describe expose status, labels, quota usage, and whether the current machine has a local token without revealing token plaintext.
• TiDB Cloud Filesystem endpoint mappings for aws-us-east-1, aws-ap-southeast-1, aws-us-west-2, and alicloud-ap-southeast-1 are built into ti. Runtime commands and installers no longer depend on downloading a Drive9 region manifest.
• Alibaba Cloud placement now uses the canonical alicloud-ap-southeast-1 code. Existing local credentials using the legacy ali-ap-southeast-1 code remain usable.
• Successful background mounts now return the structured ti result without raw Drive9 startup or misleading unmount guidance. Foreground mounts still stream companion output, and failed background mounts retain their diagnostic log path.
• Installer output is shorter and command help fixes several visible wording and spacing errors.

Upgrade from v0.2.2

Drain and unmount active Filesystem mounts before replacing ti and its bundled ti-drive9 companion, then run:

ti update --check
ti update
ti --version

New installations can use:

curl -fsSL https://github.com/tidbcloud/ti-cli/releases/download/v0.2.3/install.sh | sh -s -- --yes
export PATH="$HOME/.ti/bin:$PATH"
ti --version

Manage Filesystem metadata

Create a Filesystem with organization-visible metadata and wait for it to become ready:

FILE_SYSTEM_ID="$(ti fs create-file-system \
  --display-name agent-workspace \
  --label environment=development \
  --wait \
  --query file_system_id \
  --output text)"

Filter remote inventory and inspect the selected resource:

ti fs list-file-systems \
  --display-name agent-workspace \
  --label environment=development \
  --output text
ti fs describe-file-system --file-system-id "$FILE_SYSTEM_ID" --output text

Display names and labels are metadata only. Continue to use --file-system-id, TI_FS_FILE_SYSTEM_ID, or an explicitly supplied Filesystem token to select a resource.

v0.2.2

TiDB Cloud CLI v0.2.2

This release adds complete TiDB Cloud Filesystem token lifecycle management and makes --output text reliable across structured commands.

What's new

• A Filesystem can now have multiple independently managed owner and scoped tokens for machines, CI jobs, and agent sandboxes. New commands generate, list, enable, disable, delete, and refresh tokens.
• Owner tokens retain full Filesystem access. Scoped tokens can be restricted to selected paths and read, list, search, write, or delete operations, and the Filesystem backend enforces those boundaries.
• TI_FS_TOKEN and --fs-token accept either owner or scoped credentials. Scoped tokens can refresh themselves but cannot issue child tokens or manage token inventory.
• Token plaintext is returned only when generated or refreshed. --store-locally can select a returned token in the local credential registry, while externally supplied tokens remain under the caller's secret-management control.
• Token-changing operations detect active local mounts and require them to be drained and unmounted first, reducing the risk of invalidating a running mount.
• Structured commands now provide deterministic text tables or key-value output. --output text no longer silently falls back to JSON, and queried scalar lists render one value per line.

Upgrade from v0.2.1

Drain and unmount active Filesystem mounts before replacing ti and its bundled ti-drive9 companion, then run:

ti update --check
ti update
ti --version

New installations can use:

curl -fsSL https://github.com/tidbcloud/ti-cli/releases/download/v0.2.2/install.sh | sh -s -- --yes
export PATH="$HOME/.ti/bin:$PATH"
ti --version

Manage Filesystem tokens

Generate an additional owner token and retain its one-time plaintext response:

umask 077
ti fs generate-file-system-token \
  --file-system-id "<file-system-id>" \
  --token-name ci-deploy \
  --ttl 24h > ./ci-token.json
ti fs list-file-system-tokens --file-system-id "<file-system-id>" --output text

Use an owner token to issue a path-and-operation-limited token for an agent sandbox:

export TI_FS_TOKEN="<owner-fs-token>"
ti fs generate-file-system-scoped-token \
  --subject sandbox-agent \
  --ttl 24h \
  --allow /workspace:read,list,write \
  --allow /artifacts:read,list

Use immutable token IDs from the list response for lifecycle operations:

ti fs disable-file-system-token --file-system-id "<file-system-id>" --token-id "<token-id>"
ti fs enable-file-system-token --file-system-id "<file-system-id>" --token-id "<token-id>"
ti fs delete-file-system-token --file-system-id "<file-system-id>" --token-id "<token-id>"

Authentication changes can take several seconds to converge. For shared environments, distribute and validate a replacement token before disabling or deleting the previous token.

v0.2.1

TiDB Cloud CLI v0.2.1

This release makes TiDB Cloud Filesystem inventory portable across machines and removes client-side TiDB Cloud Project selection from Starter database workflows.

What's new

• ti fs list-file-systems now reads the remote Drive9 inventory by using the configured TiDB Cloud API keys. Filesystems are identified by their server-assigned file_system_id instead of a client-only name.
• Filesystem create returns the server-assigned ID and owner token. Local state stores only known tokens and routing hints keyed by that ID; remote inventory remains authoritative for resource existence and status.
• ti fs import-file-system-token imports an existing owner token on another machine. Because the token contains its Filesystem ID, data-plane and mount commands can also run in a clean sandbox with TI_FS_TOKEN and TI_REGION_CODE only.
• ti configure now validates and stores local input without making a TiDB Cloud API request. Authentication and authorization errors are reported by the first remote command that uses the configured keys.
• Starter cluster creation no longer accepts --project-id, reads a saved project default, or sends project-selection labels. TiDB Cloud selects the server-side default project, while project metadata returned by TiDB Cloud remains unchanged in command output.
• The ti organization list-projects command and its project-read permission are removed.

Breaking changes and migration

Filesystem commands that select an existing resource now use --file-system-id or TI_FS_FILE_SYSTEM_ID. ti fs create-file-system no longer accepts a user-defined Filesystem name. Existing complete name-keyed local credentials are migrated to the ID-keyed credential store without deleting the legacy source.

Existing project_id values in ~/.ti/config are ignored immediately. Running ti configure for that profile removes its legacy project value while preserving other profiles.

Upgrade from v0.2.0

Drain and unmount active Filesystem mounts before replacing ti and its bundled ti-drive9 companion, then run:

ti update --check
ti update
ti --version

New installations can use:

curl -fsSL https://github.com/tidbcloud/ti-cli/releases/download/v0.2.1/install.sh | sh -s -- --yes
export PATH="$HOME/.ti/bin:$PATH"
ti --version

Updated workflows

Configure and create a Starter cluster without selecting a project:

ti configure
ti db create-db-cluster --db-cluster-type starter --db-cluster-name my-app-db --wait

Inspect remote Filesystems and select one for subsequent commands:

ti fs list-file-systems --output text
export TI_FS_FILE_SYSTEM_ID="<file-system-id>"
ti fs check-file-system

Provision a Filesystem and retain the one-time owner token returned in the JSON result:

ti fs create-file-system --wait

v0.2.0

TiDB Cloud CLI v0.2.0

This release renames the TiDB Cloud command-line product from tdc to ti and moves the project to github.com/tidbcloud/ti-cli. It also introduces a product-aware database command architecture while keeping the current public database scope limited to TiDB Cloud Starter.

What's new

• The executable is now ti. Commands use forms such as ti db, ti fs, ti fs-git, ti fs-journal, and ti fs-vault.
• Installers, release archives, the updater, local state, operation logs, telemetry components, and the bundled filesystem companion now use the ti name. The companion is installed as ti-drive9.
• New installations use ~/.ti, TI_* environment variables, and TIDB_CLOUD_PUBLIC_KEY / TIDB_CLOUD_PRIVATE_KEY.
• Existing durable v0.1 state can be migrated safely from ~/.tdc to ~/.ti. Profiles, credentials, preferences, telemetry identity, SQL credentials, and filesystem registrations are copied; the old directory is never modified or deleted.
• Database commands now dispatch through product-specific providers. Commands that do not identify an existing cluster require --db-cluster-type starter. Commands with --db-cluster-id discover the cluster service plan and reject unsupported products before executing an operation.
• ti db list-db-clusters --db-cluster-type starter returns verified Starter clusters from the effective region through bounded, filtered pagination and a ti-owned continuation token.

Upgrade from tdc v0.1.x

This is an intentional breaking change. There is no tdc command alias, and the old tdc update command cannot install ti from the renamed repository.

Before upgrading, drain and unmount every filesystem mounted by tdc. Then install ti directly.

On macOS or Linux:

curl -fsSL https://github.com/tidbcloud/ti-cli/releases/download/v0.2.0/install.sh | sh -s -- --yes
export PATH="$HOME/.ti/bin:$PATH"
ti --version

On Windows PowerShell:

$script = "$env:TEMP\install-ti.ps1"
iwr https://github.com/tidbcloud/ti-cli/releases/download/v0.2.0/install.ps1 -OutFile $script
powershell -ExecutionPolicy Bypass -File $script -Yes
$env:Path = "$HOME\.ti\bin;$env:Path"
ti --version

The installer runs the same migration logic as the CLI. Migration proceeds only when ~/.ti does not already contain independent state. If both ~/.tdc and ~/.ti exist without a valid migration marker, ti fails with an actionable conflict instead of merging or overwriting them. Verify the new installation before manually removing old binaries or ~/.tdc.

Automation should move from TDC_* variables to TI_*, and from TDC_PUBLIC_KEY / TDC_PRIVATE_KEY to TIDB_CLOUD_PUBLIC_KEY / TIDB_CLOUD_PRIVATE_KEY. The v0.2 release line temporarily accepts a legacy variable when its new equivalent is absent; conflicting old and new values fail before any mutation.

Get started

Configure a profile:

ti configure

Create and query a Starter cluster:

CLUSTER_ID="$(ti db create-db-cluster --db-cluster-type starter --db-cluster-name my-app-db --wait --query id --output text)"
ti db create-db-sql-users --db-cluster-id "$CLUSTER_ID"
ti db execute-sql-statement --db-cluster-id "$CLUSTER_ID" --read-write --sql "SELECT 1"

Create and mount a TiDB Cloud Filesystem:

ti fs create-file-system --file-system-name workspace --wait
mkdir -p "$HOME/workspace"
ti fs mount-file-system --file-system-name workspace --mount-path "$HOME/workspace"

Future upgrades use the new updater:

ti update --check
ti update

The v0.1 tdc release line is no longer updated.

v0.1.7

tdc v0.1.7

This release adds optional, process-scoped telemetry metadata for integrations that need to segment anonymous CLI usage. Set TDC_TELEMETRY_TAG to send a bounded UTF-8 label, and set TDC_TELEMETRY_EXTRA to send one bounded JSON value. Both values are optional, are never persisted locally, and must not contain credentials, tokens, SQL, paths, personal data, profile names, or cloud resource IDs.

The telemetry ingestion service now applies versioned Goose migrations before starting. The migration path preserves existing telemetry events, adds storage for the optional tag and JSON metadata, and verifies the deployed schema with an isolated TiDB integration test.

v0.1.6

tdc v0.1.6

This release adds privacy-preserving command reliability telemetry to release builds. Eligible commands send one best-effort completion event containing command and flag names without values, stable exit and error codes, duration, region, tdc version, OS, and architecture. Credentials, tokens, SQL text, file paths and contents, command output, API payloads, profile names, and cloud resource IDs are never collected.

Telemetry is sent only to the tdc-owned ingestion service. It is disabled by default in development and CI, never runs for help, version, commandless usage, or tdc update, and cannot change command output or exit status. To opt out persistently, create or edit ~/.tdc/.preferences:

[telemetry]
enabled = false

For one process, run TDC_TELEMETRY=off tdc ....

v0.1.5

tdc v0.1.5

This release makes TiDB Cloud Starter cluster creation shorter and more deterministic for users, scripts, and agents. Because tdc currently manages Starter clusters exclusively, tdc db create-db-cluster now defaults the cluster type to starter; users only need to provide the cluster name and can still explicitly pass --db-cluster-type starter when desired.

export CLUSTER_ID="$(tdc db create-db-cluster \
  --db-cluster-name agent-db \
  --wait \
  --query id \
  --output text)"

Unsupported explicit cluster types continue to fail before a request is sent. The release also refines command help descriptions and Preview labels across the Filesystem command surface, and simplifies the README quick-start, configuration, mount, and help workflows.

Upgrade an existing installation with:

tdc update --check
tdc update
tdc --version

v0.1.4

tdc v0.1.4

This release makes the tdc command line easier to discover and use consistently from terminals, scripts, and agents. Running tdc without a command now returns a compact AWS-style two-level usage synopsis, while explicit help, --help, and --version requests remain successful. Generated help displays flag value types in angle brackets, lists required flags first, and marks them with (required).

--db-cluster-name <string> (required)   Starter DB cluster display name
--project-id <string>                   TiDB Cloud project ID

Filesystem deletion now uses the resource identifier directly without repeating it through a console-style confirmation flag:

tdc fs delete-file-system --file-system-name workspace

The release also clarifies the configured value as the default region code, separates human-readable errors from preceding terminal output with a blank line, and keeps the updated contracts covered by unit and binary end-to-end tests.

Upgrade an existing installation with:

tdc update --check
tdc update
tdc --version

v0.1.3

tdc v0.1.3

This release makes asynchronous TiDB Cloud lifecycle operations deterministic for agents and scripts through one consistent --wait flag. Commands still return as soon as the service accepts a request by default; add --wait when the next step depends on the resource being ready or gone.

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

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

The same contract applies when provisioning a TiDB Cloud Filesystem. A trusted machine can wait for the Drive9-backed data plane and capture the owner token in one command before injecting it into an agent sandbox:

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

Cluster creation waits for ACTIVE, branch creation waits for ACTIVE, cluster deletion waits for DELETED or confirmed inaccessibility, and Filesystem creation waits until the data-plane root is readable. Timeouts and interruptions never delete or recreate an accepted resource. Filesystem deletion remains asynchronous because the backend does not expose reliable completion status; accepted deletion now correctly reports deleting instead of deleted.

Upgrade an existing installation with:

tdc update --check
tdc update
tdc --version