From 830959e0dbec5573d9a57d989f9eb17ed31d4df1 Mon Sep 17 00:00:00 2001 From: Cheese Date: Sat, 18 Jul 2026 01:41:33 +0800 Subject: [PATCH 01/29] docs: add tdc preview documentation --- TOC-ai.md | 26 ++ ai/_index.md | 41 +++ .../concepts/tdc-concepts-and-architecture.md | 129 ++++++++ ai/tdc/examples/tdc-agent-sandbox-example.md | 106 ++++++ ai/tdc/examples/tdc-daily-workflow-example.md | 112 +++++++ .../tdc-git-workspace-for-agents-example.md | 83 +++++ .../tdc-journal-agent-workflow-example.md | 84 +++++ .../tdc-query-sql-with-roles-example.md | 103 ++++++ ...hare-filesystem-across-machines-example.md | 100 ++++++ .../tdc-vault-agent-secrets-example.md | 97 ++++++ ai/tdc/guides/tdc-filesystem-git.md | 98 ++++++ ai/tdc/guides/tdc-filesystem-journal.md | 82 +++++ ai/tdc/guides/tdc-filesystem-vault.md | 141 ++++++++ ai/tdc/guides/tdc-filesystem.md | 301 ++++++++++++++++++ ai/tdc/guides/tdc-install-configure-update.md | 148 +++++++++ ai/tdc/guides/tdc-organization.md | 65 ++++ ai/tdc/guides/tdc-starter-database.md | 204 ++++++++++++ ai/tdc/reference/tdc-cli-reference.md | 158 +++++++++ .../tdc-configuration-and-credentials.md | 195 ++++++++++++ .../tdc-regions-security-and-limitations.md | 94 ++++++ ai/tdc/reference/tdc-troubleshooting.md | 190 +++++++++++ ai/tdc/tdc-overview.md | 72 +++++ ai/tdc/tdc-quick-start.md | 130 ++++++++ 23 files changed, 2759 insertions(+) create mode 100644 ai/tdc/concepts/tdc-concepts-and-architecture.md create mode 100644 ai/tdc/examples/tdc-agent-sandbox-example.md create mode 100644 ai/tdc/examples/tdc-daily-workflow-example.md create mode 100644 ai/tdc/examples/tdc-git-workspace-for-agents-example.md create mode 100644 ai/tdc/examples/tdc-journal-agent-workflow-example.md create mode 100644 ai/tdc/examples/tdc-query-sql-with-roles-example.md create mode 100644 ai/tdc/examples/tdc-share-filesystem-across-machines-example.md create mode 100644 ai/tdc/examples/tdc-vault-agent-secrets-example.md create mode 100644 ai/tdc/guides/tdc-filesystem-git.md create mode 100644 ai/tdc/guides/tdc-filesystem-journal.md create mode 100644 ai/tdc/guides/tdc-filesystem-vault.md create mode 100644 ai/tdc/guides/tdc-filesystem.md create mode 100644 ai/tdc/guides/tdc-install-configure-update.md create mode 100644 ai/tdc/guides/tdc-organization.md create mode 100644 ai/tdc/guides/tdc-starter-database.md create mode 100644 ai/tdc/reference/tdc-cli-reference.md create mode 100644 ai/tdc/reference/tdc-configuration-and-credentials.md create mode 100644 ai/tdc/reference/tdc-regions-security-and-limitations.md create mode 100644 ai/tdc/reference/tdc-troubleshooting.md create mode 100644 ai/tdc/tdc-overview.md create mode 100644 ai/tdc/tdc-quick-start.md diff --git a/TOC-ai.md b/TOC-ai.md index e79d9a34cc2be..cbf1494523e9f 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -7,10 +7,15 @@ - [Get Started via Python](/ai/quickstart-via-python.md) - [Get Started via SQL](/ai/quickstart-via-sql.md) +- TiDB Cloud CLI (tdc) (Preview) + - [Overview](/ai/tdc/tdc-overview.md) + - [Quick Start](/ai/tdc/tdc-quick-start.md) ## CONCEPTS - [Vector Search](/ai/concepts/vector-search-overview.md) +- TiDB Cloud CLI (tdc) (Preview) + - [Concepts and Architecture](/ai/tdc/concepts/tdc-concepts-and-architecture.md) ## GUIDES @@ -30,6 +35,14 @@ - [Join Queries](/ai/guides/join-queries.md) - [Raw SQL Queries](/ai/guides/raw-queries.md) - [Transactions](/ai/guides/transactions.md) +- TiDB Cloud CLI (tdc) (Preview) + - [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) + - [Organization](/ai/tdc/guides/tdc-organization.md) + - [Starter Database](/ai/tdc/guides/tdc-starter-database.md) + - [Filesystem](/ai/tdc/guides/tdc-filesystem.md) + - [Filesystem Git](/ai/tdc/guides/tdc-filesystem-git.md) + - [Filesystem Journal](/ai/tdc/guides/tdc-filesystem-journal.md) + - [Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) ## EXAMPLES @@ -44,6 +57,14 @@ - [RAG Application](/ai/examples/rag-with-pytidb.md) - [Conversational Memory](/ai/examples/memory-with-pytidb.md) - [Text-to-SQL](/ai/examples/text2sql-with-pytidb.md) +- TiDB Cloud CLI (tdc) (Preview) + - [Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) + - [Daily Workflow](/ai/tdc/examples/tdc-daily-workflow-example.md) + - [Query SQL with Roles](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) + - [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) + - [Git Workspace for Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) + - [Journal an Agent Workflow](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) + - [Delegate Vault Secrets](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) ## INTEGRATIONS @@ -84,3 +105,8 @@ - [Performance Tuning](/ai/reference/vector-search-improve-performance.md) - [Limitations](/ai/reference/vector-search-limitations.md) - [Changelogs](/ai/reference/vector-search-changelogs.md) +- TiDB Cloud CLI (tdc) (Preview) + - [CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) + - [Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) + - [Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) + - [Troubleshooting](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/_index.md b/ai/_index.md index bf8a92d7832e7..fbb035e71d94c 100644 --- a/ai/_index.md +++ b/ai/_index.md @@ -16,6 +16,13 @@ Get up and running quickly with TiDB's AI capabilities. | [Get Started with Python](/ai/quickstart-via-python.md) | Build your first AI application with TiDB in minutes using Python. | | [Get Started with SQL](/ai/quickstart-via-sql.md) | Quick start guide for vector search using SQL. | +### TiDB Cloud CLI (tdc) (Preview) + +| Document | Description | +| --- | --- | +| [tdc Overview](/ai/tdc/tdc-overview.md) | Understand what tdc manages and how it uses its bundled Filesystem companion. | +| [Get Started with tdc](/ai/tdc/tdc-quick-start.md) | Install and configure tdc, then complete a first database or Filesystem operation. | + ## Concepts Understand the foundational concepts behind AI-powered search in TiDB. @@ -23,6 +30,7 @@ Understand the foundational concepts behind AI-powered search in TiDB. | Document | Description | | --- | --- | | [Vector Search](/ai/concepts/vector-search-overview.md) | Comprehensive overview of vector search, including concepts, how it works, and use cases. | +| [tdc Concepts and Architecture (Preview)](/ai/tdc/concepts/tdc-concepts-and-architecture.md) | Understand profiles, regions, credentials, SQL roles, Filesystems, and the Drive9 companion boundary. | ## Guides @@ -39,6 +47,18 @@ Step-by-step guides for building AI applications with TiDB using the [`pytidb`]( | [Auto Embedding](/ai/guides/auto-embedding.md) | Automatically generate embeddings on data insertion. | | [Filtering](/ai/guides/filtering.md) | Filter search results with metadata conditions. | +### TiDB Cloud CLI (tdc) (Preview) + +| Document | Description | +| --- | --- | +| [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) | Install release binaries, configure profiles, update, and uninstall tdc. | +| [Organization](/ai/tdc/guides/tdc-organization.md) | List projects and understand virtual-project selection. | +| [Starter Database](/ai/tdc/guides/tdc-starter-database.md) | Manage clusters, branches, SQL users, connection strings, and SQL execution. | +| [Filesystem](/ai/tdc/guides/tdc-filesystem.md) | Manage resources, data, layers, packs, and FUSE or WebDAV mounts. | +| [Filesystem Git](/ai/tdc/guides/tdc-filesystem-git.md) | Clone, hydrate, and manage linked Git worktrees. | +| [Filesystem Journal](/ai/tdc/guides/tdc-filesystem-journal.md) | Record, search, and verify append-only workflow events. | +| [Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) | Store secrets, delegate access, audit, inject, and mount a read-only vault. | + ## Examples Complete code examples and demos showcasing TiDB's AI capabilities. @@ -52,6 +72,18 @@ Complete code examples and demos showcasing TiDB's AI capabilities. | [Conversational Memory](/ai/examples/memory-with-pytidb.md) | Persistent memory for AI agents and chatbots. | | [Text-to-SQL](/ai/examples/text2sql-with-pytidb.md) | Convert natural language to SQL queries. | +### TiDB Cloud CLI (tdc) (Preview) + +| Document | Description | +| --- | --- | +| [Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) | Give a clean sandbox Filesystem access without TiDB Cloud API keys. | +| [Daily Workflow](/ai/tdc/examples/tdc-daily-workflow-example.md) | Manage one Starter cluster and Filesystem in a routine operator flow. | +| [Query SQL with Roles](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) | Use explicit read-only, read-write, and admin SQL roles. | +| [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) | Transfer an owner token securely and verify cross-machine visibility. | +| [Git Workspace for Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) | Prepare a mounted Git workspace and isolated linked worktree. | +| [Journal an Agent Workflow](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) | Record structured events and verify their hash chain. | +| [Delegate Vault Secrets](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) | Grant an agent temporary access to one secret field. | + ## Integrations Integrate TiDB with popular AI frameworks, embedding providers, and development tools. @@ -75,3 +107,12 @@ Technical reference documentation for TiDB's AI and vector search features. | [Vector Search Index](/ai/reference/vector-search-index.md) | Create and manage vector indexes for performance. | | [Performance Tuning](/ai/reference/vector-search-improve-performance.md) | Optimize vector search performance. | | [Limitations](/ai/reference/vector-search-limitations.md) | Current limitations and constraints. | + +### TiDB Cloud CLI (tdc) (Preview) + +| Document | Description | +| --- | --- | +| [CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) | Global flags, output, queries, dry-run, help, errors, and aliases. | +| [Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) | Profiles, precedence, local state, credentials, mount locators, and logs. | +| [Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) | Placement, authentication boundaries, platforms, durability, and Preview constraints. | +| [Troubleshooting](/ai/tdc/reference/tdc-troubleshooting.md) | Diagnose authentication, quota, SQL, companion, selection, and mount failures. | diff --git a/ai/tdc/concepts/tdc-concepts-and-architecture.md b/ai/tdc/concepts/tdc-concepts-and-architecture.md new file mode 100644 index 0000000000000..eed0164f523e5 --- /dev/null +++ b/ai/tdc/concepts/tdc-concepts-and-architecture.md @@ -0,0 +1,129 @@ +--- +title: tdc Concepts and Architecture +summary: Understand tdc profiles, regions, credentials, SQL roles, Filesystem resources, local state, and the bundled Drive9 companion. +--- + +# tdc Concepts and Architecture + +This document explains the concepts needed to use tdc with TiDB Cloud Starter and TiDB Cloud Filesystem. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Command model + +tdc uses service nouns and explicit operation names: + +```text +tdc db create-db-cluster +tdc fs copy-file +tdc fs-git clone-git-workspace +``` + +The command tree is at most two levels. Long, descriptive command and flag names make intent explicit in logs and agent-generated commands. Commands are non-interactive except for `tdc configure`. + +Structured commands return JSON by default. Use `--output text` for a terminal-oriented representation and `--query` for a JMESPath projection. + +## Profiles and regions + +A profile is a named local namespace containing TiDB Cloud placement, a default virtual project, and credentials. The default profile is named `default`; select another with `--profile`. + +tdc represents placement with one canonical region code: + +```text +aws-us-east-1 +aws-ap-southeast-1 +ali-ap-southeast-1 +``` + +The prefix identifies the cloud provider. A global `--region` value overrides `TDC_REGION_CODE` and the profile region for one command without changing saved configuration. + +During `tdc configure`, tdc calls the organization API and requires one accessible project with `type = "tidbx_virtual"`. It stores that project ID as the default for Starter cluster creation. + +## Credential boundaries + +tdc uses separate credentials for separate security boundaries: + +| Credential | Purpose | Storage | +| --- | --- | --- | +| TiDB Cloud API public/private key | Organization, Starter control plane, Filesystem provisioning and deletion | `~/.tdc/credentials` | +| DB SQL username/password | SQL access to one Starter cluster | `~/.tdc/db_users//credentials` | +| Filesystem owner token | Filesystem data plane, mounts, Git, journal, and owner vault operations | Per-resource credentials under `~/.tdc/fs_resources/` or `TDC_FS_TOKEN` | +| Delegated vault token | Limited access to selected secret fields | `TDC_VAULT_TOKEN` or an explicit command input | + +TiDB Cloud API keys are never reused as SQL passwords or Filesystem tokens. + +## SQL roles + +`tdc db create-db-sql-users` creates or repairs three stable users for a cluster: + +- `read_only` for queries that must not modify data; +- `read_write` for normal application and agent work; +- `admin` for DDL and privilege administration. + +Role selection is explicit with `--read-only`, `--read-write`, or `--admin`. Read-write is the default when no role flag is supplied. + +## One profile, multiple Filesystems + +One profile can register multiple Filesystem resources. Each resource has an isolated config file and credential file. Select a resource in this order: + +1. `--file-system-name`; +2. `TDC_FS_FILE_SYSTEM_NAME`; +3. the profile's default Filesystem; +4. the only registered Filesystem, when exactly one exists. + +If multiple resources exist and none is selected, tdc fails instead of guessing. Use `tdc fs set-default-file-system` to choose a default. + +## Config-free sandbox access + +A clean agent sandbox does not need `tdc configure` or TiDB Cloud API keys to use an existing Filesystem. Supply: + +```bash +export TDC_FS_TOKEN="" +export TDC_REGION_CODE="aws-us-east-1" +export TDC_FS_FILE_SYSTEM_NAME="workspace" +``` + +tdc resolves these values into an in-memory profile namespace. It does not write an `[env]` profile or persist the token. + +## Local state + +All tdc-owned state is under `~/.tdc/`: + +| Path | Contents | +| --- | --- | +| `config` | Non-sensitive profile, default project, and logging settings | +| `credentials` | TiDB Cloud API keys | +| `fs_resources/` | Per-profile, per-Filesystem metadata and owner credentials | +| `db_users/` | Cluster-scoped SQL credentials | +| `mounts/` | Non-secret locators for active background mounts | +| `logs/tdc.jsonl` | Redacted local operation log | +| `bin/` | Installed `tdc` and `tdc-drive9` binaries | + +Operation logging is local and is not telemetry. Set `TDC_LOGGING=off` to disable it for one process. + +## tdc and the Drive9 companion + +tdc installs [Drive9](https://github.com/mem9-ai/drive9) as the private companion name `tdc-drive9`. + +tdc owns: + +- profile, credential, region, and Filesystem selection; +- TiDB Cloud control-plane calls; +- JSON/text output, queries, errors, and local logging; +- translation from the tdc command surface to the companion. + +The companion owns: + +- Filesystem reads, writes, metadata, links, search, and layers; +- FUSE and WebDAV mount processes, caches, drain, and unmount; +- pack/unpack, Git workspace, journal, and vault semantics. + +A background mount leaves a long-running `tdc-drive9 mount --foreground` process. `tdc fs drain-file-system` asks that process to flush pending FUSE work, and `tdc fs unmount-file-system` stops the mount. Do not terminate a machine with unflushed writes or local-only overlay data that you need to keep. + +## What's next + +- [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/examples/tdc-agent-sandbox-example.md b/ai/tdc/examples/tdc-agent-sandbox-example.md new file mode 100644 index 0000000000000..9c080242a49d3 --- /dev/null +++ b/ai/tdc/examples/tdc-agent-sandbox-example.md @@ -0,0 +1,106 @@ +--- +title: Use TiDB Cloud Filesystem in an Agent Sandbox +summary: Provision a Filesystem on a trusted machine and give a clean agent sandbox config-free access without TiDB Cloud API keys. +--- + +# Use TiDB Cloud Filesystem in an Agent Sandbox + +This example provisions a Filesystem on a trusted machine, transfers the minimum environment to a clean sandbox, and uses tdc without copying `~/.tdc/`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +- Install and configure tdc on a trusted machine. +- Install tdc in the sandbox. The release installer includes `tdc-drive9`. +- Use a secure secret manager or encrypted sandbox input for token transfer. + +## Step 1. Provision on the trusted machine + +```bash +export TDC_FS_TOKEN="$(tdc fs create-file-system \ + --file-system-name agent-sandbox \ + --query fs_token \ + --output text)" +``` + +Record the canonical region code used by the profile, for example `aws-us-east-1`. Do not print the token. + +## Step 2. Inject the minimum sandbox environment + +Configure the sandbox secret/environment mechanism with: + +```bash +TDC_FS_TOKEN= +TDC_REGION_CODE=aws-us-east-1 +TDC_FS_FILE_SYSTEM_NAME=agent-sandbox +``` + +The sandbox does not need `TDC_PUBLIC_KEY`, `TDC_PRIVATE_KEY`, `tdc configure`, or files copied from `~/.tdc/`. + +## Step 3. Verify direct access + +In the sandbox: + +```bash +printf 'sandbox ready\n' | tdc fs copy-file \ + --from-stdin \ + --to-remote /sandbox/status.txt + +tdc fs read-file --path /sandbox/status.txt +``` + +Expected output: + +```text +sandbox ready +``` + +## Step 4. Optionally mount the Filesystem + +On Linux with FUSE: + +```bash +mkdir -p /workspace +tdc fs mount-file-system \ + --file-system-name agent-sandbox \ + --mount-path /workspace \ + --driver fuse + +cat /workspace/sandbox/status.txt +``` + +On macOS, omit `--driver fuse` to use the default WebDAV path. Use FUSE only after installing macFUSE. + +After mounting, you can use `tdc fs-git`, `tdc fs-journal`, and owner-authorized `tdc fs-vault` commands with the same FS environment. Give agents a delegated `TDC_VAULT_TOKEN` instead of the owner token when they need only selected secret fields. + +## Cleanup + +Stop writers. For FUSE: + +```bash +tdc fs drain-file-system --mount-path /workspace +tdc fs unmount-file-system --mount-path /workspace +``` + +For WebDAV, close files and run only unmount. Back on the trusted machine: + +```bash +tdc fs delete-file-system \ + --file-system-name agent-sandbox \ + --confirm-file-system-name agent-sandbox +``` + +## Security notes + +- Treat `TDC_FS_TOKEN` as an owner credential. +- Do not place it in an image, repository, command flag, or operation log. +- Deleting the sandbox does not delete the remote Filesystem. +- Draining is required before deleting a FUSE sandbox when pending writes must be durable. + +## What's next + +- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/examples/tdc-daily-workflow-example.md b/ai/tdc/examples/tdc-daily-workflow-example.md new file mode 100644 index 0000000000000..655177738bbc6 --- /dev/null +++ b/ai/tdc/examples/tdc-daily-workflow-example.md @@ -0,0 +1,112 @@ +--- +title: Run a Daily tdc Workflow +summary: Inspect projects, manage a Starter cluster and Filesystem, check for tdc updates, and clean up resources. +--- + +# Run a Daily tdc Workflow + +This example follows a typical operator workflow across TiDB Cloud Starter and TiDB Cloud Filesystem. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +- Install tdc and run `tdc configure`. +- Ensure your organization has capacity for one Starter cluster and one Filesystem. + +## Step 1. Inspect the active account + +```bash +tdc organization list-projects --output text +tdc db list-db-clusters --output text +tdc fs list-file-systems --output text +``` + +## Step 2. Create a Starter cluster + +```bash +tdc db create-db-cluster \ + --db-cluster-name daily-demo \ + --db-cluster-type starter \ + --dry-run + +tdc db create-db-cluster \ + --db-cluster-name daily-demo \ + --db-cluster-type starter +``` + +Record the returned cluster ID and wait until the cluster is active: + +```bash +tdc db describe-db-cluster \ + --db-cluster-id "" \ + --output text +``` + +## Step 3. Verify SQL access + +```bash +tdc db create-db-sql-users --db-cluster-id "" +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --sql "SELECT CURRENT_TIMESTAMP AS checked_at" \ + --output text +``` + +## Step 4. Create and use a Filesystem + +```bash +tdc fs create-file-system \ + --file-system-name daily-workspace \ + --set-default + +printf 'daily workflow\n' | tdc fs copy-file \ + --from-stdin \ + --to-remote /notes/today.txt + +tdc fs list-files --path /notes --output text +``` + +The file in `/notes/today.txt` verifies that the selected default resource is usable. + +## Step 5. Check for updates + +Unmount active filesystems before applying an update. A check is always non-mutating: + +```bash +tdc update --check +``` + +Apply an update when appropriate: + +```bash +tdc update --dry-run +tdc update +``` + +## Cleanup + +```bash +tdc fs delete-file-system \ + --file-system-name daily-workspace \ + --confirm-file-system-name daily-workspace + +tdc db delete-db-cluster \ + --db-cluster-id "" +``` + +Deleting local tdc configuration is not a substitute for deleting remote resources. + +## Security notes + +- Do not echo FS tokens or formatted database connection strings. +- Use unique automation prefixes and delete only resources created by that run. +- Preview destructive operations with `--dry-run`. + +## What's next + +- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) +- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) diff --git a/ai/tdc/examples/tdc-git-workspace-for-agents-example.md b/ai/tdc/examples/tdc-git-workspace-for-agents-example.md new file mode 100644 index 0000000000000..4efb162eae68c --- /dev/null +++ b/ai/tdc/examples/tdc-git-workspace-for-agents-example.md @@ -0,0 +1,83 @@ +--- +title: Prepare a Git Workspace for Agents on TiDB Cloud Filesystem +summary: Mount a Filesystem, create a fast Git workspace and linked worktree, use Git normally, and clean up safely. +--- + +# Prepare a Git Workspace for Agents on TiDB Cloud Filesystem + +This example prepares a repository and an isolated linked worktree for an agent. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +- Select a Filesystem. +- Use Linux FUSE or macOS with macFUSE and explicit `--driver fuse`. +- Install Git and configure repository authentication. + +## Step 1. Mount a workspace + +```bash +mkdir -p /path/to/workspace +tdc fs mount-file-system \ + --mount-path /path/to/workspace \ + --driver fuse +``` + +## Step 2. Clone and hydrate + +```bash +tdc fs-git clone-git-workspace \ + --repo-url https://github.com/pingcap/tidb.git \ + --target-path /path/to/workspace/tidb \ + --blobless \ + --hydrate sync +``` + +Verify: + +```bash +git -C /path/to/workspace/tidb status +``` + +## Step 3. Create an agent worktree + +```bash +tdc fs-git add-git-worktree \ + --base-path /path/to/workspace/tidb \ + --worktree-path /path/to/workspace/tidb-agent-task \ + --branch-name agent-task +``` + +The agent can now use ordinary tools: + +```bash +git -C /path/to/workspace/tidb-agent-task status +``` + +Commit or push required changes before removing the worktree. + +## Cleanup + +```bash +tdc fs-git remove-git-worktree \ + --worktree-path /path/to/workspace/tidb-agent-task + +tdc fs drain-file-system --mount-path /path/to/workspace +tdc fs unmount-file-system --mount-path /path/to/workspace +``` + +Use `--force` for worktree removal only when uncommitted changes can be discarded. + +## Security and durability notes + +- Repository credentials are managed by Git, not tdc. +- The coding-agent profile keeps `.git` and ignored generated files locally for performance. +- Preserve or pack local overlay state before deleting an ephemeral machine when it cannot be rebuilt. + +## What's next + +- [Use Git Workspaces on TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem-git.md) +- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) diff --git a/ai/tdc/examples/tdc-journal-agent-workflow-example.md b/ai/tdc/examples/tdc-journal-agent-workflow-example.md new file mode 100644 index 0000000000000..788953e6085ca --- /dev/null +++ b/ai/tdc/examples/tdc-journal-agent-workflow-example.md @@ -0,0 +1,84 @@ +--- +title: Record an Agent Workflow in a Filesystem Journal +summary: Create a journal, append structured agent events, search the workflow, and verify the journal hash chain. +--- + +# Record an Agent Workflow in a Filesystem Journal + +This example records an agent task as structured, ordered events rather than appending unvalidated text to a mutable file. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +Select a Filesystem through a configured profile or FS token environment. + +## Step 1. Create the journal + +```bash +tdc fs-journal create-journal \ + --journal-id jrn-agent-demo \ + --journal-kind agent \ + --title "dependency update" \ + --actor agent:dependency-bot \ + --label repository=demo \ + --label environment=test +``` + +## Step 2. Append workflow events + +```bash +tdc fs-journal append-journal-entries \ + --journal-id jrn-agent-demo \ + --idempotency-key dependency-update-start \ + --entry-json '{"type":"task.started","status":"running"}' + +tdc fs-journal append-journal-entries \ + --journal-id jrn-agent-demo \ + --entry-json '{"type":"test.finished","status":"passed","suite":"unit"}' \ + --entry-json '{"type":"task.finished","status":"completed"}' +``` + +## Step 3. Read and search + +```bash +tdc fs-journal read-journal-entries \ + --journal-id jrn-agent-demo \ + --after-seq 0 \ + --limit 100 \ + --output text + +tdc fs-journal search-journal-entries \ + --entry-type task.finished \ + --status completed \ + --label repository=demo \ + --include-entries +``` + +The ordered result should include the start, test, and completion events. + +## Step 4. Verify integrity + +```bash +tdc fs-journal verify-journal \ + --journal-id jrn-agent-demo \ + --output text +``` + +A successful result confirms the stored sequence and hash chain are consistent. + +## Cleanup + +Journals are append-only and currently have no delete command in the tdc public surface. Use a synthetic journal ID and retain it as workflow evidence. Delete the containing Filesystem only when its complete contents are no longer needed. + +## Security notes + +- Do not put API keys, passwords, SQL text containing secrets, or raw file contents in journal payloads. +- Hash-chain verification detects stored-chain inconsistency; it does not prove the original event was truthful. + +## What's next + +- [Use TiDB Cloud Filesystem Journals](/ai/tdc/guides/tdc-filesystem-journal.md) +- [Delegate Secrets to an Agent](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) diff --git a/ai/tdc/examples/tdc-query-sql-with-roles-example.md b/ai/tdc/examples/tdc-query-sql-with-roles-example.md new file mode 100644 index 0000000000000..d9289fc297500 --- /dev/null +++ b/ai/tdc/examples/tdc-query-sql-with-roles-example.md @@ -0,0 +1,103 @@ +--- +title: Query TiDB Cloud Starter with Explicit SQL Roles +summary: Prepare tdc-managed SQL users and run read-only, read-write, and admin statements with clear privilege intent. +--- + +# Query TiDB Cloud Starter with Explicit SQL Roles + +This example uses all three tdc-managed SQL roles without exposing generated passwords. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +- Configure tdc. +- Select an active Starter cluster ID. + +## Step 1. Prepare users + +```bash +tdc db create-db-sql-users \ + --db-cluster-id "" +``` + +The command is idempotent and creates or repairs `read_only`, `read_write`, and `admin` credentials. + +## Step 2. Use admin for schema changes + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --admin \ + --sql "CREATE DATABASE IF NOT EXISTS role_demo" + +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --admin \ + --database role_demo \ + --sql "CREATE TABLE IF NOT EXISTS messages (id BIGINT PRIMARY KEY, body VARCHAR(255))" +``` + +## Step 3. Use read-write for data changes + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-write \ + --database role_demo \ + --sql "INSERT INTO messages(id, body) VALUES (1, 'hello') ON DUPLICATE KEY UPDATE body = VALUES(body)" +``` + +## Step 4. Use read-only for verification + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --database role_demo \ + --sql "SELECT id, body FROM messages ORDER BY id" \ + --output text +``` + +Expected result contains ID `1` and body `hello`. + +## Step 5. Format a connection environment + +Write the output directly to a protected local file instead of displaying it: + +```bash +umask 077 +tdc db format-db-connection-string \ + --db-cluster-id "" \ + --read-only \ + --database role_demo \ + --format env \ + --env-include-database-url > .env.tidb +``` + +Do not commit `.env.tidb`. + +## Cleanup + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --admin \ + --sql "DROP DATABASE role_demo" + +rm -f .env.tidb +``` + +## Security notes + +- Use the least privileged explicit role for each statement. +- tdc accepts one SQL statement per invocation. +- HTTPS is the default transport; `--transport mysql` is an explicit fallback. +- Connection strings and environment output contain credentials. + +## What's next + +- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md new file mode 100644 index 0000000000000..32b6d301f67bf --- /dev/null +++ b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md @@ -0,0 +1,100 @@ +--- +title: Share a TiDB Cloud Filesystem Across Machines +summary: Create one Filesystem, securely access it from a second machine, and verify data-plane and mount visibility. +--- + +# Share a TiDB Cloud Filesystem Across Machines + +This example creates a Filesystem on machine A and accesses the same data from machine B without copying a tdc profile. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +- Machine A has configured tdc. +- Both machines have tdc installed. +- You have a secure secret-transfer channel. + +## Step 1. Create the Filesystem on machine A + +```bash +export TDC_FS_TOKEN="$(tdc fs create-file-system \ + --file-system-name shared-workspace \ + --query fs_token \ + --output text)" + +printf 'from machine A\n' | tdc fs copy-file \ + --file-system-name shared-workspace \ + --from-stdin \ + --to-remote /shared/origin.txt +``` + +Transfer the token through a secret manager. Also communicate the canonical region code and Filesystem name. + +## Step 2. Configure machine B in memory + +```bash +export TDC_FS_TOKEN="" +export TDC_REGION_CODE="aws-us-east-1" +export TDC_FS_FILE_SYSTEM_NAME="shared-workspace" +``` + +No `tdc configure` is required. + +## Step 3. Verify direct visibility on machine B + +```bash +tdc fs read-file --path /shared/origin.txt +printf 'from machine B\n' | tdc fs copy-file --from-stdin --to-remote /shared/second.txt +``` + +## Step 4. Verify mount and data-plane visibility + +```bash +mkdir -p /path/to/shared-workspace +tdc fs mount-file-system \ + --file-system-name shared-workspace \ + --mount-path /path/to/shared-workspace + +cat /path/to/shared-workspace/shared/origin.txt +printf 'written through mount\n' > /path/to/shared-workspace/shared/mounted.txt +tdc fs read-file --path /shared/mounted.txt +``` + +The first read proves data-plane writes are visible through the mount. The final read proves mount writes are visible through the data plane after they are flushed. + +## Cleanup + +Stop writers. If the mount is FUSE: + +```bash +tdc fs drain-file-system --mount-path /path/to/shared-workspace +``` + +Unmount either driver: + +```bash +tdc fs unmount-file-system --mount-path /path/to/shared-workspace +unset TDC_FS_TOKEN TDC_REGION_CODE TDC_FS_FILE_SYSTEM_NAME +``` + +On machine A: + +```bash +tdc fs delete-file-system \ + --file-system-name shared-workspace \ + --confirm-file-system-name shared-workspace +``` + +## Security notes + +- The FS token grants owner access. Transfer it as a secret, not in chat or command history. +- Concurrent writers can overwrite the same paths; coordinate ownership at the workflow level. +- Do not terminate a machine before pending FUSE writes are drained. + +## What's next + +- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) +- [Use a Filesystem in an Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) diff --git a/ai/tdc/examples/tdc-vault-agent-secrets-example.md b/ai/tdc/examples/tdc-vault-agent-secrets-example.md new file mode 100644 index 0000000000000..99bf88c5ab705 --- /dev/null +++ b/ai/tdc/examples/tdc-vault-agent-secrets-example.md @@ -0,0 +1,97 @@ +--- +title: Delegate Filesystem Vault Secrets to an Agent +summary: Store a secret, grant one field to an agent, inject it into a process, audit access, and revoke the grant. +--- + +# Delegate Filesystem Vault Secrets to an Agent + +This example gives an agent temporary access to one field without sharing the Filesystem owner token. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +- Select a Filesystem with owner access. +- Store the source secret value in a protected file. + +## Step 1. Create a secret + +```bash +tdc fs-vault create-secret \ + --secret-name service-demo \ + --field ENDPOINT=https://service.example \ + --field API_TOKEN=@./api-token.txt +``` + +## Step 2. Create a narrow grant + +```bash +export TDC_VAULT_TOKEN="$(tdc fs-vault create-grant \ + --agent-id example-agent \ + --scope service-demo/ENDPOINT \ + --permission read \ + --ttl 10m \ + --label-hint example \ + --token-only)" +``` + +Record the returned grant ID from the structured create result in a real workflow. The token is captured and not printed. + +## Step 3. Use the delegated field + +```bash +tdc fs-vault read-secret \ + --secret-name service-demo \ + --field ENDPOINT \ + --format raw +``` + +Inject the allowed fields into a command: + +```bash +tdc fs-vault run-with-secret \ + --secret-path /n/vault/service-demo \ + -- sh -c 'test -n "$ENDPOINT"' +``` + +The process exits successfully when the permitted field is present. Do not use commands that print all environment values. + +## Step 4. Audit and revoke + +```bash +tdc fs-vault list-audit-events \ + --secret-name service-demo \ + --agent-id example-agent \ + --limit 20 + +tdc fs-vault delete-grant \ + --grant-id "" \ + --revoked-by operator \ + --reason task-complete +``` + +Unset the local token: + +```bash +unset TDC_VAULT_TOKEN +``` + +## Cleanup + +```bash +tdc fs-vault delete-secret --secret-name service-demo +rm -f ./api-token.txt +``` + +## Security notes + +- Scope grants to the smallest set of fields and shortest useful TTL. +- A revoked token cannot authorize new reads, but it cannot erase a value already read by a process. +- Avoid secret flags because process listings and shell history can retain them. + +## What's next + +- [Use TiDB Cloud Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) +- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/guides/tdc-filesystem-git.md b/ai/tdc/guides/tdc-filesystem-git.md new file mode 100644 index 0000000000000..05d41eec7eebc --- /dev/null +++ b/ai/tdc/guides/tdc-filesystem-git.md @@ -0,0 +1,98 @@ +--- +title: Use Git Workspaces on TiDB Cloud Filesystem +summary: Clone, hydrate, and manage linked Git worktrees in a mounted TiDB Cloud Filesystem workspace. +--- + +# Use Git Workspaces on TiDB Cloud Filesystem + +`tdc fs-git` accelerates Git workspace setup on mounted TiDB Cloud Filesystem paths. It augments Git; you continue to use ordinary `git` commands for status, edit, add, commit, fetch, and push. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +- Mount a Filesystem through FUSE. Git workspace acceleration relies on the mounted Filesystem runtime. +- Install `git` and configure any repository credentials independently. +- Ensure the FS owner token or selected profile can access the Filesystem. + +## Clone a workspace + +```bash +tdc fs-git clone-git-workspace \ + --repo-url https://github.com/pingcap/tidb.git \ + --target-path /path/to/workspace/tidb +``` + +For a large repository, create a blobless workspace and hydrate synchronously: + +```bash +tdc fs-git clone-git-workspace \ + --repo-url https://github.com/pingcap/tidb.git \ + --target-path /path/to/workspace/tidb \ + --blobless \ + --hydrate sync +``` + +`--hydrate` accepts `auto`, `background`, `sync`, or `off`. + +## Hydrate an existing workspace + +```bash +tdc fs-git hydrate-git-workspace \ + --target-path /path/to/workspace/tidb \ + --timeout 30m +``` + +Hydration materializes clean Git objects for a fast or blobless workspace. It does not discard working-tree changes. + +## Add a linked worktree + +```bash +tdc fs-git add-git-worktree \ + --base-path /path/to/workspace/tidb \ + --worktree-path /path/to/workspace/tidb-feature \ + --branch-name feature-x +``` + +Use `--detach` for a detached worktree, `--commit-ish` to select a starting revision, and `--blobless` with `--hydrate` when the base workspace uses the blobless mode. + +Use Git normally: + +```bash +git -C /path/to/workspace/tidb-feature status +git -C /path/to/workspace/tidb-feature add . +git -C /path/to/workspace/tidb-feature commit -m "Implement feature x" +``` + +## Remove a worktree + +```bash +tdc fs-git remove-git-worktree \ + --worktree-path /path/to/workspace/tidb-feature +``` + +The command refuses a dirty worktree by default. Use `--force` only after deciding that local changes can be discarded: + +```bash +tdc fs-git remove-git-worktree \ + --worktree-path /path/to/workspace/tidb-feature \ + --force +``` + +## Lifecycle guidance + +Before terminating an ephemeral machine: + +1. Commit or otherwise preserve required working-tree changes. +2. Remove linked worktrees you no longer need. +3. Drain the Filesystem mount. +4. Unmount it. + +The default coding-agent mount profile keeps `.git` and rebuildable generated files in local overlay storage. Preserve or pack that local state when it must survive machine deletion. + +## What's next + +- [Prepare a Git Workspace for Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) +- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) diff --git a/ai/tdc/guides/tdc-filesystem-journal.md b/ai/tdc/guides/tdc-filesystem-journal.md new file mode 100644 index 0000000000000..3eb31a3053dd1 --- /dev/null +++ b/ai/tdc/guides/tdc-filesystem-journal.md @@ -0,0 +1,82 @@ +--- +title: Use TiDB Cloud Filesystem Journals +summary: Create append-only workflow journals, append and search structured events, and verify their hash chains. +--- + +# Use TiDB Cloud Filesystem Journals + +`tdc fs-journal` provides an append-only, verifiable ledger for agent and workflow events. Unlike a mutable text file, a journal assigns ordered sequence numbers, supports structured search, and maintains a hash chain that can detect alteration. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +Select a Filesystem through a profile or provide `TDC_FS_TOKEN`, `TDC_REGION_CODE`, and `TDC_FS_FILE_SYSTEM_NAME`. + +## Create a journal + +```bash +tdc fs-journal create-journal \ + --journal-id jrn-demo \ + --journal-kind agent \ + --title "demo task" \ + --actor agent:tdc \ + --label env=dev +``` + +`--journal-id` is optional and generated when omitted. Labels are repeatable. + +## Append entries + +Append one or more JSON objects: + +```bash +tdc fs-journal append-journal-entries \ + --journal-id jrn-demo \ + --entry-json '{"type":"task.started","status":"running"}' \ + --entry-json '{"type":"tool.called","tool":"tdc"}' +``` + +Use `--entry-type` as a default for entries without `type`, and add `--source` or repeatable `--subject` metadata. `--idempotency-key` makes a retry deterministic; tdc generates one when omitted. + +For pipelines, send JSON Lines on stdin, or use `--json-array` for a JSON array. + +## Read and search + +Read entries after a sequence: + +```bash +tdc fs-journal read-journal-entries \ + --journal-id jrn-demo \ + --after-seq 0 \ + --limit 100 +``` + +Search across journals: + +```bash +tdc fs-journal search-journal-entries \ + --entry-type task.started \ + --journal-kind agent \ + --label env=dev \ + --include-entries +``` + +Search also supports status, actor, subject, `--since`, `--until`, `--limit`, and pagination cursor filters. + +## Verify integrity + +```bash +tdc fs-journal verify-journal \ + --journal-id jrn-demo \ + --output text +``` + +Verification recalculates the ordered hash chain and reports whether the entries are internally consistent. It does not assert that the event payload was truthful when originally appended. + +## What's next + +- [Record an Agent Workflow in a Journal](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/guides/tdc-filesystem-vault.md b/ai/tdc/guides/tdc-filesystem-vault.md new file mode 100644 index 0000000000000..293407d189509 --- /dev/null +++ b/ai/tdc/guides/tdc-filesystem-vault.md @@ -0,0 +1,141 @@ +--- +title: Use TiDB Cloud Filesystem Vault +summary: Store Filesystem secrets, delegate limited access, inject secrets into processes, audit access, and mount a read-only vault. +--- + +# Use TiDB Cloud Filesystem Vault + +`tdc fs-vault` stores structured secrets and delegates limited, expiring access to agents. Owner operations use the Filesystem owner credential; delegated reads use a vault token scoped to selected secrets or fields. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +Select a Filesystem through a profile or the config-free FS environment variables. Never print, log, or commit owner or delegated tokens. + +## Create and replace secrets + +Create a secret with repeatable fields: + +```bash +tdc fs-vault create-secret \ + --secret-name db-prod \ + --field DB_URL=mysql://example \ + --field PASSWORD=@./password.txt +``` + +`key=value` uses a literal value, `key=@file` reads a file, and `key=-` reads the value from stdin. + +Replace all fields with files from a directory: + +```bash +tdc fs-vault replace-secret \ + --secret-path /n/vault/db-prod \ + --from-directory ./secret-fields +``` + +## Read, list, and delete + +```bash +tdc fs-vault list-secrets +tdc fs-vault read-secret --secret-name db-prod +tdc fs-vault read-secret --secret-name db-prod --field DB_URL --format raw +tdc fs-vault read-secret --secret-name db-prod --field DB_URL --format env +``` + +Delete an owner-visible secret: + +```bash +tdc fs-vault delete-secret --secret-name db-prod +``` + +Raw and environment output contains plaintext. Direct it only to the intended process. + +## Delegate limited access + +Create a short-lived read grant and capture its token: + +```bash +export TDC_VAULT_TOKEN="$(tdc fs-vault create-grant \ + --agent-id deploy-agent \ + --scope db-prod/DB_URL \ + --permission read \ + --ttl 10m \ + --token-only)" +``` + +Scopes are repeatable. `--label-hint` can add non-secret operator context. + +Use the delegated token: + +```bash +tdc fs-vault read-secret \ + --secret-name db-prod \ + --field DB_URL \ + --format raw +``` + +`TDC_VAULT_TOKEN` is preferred over `--vault-token` because command-line values can remain in process listings or shell history. + +## Inject a secret into a process + +```bash +tdc fs-vault run-with-secret \ + --secret-path /n/vault/db-prod \ + -- env +``` + +The child receives secret fields as environment variables. Avoid commands that print the complete environment in production; `env` is shown only to demonstrate the interface. + +## Audit and revoke + +```bash +tdc fs-vault list-audit-events \ + --secret-name db-prod \ + --agent-id deploy-agent \ + --since 24h \ + --limit 20 + +tdc fs-vault delete-grant \ + --grant-id "" \ + --revoked-by operator \ + --reason rotated +``` + +Revocation prevents new authorized operations. It cannot erase secret values a process already read. + +## Mount a read-only vault + +On macOS or Linux with FUSE support: + +```bash +mkdir -p /path/to/vault +tdc fs-vault mount-vault \ + --mount-path /path/to/vault \ + --vault-token "$TDC_VAULT_TOKEN" +``` + +The mount is read-only. `--foreground` keeps it attached to the terminal, and `--ready-timeout` changes the background readiness wait. + +Unmount: + +```bash +tdc fs-vault unmount-vault --mount-path /path/to/vault +``` + +Unmount also supports `--timeout`, `--force`, and `--ignore-absent`. Vault mount is unavailable on Windows and requires FUSE support; direct `read-secret` and `run-with-secret` do not require a mount. + +## Security guidance + +- Give an agent the narrowest field scope and shortest practical TTL. +- Prefer `run-with-secret` over writing plaintext to disk. +- Do not store delegated tokens in tdc config or operation logs. +- Stop processes using a vault mount before unmounting. +- Revoke a grant after the task finishes. + +## What's next + +- [Delegate Secrets to an Agent](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) +- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/guides/tdc-filesystem.md b/ai/tdc/guides/tdc-filesystem.md new file mode 100644 index 0000000000000..2a3ba4f1dd252 --- /dev/null +++ b/ai/tdc/guides/tdc-filesystem.md @@ -0,0 +1,301 @@ +--- +title: Manage TiDB Cloud Filesystem with tdc +summary: Manage Filesystem resources, operate on files, use layers and packs, and mount Filesystems through the bundled Drive9 companion. +--- + +# Manage TiDB Cloud Filesystem with tdc + +Use `tdc fs` to provision TiDB Cloud Filesystem resources and access their data from commands or local mounts. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +- Run `tdc configure` before provisioning or deleting a Filesystem. +- Install tdc with the release installer so the `tdc-drive9` companion is next to the `tdc` binary. +- Treat the returned FS owner token as a secret. + +Data-plane commands can instead use an existing Filesystem with `TDC_FS_TOKEN`, `TDC_REGION_CODE`, and `TDC_FS_FILE_SYSTEM_NAME`, without TiDB Cloud API keys. + +## Manage Filesystem resources + +Create a resource and make it the profile default: + +```bash +tdc fs create-file-system \ + --file-system-name workspace \ + --set-default +``` + +The JSON response includes `fs_token`. Capture it without displaying the complete result: + +```bash +export TDC_FS_TOKEN="$(tdc fs create-file-system \ + --file-system-name sandbox \ + --query fs_token \ + --output text)" +``` + +List and describe locally registered resources: + +```bash +tdc fs list-file-systems +tdc fs describe-file-system --file-system-name workspace +``` + +Set or clear a profile default: + +```bash +tdc fs set-default-file-system --file-system-name workspace +tdc fs unset-default-file-system +``` + +Check the selected resource and companion: + +```bash +tdc fs check-file-system --file-system-name workspace +``` + +Delete a resource only after removing data you need: + +```bash +tdc fs delete-file-system \ + --file-system-name workspace \ + --confirm-file-system-name workspace +``` + +Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and a locally registered resource; an FS token alone cannot delete the resource. + +## Select one of multiple Filesystems + +One profile can own multiple resources. Selection precedence is: + +1. `--file-system-name`; +2. `TDC_FS_FILE_SYSTEM_NAME`; +3. the profile default; +4. the only registered resource. + +When selection is ambiguous, tdc fails. It never chooses an arbitrary Filesystem. + +## Copy and read data + +Upload, download, and copy remotely: + +```bash +tdc fs copy-file --from-local ./README.md --to-remote /workspace/README.md +tdc fs copy-file --from-remote /workspace/README.md --to-local ./README.copy.md --create-parents +tdc fs copy-file --from-remote /workspace/README.md --to-remote /archive/README.md +``` + +Use `--overwrite` to replace an existing target, `--resume` for a supported interrupted upload or download, and `--recursive` for directories: + +```bash +tdc fs copy-file --from-local ./src --to-remote /workspace/src --recursive +tdc fs copy-file --from-local ./large.bin --to-remote /workspace/large.bin --resume +``` + +Append and stream: + +```bash +tdc fs copy-file --from-local ./tail.log --to-remote /logs/app.log --append +printf 'hello\n' | tdc fs copy-file --from-stdin --to-remote /workspace/stdin.txt +tdc fs copy-file --from-remote /workspace/stdin.txt --to-stdout +``` + +Add metadata during upload: + +```bash +tdc fs copy-file \ + --from-local ./report.md \ + --to-remote /workspace/report.md \ + --tag owner=agent \ + --tag stage=review \ + --description "agent review report" +``` + +Read a complete file or a byte range: + +```bash +tdc fs read-file --path /workspace/report.md +tdc fs read-file --path /workspace/large.bin --offset 1024 --length 4096 +``` + +## Inspect and modify the namespace + +```bash +tdc fs list-files --path /workspace +tdc fs describe-file --path /workspace/report.md +tdc fs create-directory --path /workspace/archive --mode 0755 +tdc fs move-file --from-remote /workspace/report.md --to-remote /workspace/archive/report.md +tdc fs chmod-file --path /workspace/archive/report.md --mode 0600 +tdc fs create-symlink --target archive/report.md --link-path /workspace/report.link +tdc fs create-hardlink --source-path /workspace/archive/report.md --link-path /workspace/report.hard +tdc fs delete-file --path /workspace/report.link +tdc fs delete-file --path /workspace/archive --recursive +``` + +Mutating namespace commands support `--dry-run`. + +Search content and metadata: + +```bash +tdc fs search-file-content --path /workspace --pattern "TODO" --limit 50 +tdc fs find-files --path /workspace --file-name-pattern "*.md" --tag stage=review +``` + +`find-files` also supports resource type, time, size, and result-limit filters. Both search commands accept `--layer-id`. + +## Use layers and checkpoints + +A layer records changes over a base root before you commit or discard them: + +```bash +tdc fs create-layer \ + --base-root-path /workspace \ + --layer-name agent-task \ + --durability-mode restore-safe \ + --tag task=review +``` + +Use the returned layer ID: + +```bash +tdc fs copy-file \ + --from-local ./proposal.md \ + --to-remote /workspace/proposal.md \ + --layer-id "" + +tdc fs list-layers +tdc fs describe-layer --layer-id "" +tdc fs diff-layer --layer-id "" +tdc fs create-layer-checkpoint \ + --layer-id "" \ + --checkpoint-id before-review \ + --label "before review" +``` + +Finish the layer by rolling it back or committing it: + +```bash +tdc fs rollback-layer --layer-id "" +tdc fs commit-layer --layer-id "" +``` + +These two commands represent alternative outcomes for the same work; do not run both in sequence in a real workflow. + +## Pack local overlay state + +FUSE mount profiles can route selected paths to local overlay storage. Pack those paths to a remote archive before moving to another machine: + +```bash +tdc fs pack-file-system --mount-path /path/to/workspace +tdc fs unpack-file-system --mount-path /path/to/workspace +``` + +Without an active mount, provide `--local-root`, `--remote-root`, and `--mount-profile`. `--archive-path` selects the remote archive, repeatable `--path` limits pack contents, and `--no-replace` makes unpack merge rather than replace manifest paths. + +## Mount a Filesystem + +Create the local mount path and mount in the background: + +```bash +mkdir -p /path/to/workspace +tdc fs mount-file-system \ + --file-system-name workspace \ + --mount-path /path/to/workspace +``` + +The default `--driver auto` is platform-specific. `--remote-path` exposes a subtree, `--read-only` prevents writes, and `--foreground` keeps the runtime attached to the terminal. + +### Platform behavior + +| Platform | `--driver auto` | Optional or required dependency | Notes | +| --- | --- | --- | --- | +| macOS | WebDAV | No extra dependency for WebDAV | Install macFUSE and select `--driver fuse` for the complete FUSE experience | +| Linux | FUSE | FUSE3 and access to `/dev/fuse`; install `davfs2` for explicit WebDAV | FUSE supports drain and FUSE cache controls | +| Windows | WebDAV | Windows WebClient service | Mount path must be a drive letter such as `X:`; FUSE and vault mount are unavailable | + +macOS intentionally keeps WebDAV as the automatic choice even when macFUSE is installed. To use FUSE, install a supported release from the [official macFUSE site](https://macfuse.github.io/), complete any approval or restart requested by its installer, and run: + +```bash +tdc fs mount-file-system \ + --file-system-name workspace \ + --mount-path /path/to/workspace \ + --driver fuse +``` + +Explicit FUSE supports cache controls: + +```bash +tdc fs mount-file-system \ + --file-system-name workspace \ + --mount-path /path/to/workspace \ + --driver fuse \ + --cache-dir "$HOME/.tdc/cache/workspace" \ + --read-cache-size-mb 256 \ + --read-cache-max-file-mb 16 \ + --read-cache-ttl 30s +``` + +The default mount profile is `coding-agent`, which keeps common development state such as dependencies, caches, generated output, and Git internals in a local overlay. Those local-only files do not survive machine deletion unless you pack or preserve the local volume. Use `--mount-profile portable` when you want automatic portable pack behavior, or `none` when you do not want the coding-agent overlay policy. + +## Drain and unmount + +Stop writers and close open files before cleanup. For FUSE: + +```bash +tdc fs drain-file-system \ + --mount-path /path/to/workspace \ + --timeout 30s + +tdc fs unmount-file-system \ + --mount-path /path/to/workspace +``` + +Drain waits for dirty handles and pending writes. It is not supported for WebDAV. `unmount-file-system` also supports `--timeout`, `--force`, `--ignore-absent`, `--pack-archive-path`, and `--no-auto-pack`. + +A successful background mount writes a non-secret locator under `~/.tdc/mounts/`. Drain and unmount can use that locator from the same `HOME` without `TDC_FS_TOKEN` or `TDC_REGION_CODE`. + +> **Warning:** +> +> Do not terminate a sandbox or virtual machine while writes remain pending. Remote-committed data survives, but in-memory writes, write-back data on a deleted local disk, and coding-agent local-only files can be lost. + +## Unix-style aliases + +Aliases change only the command name. All flags remain long and identical to the canonical command. + +| Alias | Canonical command | +| --- | --- | +| `tdc fs cp` | `tdc fs copy-file` | +| `tdc fs cat` | `tdc fs read-file` | +| `tdc fs ls` | `tdc fs list-files` | +| `tdc fs stat` | `tdc fs describe-file` | +| `tdc fs mv` | `tdc fs move-file` | +| `tdc fs rm` | `tdc fs delete-file` | +| `tdc fs mkdir` | `tdc fs create-directory` | +| `tdc fs chmod` | `tdc fs chmod-file` | +| `tdc fs symlink` | `tdc fs create-symlink` | +| `tdc fs hardlink` | `tdc fs create-hardlink` | +| `tdc fs grep` | `tdc fs search-file-content` | +| `tdc fs find` | `tdc fs find-files` | +| `tdc fs mount` | `tdc fs mount-file-system` | +| `tdc fs drain` | `tdc fs drain-file-system` | +| `tdc fs umount` | `tdc fs unmount-file-system` | + +## Command summary + +| Area | Commands | +| --- | --- | +| Resources | `create-file-system`, `list-file-systems`, `describe-file-system`, `set-default-file-system`, `unset-default-file-system`, `check-file-system`, `delete-file-system` | +| Data | `copy-file`, `read-file`, `list-files`, `describe-file`, `move-file`, `delete-file`, `create-directory`, `chmod-file`, `create-symlink`, `create-hardlink`, `search-file-content`, `find-files` | +| Layers | `create-layer`, `list-layers`, `describe-layer`, `diff-layer`, `create-layer-checkpoint`, `rollback-layer`, `commit-layer` | +| Portability | `pack-file-system`, `unpack-file-system` | +| Mounts | `mount-file-system`, `drain-file-system`, `unmount-file-system` | + +## What's next + +- [Use a Filesystem in an Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) +- [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) +- [Use Git Workspaces on TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem-git.md) diff --git a/ai/tdc/guides/tdc-install-configure-update.md b/ai/tdc/guides/tdc-install-configure-update.md new file mode 100644 index 0000000000000..c0b2166b824ff --- /dev/null +++ b/ai/tdc/guides/tdc-install-configure-update.md @@ -0,0 +1,148 @@ +--- +title: Install, Configure, and Update tdc +summary: Install tdc release binaries, configure profiles interactively or in automation, update safely, and remove the CLI. +--- + +# Install, Configure, and Update tdc + +This guide covers the supported release installers, profile configuration, help and version behavior, updates, and uninstallation. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Install tdc + +### macOS and Linux + +```bash +curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes +export PATH="$HOME/.tdc/bin:$PATH" +tdc --version +``` + +The installer places `tdc` and its `tdc-drive9` companion in `~/.tdc/bin`. Add the `PATH` export to your shell profile. The installer does not require `sudo` and does not write credentials. + +### Windows + +```powershell +$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 +$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. + +## Configure a profile + +Interactive configuration is the only tdc workflow that prompts: + +```bash +tdc configure +``` + +tdc requests a TiDB Cloud API public key, private key, and canonical region code. It validates the key by listing projects and records the unique `tidbx_virtual` project as the profile's default project. + +Configure a named profile: + +```bash +tdc configure --profile staging +``` + +For CI or another non-interactive environment, prefer environment variables: + +```bash +TDC_PUBLIC_KEY="" \ +TDC_PRIVATE_KEY="" \ +TDC_REGION_CODE="aws-us-east-1" \ +tdc configure --profile ci --non-interactive +``` + +You can also provide `--tdc-public-key`, `--tdc-private-key`, and `--region-code`, but secret flags can remain in shell history or process listings. + +Configuration precedence is command flag, environment variable, then saved profile. The global `--region` overrides only the placement for the current command: + +```bash +tdc db list-db-clusters --profile staging --region aws-us-west-2 +``` + +## Get help and version information + +All command levels support `help`, `--help`, and `--version`: + +```bash +tdc help +tdc fs help +tdc db create-db-cluster help +tdc --version +tdc fs --version +``` + +Required flags appear before optional flags in generated usage. tdc supports long flags only. + +## Update tdc + +Check without changing files: + +```bash +tdc update --check +``` + +In automation, fail when an update exists: + +```bash +tdc update --check --fail-if-update-available +``` + +Preview and apply an update: + +```bash +tdc update --dry-run +tdc update +``` + +Install a specific tdc release: + +```bash +tdc update --target-version v0.1.2 +``` + +The update command replaces both binaries in the user-owned install directory. An active Filesystem mount keeps running the already loaded companion process. To avoid mixing the old mount runtime with new CLI commands, stop writers, drain FUSE mounts, and unmount before updating: + +```bash +tdc fs drain-file-system --mount-path /path/to/workspace +tdc fs unmount-file-system --mount-path /path/to/workspace +tdc update +``` + +For WebDAV, close writers and unmount; drain is FUSE-only. Installations in protected or package-manager-owned locations are not modified. Run the installer once to migrate an older `/usr/local/bin` installation to `~/.tdc/bin`. + +## Uninstall tdc + +Remove only the binaries: + +```bash +rm -f "$HOME/.tdc/bin/tdc" "$HOME/.tdc/bin/tdc-drive9" +``` + +On Windows: + +```powershell +Remove-Item "$HOME\.tdc\bin\tdc.exe", "$HOME\.tdc\bin\tdc-drive9.exe" +``` + +Removing binaries preserves profiles, credentials, Filesystem registrations, DB SQL credentials, logs, and mount locators. Remove `~/.tdc/` only when you intend to delete all local tdc state: + +```bash +rm -rf "$HOME/.tdc" +``` + +Deleting local state does not delete remote Starter clusters or Filesystem resources. + +## What's next + +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) +- [Manage TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem.md) diff --git a/ai/tdc/guides/tdc-organization.md b/ai/tdc/guides/tdc-organization.md new file mode 100644 index 0000000000000..fc0a923afd974 --- /dev/null +++ b/ai/tdc/guides/tdc-organization.md @@ -0,0 +1,65 @@ +--- +title: Manage TiDB Cloud Organizations with tdc +summary: List accessible TiDB Cloud projects and understand regular and virtual project types used by tdc. +--- + +# Manage TiDB Cloud Organizations with tdc + +Use `tdc organization` to inspect the projects accessible to the configured TiDB Cloud API key. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +Run `tdc configure` with a TiDB Cloud API key that can list organization projects. + +## List projects + +```bash +tdc organization list-projects +``` + +The JSON response includes project IDs, names, and `type` values: + +- `tidbx` identifies a regular project; +- `tidbx_virtual` identifies a virtual project used as the default Starter project. + +Request a page size or continue with a returned page token: + +```bash +tdc organization list-projects --page-size 50 +tdc organization list-projects --page-size 50 --page-token "" +``` + +Render a terminal-oriented table or select fields: + +```bash +tdc organization list-projects --output text +tdc organization list-projects --query 'projects[].{id:id,name:name,type:type}' +``` + +## Default virtual project + +`tdc configure` calls the same project-listing API. Configuration succeeds only when it finds exactly one accessible `tidbx_virtual` project, and saves its ID in the selected profile: + +```toml +[default] +region_code = "aws-us-east-1" +project_id = "..." +``` + +`tdc db create-db-cluster` uses this project when `--project-id` is omitted. Pass an explicit project ID to override it for one cluster: + +```bash +tdc db create-db-cluster \ + --db-cluster-name project-specific-cluster \ + --db-cluster-type starter \ + --project-id "" +``` + +## What's next + +- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/guides/tdc-starter-database.md b/ai/tdc/guides/tdc-starter-database.md new file mode 100644 index 0000000000000..9fd2eb2d8291c --- /dev/null +++ b/ai/tdc/guides/tdc-starter-database.md @@ -0,0 +1,204 @@ +--- +title: Manage TiDB Cloud Starter Databases with tdc +summary: Manage Starter clusters and branches, create SQL users, format connection strings, and execute SQL with explicit roles. +--- + +# Manage TiDB Cloud Starter Databases with tdc + +Use `tdc db` to manage TiDB Cloud Starter clusters, branches, and SQL access. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +- Configure tdc with `tdc configure`. +- Ensure the API key can manage Starter clusters in the selected project. +- Use synthetic names in automation so cleanup can identify only resources created by that run. + +## Manage clusters + +Preview and create a Starter cluster: + +```bash +tdc db create-db-cluster \ + --db-cluster-name demo-cluster \ + --db-cluster-type starter \ + --dry-run + +tdc db create-db-cluster \ + --db-cluster-name demo-cluster \ + --db-cluster-type starter +``` + +The configured virtual project is used unless you provide `--project-id`. `--monthly-spending-limit-usd-cents` is optional; setting it can require a payment method. + +List and filter clusters: + +```bash +tdc db list-db-clusters +tdc db list-db-clusters --page-size 20 --order-by "createTime desc" +tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name,state:state}' +``` + +The list command also accepts `--page-token`, `--filter`, and `--skip`. + +Describe and update a cluster: + +```bash +tdc db describe-db-cluster \ + --db-cluster-id "" \ + --view FULL + +tdc db update-db-cluster \ + --db-cluster-id "" \ + --db-cluster-name demo-cluster-renamed +``` + +An update must include a new name or spending limit. Preview mutating commands with `--dry-run`. + +Delete a cluster: + +```bash +tdc db delete-db-cluster \ + --db-cluster-id "" \ + --dry-run + +tdc db delete-db-cluster \ + --db-cluster-id "" +``` + +tdc resolves the cluster name internally; no name-confirmation flag is required. + +## Manage branches + +Create and list branches: + +```bash +tdc db create-db-cluster-branch \ + --db-cluster-id "" \ + --db-cluster-branch-name development + +tdc db list-db-cluster-branches \ + --db-cluster-id "" \ + --page-size 20 +``` + +Use `--page-token` to continue a paginated branch list. + +Describe and delete a branch: + +```bash +tdc db describe-db-cluster-branch \ + --db-cluster-id "" \ + --db-cluster-branch-id "" \ + --view FULL + +tdc db delete-db-cluster-branch \ + --db-cluster-id "" \ + --db-cluster-branch-id "" +``` + +Create and delete support `--dry-run`. + +## Create SQL users + +Create or repair the three tdc-managed SQL roles: + +```bash +tdc db create-db-sql-users \ + --db-cluster-id "" +``` + +The operation is idempotent. It reuses stable role names and stores generated credentials under `~/.tdc/db_users//credentials`. It creates: + +- `read_only`; +- `read_write`; +- `admin`. + +Preview the operation without changing users: + +```bash +tdc db create-db-sql-users \ + --db-cluster-id "" \ + --dry-run +``` + +## Format connection strings + +Read-write is the default, but explicit role selection is recommended: + +```bash +tdc db format-db-connection-string \ + --db-cluster-id "" \ + --read-write \ + --database app \ + --format mysql-uri + +tdc db format-db-connection-string \ + --db-cluster-id "" \ + --read-only \ + --format env \ + --env-prefix TIDB_ + +tdc db format-db-connection-string \ + --db-cluster-id "" \ + --admin \ + --format jdbc +``` + +Supported formats are `mysql-uri`, `jdbc`, `go-sql-driver`, `sqlalchemy`, and `env`. With `env`, `--env-include-database-url` adds a URL variable and `--env-database-url-name` changes its name. + +> **Warning:** +> +> Connection strings contain credentials. Do not write them to logs, tickets, or source control. + +## Execute SQL + +Each invocation accepts exactly one SQL statement. Use an explicit role: + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --database app \ + --sql "SELECT COUNT(*) AS row_count FROM messages" \ + --output text + +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-write \ + --database app \ + --sql "INSERT INTO messages(id, body) VALUES (1, 'hello')" + +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --admin \ + --sql "CREATE DATABASE IF NOT EXISTS app" +``` + +The default `--transport https` sends the SQL request over HTTPS without a persistent database connection. Use `--transport mysql` as an explicit compatibility fallback; it opens a connection for the command and closes it afterward. + +## Command summary + +| Command | Purpose | +| --- | --- | +| `create-db-cluster` | Create a Starter cluster | +| `list-db-clusters` | List Starter clusters | +| `describe-db-cluster` | Read one cluster | +| `update-db-cluster` | Change cluster name or spending limit | +| `delete-db-cluster` | Delete a cluster | +| `create-db-cluster-branch` | Create a branch | +| `list-db-cluster-branches` | List branches | +| `describe-db-cluster-branch` | Read one branch | +| `delete-db-cluster-branch` | Delete a branch | +| `create-db-sql-users` | Create or repair three SQL roles | +| `format-db-connection-string` | Format prepared credentials | +| `execute-sql-statement` | Execute one SQL statement | + +## What's next + +- [Query SQL with Explicit Roles](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) +- [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) +- [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md new file mode 100644 index 0000000000000..cebe12aeb9059 --- /dev/null +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -0,0 +1,158 @@ +--- +title: tdc CLI Reference +summary: Reference global flags, output and query behavior, dry-run rules, help forms, errors, command families, and Filesystem aliases. +--- + +# tdc CLI Reference + +This reference describes behavior shared across the tdc command surface. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +tdc [subcommand] [required flags] [optional flags] [global flags] +``` + +tdc accepts long flags only. A one-letter flag such as `-p` is rejected. + +Required flags appear before optional flags in generated usage. Optional flags are enclosed in brackets: + +```text +tdc db describe-db-cluster + --db-cluster-id + [--output ] + [--view ] +``` + +## Global flags + +| Flag | Description | +| --- | --- | +| `--profile ` | Select a local profile; defaults to `default` | +| `--region ` | Override canonical placement for this command | +| `--output ` | Render `json` or `text`; default is `json` | +| `--query ` | Apply a JMESPath expression before rendering | +| `--debug` | Print redacted debug diagnostics | +| `--help` | Display help | +| `--version` | Display tdc version information | + +## Output + +Structured control-plane commands return JSON by default: + +```bash +tdc db list-db-clusters +``` + +Use text output for terminal inspection: + +```bash +tdc db list-db-clusters --output text +``` + +Raw byte-oriented commands such as `tdc fs read-file` and `tdc fs copy-file --to-stdout` write file content directly. + +## JMESPath queries + +`--query` runs after successful command execution and before output rendering: + +```bash +tdc db list-db-clusters \ + --query 'clusters[].{id:id,name:display_name,state:state}' + +tdc organization list-projects \ + --query 'projects[?type == `tidbx_virtual`].id' \ + --output text +``` + +An invalid expression fails without replacing the command result with partial output. + +## Dry-run + +Mutating control-plane commands declare `--dry-run`. The command validates local flags, profile, credentials, region, and request shape, then reports a plan without making the remote mutation. + +```bash +tdc db delete-db-cluster \ + --db-cluster-id "" \ + --dry-run +``` + +Read-only commands reject `--dry-run`. Dry-run is not a general global simulation flag and is available only where shown in command help. + +## Help and version forms + +```bash +tdc help +tdc db help +tdc db create-db-cluster help +tdc --help +tdc db --help +tdc db create-db-cluster --help +tdc --version +tdc fs --version +``` + +`help` is a command for navigating the command tree. `--help` is the conventional flag on each command; both intentionally coexist. + +## Errors and exit behavior + +Human-readable errors use a stable prefix: + +```text +tdc [ERROR]: +``` + +Errors are written to stderr and successful command output is written to stdout. Usage and configuration failures return a nonzero exit code before remote mutation. Runtime and remote API failures also return nonzero. An interrupted interactive configuration returns exit code `130`. + +`--debug` can show redacted request and resolution context. It must not show API keys, FS tokens, DB passwords, SQL text, file contents, or connection strings. + +## Command families + +| Command | Purpose | +| --- | --- | +| `tdc configure` | Configure a local profile | +| `tdc update` | Check or apply release updates | +| `tdc organization` | Inspect projects | +| `tdc db` | Manage Starter clusters, branches, and SQL | +| `tdc fs` | Manage Filesystems, files, layers, packs, and mounts | +| `tdc fs-git` | Manage Git workspaces on mounted Filesystems | +| `tdc fs-journal` | Manage verifiable journals | +| `tdc fs-vault` | Manage secrets and delegated access | + +For complete commands and flags, run: + +```bash +tdc help +tdc help +``` + +## Filesystem alias mapping + +| Alias | Canonical command | +| --- | --- | +| `cp` | `copy-file` | +| `cat` | `read-file` | +| `ls` | `list-files` | +| `stat` | `describe-file` | +| `mv` | `move-file` | +| `rm` | `delete-file` | +| `mkdir` | `create-directory` | +| `chmod` | `chmod-file` | +| `symlink` | `create-symlink` | +| `hardlink` | `create-hardlink` | +| `grep` | `search-file-content` | +| `find` | `find-files` | +| `mount` | `mount-file-system` | +| `drain` | `drain-file-system` | +| `umount` | `unmount-file-system` | + +Aliases use the same long flags, authentication, output, query, and error behavior as canonical commands. + +## Related documentation + +- [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md new file mode 100644 index 0000000000000..2fa41a2768b8f --- /dev/null +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -0,0 +1,195 @@ +--- +title: tdc Configuration and Credentials +summary: Reference tdc profiles, environment and flag precedence, local state paths, Filesystem registry, SQL credentials, mount locators, and operation logs. +--- + +# tdc Configuration and Credentials + +tdc stores all product-owned local state under `~/.tdc/` and separates non-sensitive configuration from credentials. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Main files + +```toml +# ~/.tdc/config +[default] +region_code = "aws-us-east-1" +project_id = "..." +fs_default_file_system_name = "workspace" + +[logging] +enabled = true +max_file_mb = 10 +max_files = 5 +``` + +```toml +# ~/.tdc/credentials +[default] +tdc_public_key = "..." +tdc_private_key = "..." +``` + +The credentials file uses owner-only permissions where the platform supports POSIX modes. + +## Profile selection + +The profile namespace is selected in this order: + +1. explicit `--profile`; +2. `TDC_PROFILE`; +3. `default`. + +An explicit empty profile is invalid. Environment credentials do not create an `[env]` profile and do not change the selected namespace. + +## TiDB Cloud API credentials + +Credential selection is: + +1. `TDC_PUBLIC_KEY` and `TDC_PRIVATE_KEY`, when either is set; +2. the selected section of `~/.tdc/credentials`. + +Both environment values are required together. tdc never mixes one environment half with one file half. + +Placement selection is: + +1. explicit global `--region`; +2. `TDC_REGION_CODE`; +3. profile `region_code`. + +Command flags, environment inputs, saved configuration, and command defaults are resolved per field. Values can therefore come from different levels when they do not form an atomic pair such as the API key pair. + +## Default Starter project + +Starter create selects a project in this order: + +1. explicit non-empty `--project-id`; +2. profile `project_id` discovered by `tdc configure`; +3. fail before sending the create request. + +Other DB commands identify resources by cluster or branch ID and do not use `project_id`. Filesystem commands do not consume the DB project default. + +## Filesystem resource registry + +One profile can register multiple Filesystems. The main config stores only the optional default name. Resource state is isolated: + +```text +~/.tdc/fs_resources///config +~/.tdc/fs_resources///credentials +``` + +The resource config contains the stored Filesystem name, tenant ID, cloud provider, region code, and creation time. The credentials file contains only the owner `api_key` and uses owner-only permissions. + +Resource selection is: + +1. explicit `--file-system-name`; +2. `TDC_FS_FILE_SYSTEM_NAME`; +3. profile `fs_default_file_system_name`; +4. the only registered resource; +5. fail as missing or ambiguous. + +FS owner credential selection for remote `fs`, `fs-git`, `fs-journal`, and owner `fs-vault` operations is: + +1. explicit `--fs-token`; +2. `TDC_FS_TOKEN`; +3. selected resource credential. + +Prefer `TDC_FS_TOKEN` over a flag because flags can remain in shell history or process listings. + +## Config-free Filesystem inputs + +A clean sandbox can use: + +```bash +export TDC_FS_TOKEN="" +export TDC_REGION_CODE="aws-us-east-1" +export TDC_FS_FILE_SYSTEM_NAME="workspace" +``` + +These values form an in-memory namespace only. tdc does not write them to `~/.tdc/`. Provisioning and deletion still require TiDB Cloud API credentials; deletion also requires the local resource registration. + +## DB SQL credentials + +Generated SQL credentials are cluster-scoped: + +```text +~/.tdc/db_users//credentials +``` + +```toml +[read_only] +username = "..." +password = "..." + +[read_write] +username = "..." +password = "..." + +[admin] +username = "..." +password = "..." +``` + +`tdc db create-db-sql-users` creates or repairs these stable users. They are not stored in the main credentials file. + +## Companion state and mount locators + +Each registered Filesystem has an isolated companion home: + +```text +~/.tdc/drive9-home/// +``` + +Do not edit this state or a standalone `~/.drive9` configuration for tdc workflows. + +A successful background FS or vault mount writes a non-secret locator: + +```text +~/.tdc/mounts/.locator.json +``` + +The locator records enough placement and companion-home information for drain and unmount from the same `HOME`. It does not contain the FS token. Successful unmount removes it. + +## Operation logs + +tdc writes redacted local JSON Lines events to: + +```text +~/.tdc/logs/tdc.jsonl +``` + +This log is local audit/debug data, not telemetry. It can include command names, flag names, profile and region, duration, exit and stable error codes, HTTP method/status, operation, and request ID. It excludes flag values, SQL, file paths and contents, payloads, connection strings, and credentials. + +Disable it for one process: + +```bash +TDC_LOGGING=off tdc db list-db-clusters +``` + +Or configure: + +```toml +[logging] +enabled = false +``` + +Environment values `off`, `false`, `0`, and `no` disable logging; `on`, `true`, `1`, and `yes` enable it. Environment takes precedence over config. + +## Sensitive values + +Treat these as secrets: + +- TiDB Cloud API private key and public-key pair; +- FS owner token; +- DB SQL usernames, passwords, and connection strings; +- delegated vault tokens and secret values. + +Do not put them in source control, tickets, logs, command examples, or unprotected shell history. + +## Related documentation + +- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/tdc/reference/tdc-regions-security-and-limitations.md new file mode 100644 index 0000000000000..1166cf4d2502d --- /dev/null +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -0,0 +1,94 @@ +--- +title: tdc Regions, Security, and Limitations +summary: Reference supported regions, authentication boundaries, platform dependencies, Preview constraints, and Filesystem companion behavior. +--- + +# tdc Regions, Security, and Limitations + +This reference describes current placement, authentication, platform, and Preview boundaries. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## TiDB Cloud regions + +tdc accepts one canonical region code: + +| Canonical code | Provider | Location | +| --- | --- | --- | +| `aws-us-east-1` | AWS | N. Virginia | +| `aws-us-west-2` | AWS | Oregon | +| `aws-eu-central-1` | AWS | Frankfurt | +| `aws-ap-northeast-1` | AWS | Tokyo | +| `aws-ap-southeast-1` | AWS | Singapore | +| `ali-ap-southeast-1` | Alibaba Cloud | Singapore | + +Alibaba Cloud currently supports only Singapore in tdc. Users cannot configure raw service URLs. + +## Filesystem regions + +Filesystem endpoint availability is resolved from the hosted Drive9 region manifest. At publication time, TiDB Cloud native Filesystem mode is available for: + +- `aws-us-east-1`; +- `aws-ap-southeast-1`. + +The hosted manifest is authoritative and can change during Preview. A profile in another TiDB Cloud region can manage Starter databases but receives an unsupported Filesystem endpoint error until that placement appears in the manifest. + +## Credential requirements + +| Operation | Required credential | +| --- | --- | +| `tdc configure`, `tdc organization`, all `tdc db` control-plane operations | TiDB Cloud API public/private key | +| `tdc fs create-file-system` | TiDB Cloud API key | +| `tdc fs delete-file-system` | TiDB Cloud API key, local resource registration, and owner resource credential | +| Remote file, layer, pack, mount, Git, journal, and owner vault operations | FS owner token or registered resource credential | +| Delegated vault read, list, run, or mount | Scope-appropriate delegated vault token | +| Drain and unmount after a successful background mount | Non-secret mount locator in the same `HOME` | + +TiDB Cloud API calls use Digest authentication. SQL HTTPS execution uses generated SQL username/password Basic authentication over TLS. These credentials are not interchangeable. + +## Security guidance + +- Prefer environment variables or protected credential files for secrets. +- Use explicit read-only, read-write, or admin roles for SQL. +- Give agents delegated vault grants instead of FS owner tokens when only secret access is required. +- Use `--dry-run` before destructive control-plane operations. +- Keep `~/.tdc/credentials`, resource credentials, and DB SQL credentials owner-readable only. +- Review local operation logs before sharing diagnostics even though tdc redacts known secret classes. + +## Mount platform limitations + +| Platform | Default | Limitations | +| --- | --- | --- | +| macOS | WebDAV | Install macFUSE and explicitly use `--driver fuse` for FUSE caches, drain, and complete POSIX-oriented behavior | +| Linux | FUSE | Requires FUSE3 and `/dev/fuse`; explicit WebDAV requires `davfs2` | +| Windows | WebDAV | Requires the WebClient service and a drive-letter mount path; FUSE and vault mount are unavailable | + +FUSE and WebDAV are implemented by the bundled [Drive9](https://github.com/mem9-ai/drive9) companion. tdc does not fall back to a separate native mount implementation. + +## Durability limitations + +- Default FUSE behavior uses local buffering and asynchronous remote work where permitted by the companion. +- `drain-file-system` is FUSE-only. +- Abruptly killing the mount process or deleting a machine can lose uncommitted memory/write-back state. +- The default coding-agent mount profile stores dependency trees, generated output, caches, and Git internals locally. Local-only data disappears when its disk disappears unless it is packed or otherwise preserved. +- A running mount remains on the companion version loaded at mount time. Unmount and remount after updating tdc. +- Remote-committed Filesystem data survives client or sandbox deletion; deleting the machine does not delete the remote resource. + +## Product limitations + +- tdc is Preview and command contracts can change. +- Database management targets TiDB Cloud Starter, not every TiDB Cloud cluster tier. +- SQL execution accepts one statement per invocation. +- Read-write is the default SQL role; use explicit role flags in security-sensitive automation. +- Journals are append-only and the current public command surface has no journal delete command. +- Filesystem resource list and describe commands operate on the local registry; they are not an organization-wide discovery API. +- Telemetry commands, serverless-function deployment, Homebrew, and Scoop distribution are not implemented. +- tdc depends on its installed `tdc-drive9` companion for all public Filesystem runtime behavior. + +## Related documentation + +- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-troubleshooting.md b/ai/tdc/reference/tdc-troubleshooting.md new file mode 100644 index 0000000000000..eb73ce5c4fd39 --- /dev/null +++ b/ai/tdc/reference/tdc-troubleshooting.md @@ -0,0 +1,190 @@ +--- +title: Troubleshoot tdc +summary: Diagnose tdc authentication, project, Filesystem selection, companion, quota, SQL user, mount, and interrupted-cleanup failures. +--- + +# Troubleshoot tdc + +Use this guide to diagnose common current tdc failures. Add `--debug` only when needed; debug output is redacted but should still be reviewed before sharing. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## API authentication fails + +Symptoms include missing credentials, Digest authentication failure, or permission denied. + +Check that both environment values are set together: + +```bash +test -n "$TDC_PUBLIC_KEY" +test -n "$TDC_PRIVATE_KEY" +``` + +If you intend to use saved credentials, unset both variables and verify the profile: + +```bash +unset TDC_PUBLIC_KEY TDC_PRIVATE_KEY +tdc organization list-projects --profile default +``` + +An API key can authenticate successfully but still lack the permission declared by a command. Use a key with the required organization or project access. + +## Configure cannot find a virtual project + +`tdc configure` requires exactly one accessible project whose `type` is `tidbx_virtual`. + +```bash +tdc organization list-projects \ + --query 'projects[].{id:id,name:name,type:type}' +``` + +If no virtual project appears, confirm the API key's organization and project access. If multiple virtual projects appear, report the ambiguous account state through the [tdc issue tracker](https://github.com/tidbcloud/tdc/issues). + +## Filesystem token is missing + +For a clean sandbox, provide all three values: + +```bash +export TDC_FS_TOKEN="" +export TDC_REGION_CODE="aws-us-east-1" +export TDC_FS_FILE_SYSTEM_NAME="workspace" +tdc fs check-file-system +``` + +The FS token is not the TiDB Cloud API private key. + +## Filesystem selection is ambiguous + +List registered resources and select one explicitly: + +```bash +tdc fs list-file-systems --output text +tdc fs list-files --file-system-name workspace --path / +``` + +Or set a default: + +```bash +tdc fs set-default-file-system --file-system-name workspace +``` + +tdc intentionally does not guess among multiple resources. + +## Filesystem region is unsupported + +The configured TiDB Cloud region might not have a `tidb_cloud_native` Filesystem endpoint. Compare it with [current Filesystem regions](/ai/tdc/reference/tdc-regions-security-and-limitations.md#filesystem-regions). Change placement with a valid profile or command-scoped `--region`; do not configure a raw server URL. + +## Companion is missing or incompatible + +The release installer places `tdc-drive9` next to `tdc`. Re-run the current installer when tdc reports a missing companion: + +```bash +curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes +``` + +Verify that `PATH` resolves the expected tdc: + +```bash +command -v tdc +tdc --version +``` + +Do not copy an arbitrary standalone Drive9 binary into place. + +## Starter or Filesystem creation reaches quota + +Quota and capacity errors can mean the organization has reached its free Starter limit. List existing resources before creating another: + +```bash +tdc db list-db-clusters --output text +tdc fs list-file-systems --output text +``` + +Never delete an unrelated resource to make automation pass. A Starter spending limit can require configured billing. + +## SQL credentials are missing + +Prepare or repair users for the exact cluster: + +```bash +tdc db create-db-sql-users --db-cluster-id "" +``` + +Then retry with an explicit role: + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --sql "SELECT 1" +``` + +Deleting `~/.tdc/db_users//credentials` removes local passwords. Run the create/repair command rather than inventing credentials. + +## Mount does not become ready + +Inspect the log path printed by the timeout error. Confirm: + +- the mount path exists and is writable; +- no existing mount covers the path; +- the FS token and region are valid; +- FUSE prerequisites or the WebDAV helper are installed; +- the remote region is reachable. + +macOS defaults to WebDAV. To request FUSE after installing macFUSE: + +```bash +tdc fs mount-file-system \ + --mount-path /path/to/workspace \ + --driver fuse +``` + +Linux needs FUSE3 and access to `/dev/fuse`. Windows WebDAV needs the WebClient service and a drive letter such as `X:`. + +## Mount becomes stale after a process crash + +If the companion is killed without graceful unmount, FUSE access can return `EIO` or `Transport endpoint is not connected`. Stop processes with open files, then try: + +```bash +tdc fs unmount-file-system \ + --mount-path /path/to/workspace \ + --force +``` + +Use `--ignore-absent` when cleanup should succeed if no locator remains. Abrupt cleanup cannot guarantee recovery of pending writes from a deleted local disk. + +## Unmount reports busy + +Close editors, shells whose working directory is inside the mount, and other open file handles. For FUSE, drain before retrying: + +```bash +tdc fs drain-file-system --mount-path /path/to/workspace --timeout 30s +tdc fs unmount-file-system --mount-path /path/to/workspace +``` + +Do not use drain for WebDAV. + +## An interrupted command leaves resources + +List resources and identify only those created by your workflow. Use describe before delete: + +```bash +tdc db describe-db-cluster --db-cluster-id "" +tdc fs describe-file-system --file-system-name "" +``` + +Preview supported cleanup: + +```bash +tdc db delete-db-cluster --db-cluster-id "" --dry-run +tdc fs delete-file-system \ + --file-system-name "" \ + --confirm-file-system-name "" \ + --dry-run +``` + +## Report a problem + +Include the tdc version, OS and architecture, command name, stable error code, and redacted logs. Never include API keys, FS or vault tokens, DB passwords, SQL containing private data, or file contents. Report issues at [github.com/tidbcloud/tdc/issues](https://github.com/tidbcloud/tdc/issues). diff --git a/ai/tdc/tdc-overview.md b/ai/tdc/tdc-overview.md new file mode 100644 index 0000000000000..f7d0c0fb2cbdf --- /dev/null +++ b/ai/tdc/tdc-overview.md @@ -0,0 +1,72 @@ +--- +title: TiDB Cloud CLI (tdc) Overview +summary: Learn how the Preview tdc command-line interface manages TiDB Cloud Starter databases and TiDB Cloud Filesystem for users, scripts, and AI agents. +--- + +# TiDB Cloud CLI (tdc) Overview + +tdc is a command-line interface for managing TiDB Cloud Starter databases and TiDB Cloud Filesystem. It provides deterministic JSON output, explicit permissions, scriptable configuration, and commands designed for both users and AI agents. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## What you can do with tdc + +With tdc, you can: + +- create, inspect, update, and delete TiDB Cloud Starter clusters; +- create and manage Starter branches; +- create read-only, read-write, and admin SQL users, format connection strings, and execute SQL; +- create and select multiple TiDB Cloud Filesystem resources in one profile; +- access Filesystem data directly or mount it through FUSE or WebDAV; +- use Filesystem layers, packs, Git workspaces, append-only journals, and delegated secrets; +- use JSON output and JMESPath queries in scripts and agent workflows. + +tdc has a two-level command model: + +```text +tdc +``` + +Examples include `tdc db list-db-clusters`, `tdc fs copy-file`, and `tdc fs-journal verify-journal`. The top-level `tdc configure` and `tdc update` commands configure and maintain the CLI. + +## tdc and Drive9 + +tdc installs a bundled [Drive9](https://github.com/mem9-ai/drive9) companion named `tdc-drive9`. tdc owns profile selection, TiDB Cloud credentials, region and Filesystem selection, output formatting, and tdc error behavior. The companion owns Filesystem data-plane semantics, FUSE and WebDAV mounts, layers, pack and unpack, Git workspace acceleration, journals, and vault operations. + +You do not need to install, configure, or invoke Drive9 separately for normal tdc workflows. + +## Start using tdc + +- [Quick Start](/ai/tdc/tdc-quick-start.md) +- [Concepts and Architecture](/ai/tdc/concepts/tdc-concepts-and-architecture.md) + +### Guides + +- [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) +- [Manage TiDB Cloud Organizations](/ai/tdc/guides/tdc-organization.md) +- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) +- [Manage TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem.md) +- [Use Git Workspaces on TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem-git.md) +- [Use Filesystem Journals](/ai/tdc/guides/tdc-filesystem-journal.md) +- [Use Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) + +### Examples + +- [Use a Filesystem in an Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) +- [Run a Daily tdc Workflow](/ai/tdc/examples/tdc-daily-workflow-example.md) +- [Query SQL with Explicit Roles](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) +- [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) +- [Prepare a Git Workspace for Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) +- [Record an Agent Workflow in a Journal](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) +- [Delegate Secrets to an Agent](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) + +### Reference + +- [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) + +To report a problem or suggest an improvement, create an issue in the [tdc GitHub repository](https://github.com/tidbcloud/tdc/issues). diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md new file mode 100644 index 0000000000000..841f6ed4b3c47 --- /dev/null +++ b/ai/tdc/tdc-quick-start.md @@ -0,0 +1,130 @@ +--- +title: Get Started with TiDB Cloud CLI (tdc) +summary: Install and configure tdc, then complete a first TiDB Cloud Starter database or Filesystem operation. +--- + +# Get Started with TiDB Cloud CLI (tdc) + +This quick start installs tdc, configures one profile, and gets a successful result from either TiDB Cloud Starter or TiDB Cloud Filesystem. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior 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. The key must be able to access a `tidbx_virtual` project. + +## Step 1. Install tdc + +On macOS or Linux: + +```bash +curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes +export PATH="$HOME/.tdc/bin:$PATH" +tdc --version +``` + +Add `export PATH="$HOME/.tdc/bin:$PATH"` to your shell profile to keep tdc available in new terminals. + +On Windows PowerShell: + +```powershell +$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 +$env:Path = "$HOME\.tdc\bin;$env:Path" +tdc --version +``` + +## Step 2. Configure tdc + +Run the interactive configuration: + +```bash +tdc configure +``` + +Enter your API public key, private key, and a canonical region code such as `aws-us-east-1`. tdc validates the key, discovers the `tidbx_virtual` project, and saves it as the default project. + +Verify the configuration: + +```bash +tdc organization list-projects --output text +``` + +## Step 3. Choose a first workflow + +Complete either the Filesystem workflow or the Starter database workflow. + +### Option A: Write and read a file + +Create a Filesystem and capture its owner token without displaying it: + +```bash +export TDC_FS_TOKEN="$(tdc fs create-file-system \ + --file-system-name quickstart-fs \ + --query fs_token \ + --output text)" +``` + +Write and read a file through the data plane: + +```bash +printf 'hello from tdc\n' | tdc fs copy-file \ + --file-system-name quickstart-fs \ + --from-stdin \ + --to-remote /hello.txt + +tdc fs read-file \ + --file-system-name quickstart-fs \ + --path /hello.txt +``` + +Expected output: + +```text +hello from tdc +``` + +Clean up: + +```bash +tdc fs delete-file-system \ + --file-system-name quickstart-fs \ + --confirm-file-system-name quickstart-fs +unset TDC_FS_TOKEN +``` + +### Option B: Query a Starter database + +List clusters and select an active cluster ID: + +```bash +tdc db list-db-clusters --output text +export TDC_DB_CLUSTER_ID="" +``` + +If the cluster does not yet have tdc-managed SQL users, create them: + +```bash +tdc db create-db-sql-users --db-cluster-id "$TDC_DB_CLUSTER_ID" +``` + +Run a read-only verification query: + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "$TDC_DB_CLUSTER_ID" \ + --read-only \ + --sql "SELECT 1 AS ready" \ + --output text +``` + +The command executes one statement through the HTTPS SQL API and returns a result containing `ready = 1`. + +## What's next + +- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) +- [Manage TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem.md) +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) From 388e0b6e0a0e57a4fc231d3ded5c70dbc95a0037 Mon Sep 17 00:00:00 2001 From: Cheese Date: Sat, 18 Jul 2026 02:33:12 +0800 Subject: [PATCH 02/29] docs: improve tdc onboarding and examples --- ai/tdc/examples/tdc-agent-sandbox-example.md | 14 +++- .../tdc-git-workspace-for-agents-example.md | 31 +++++++-- .../tdc-journal-agent-workflow-example.md | 14 +++- .../tdc-query-sql-with-roles-example.md | 14 +++- ...hare-filesystem-across-machines-example.md | 14 +++- .../tdc-vault-agent-secrets-example.md | 14 +++- ai/tdc/guides/tdc-filesystem-git.md | 8 ++- ai/tdc/guides/tdc-install-configure-update.md | 14 ++++ .../tdc-configuration-and-credentials.md | 2 +- .../tdc-regions-security-and-limitations.md | 10 ++- ai/tdc/tdc-quick-start.md | 66 +++++++++++++------ 11 files changed, 164 insertions(+), 37 deletions(-) diff --git a/ai/tdc/examples/tdc-agent-sandbox-example.md b/ai/tdc/examples/tdc-agent-sandbox-example.md index 9c080242a49d3..d702c00309fa1 100644 --- a/ai/tdc/examples/tdc-agent-sandbox-example.md +++ b/ai/tdc/examples/tdc-agent-sandbox-example.md @@ -5,12 +5,24 @@ summary: Provision a Filesystem on a trusted machine and give a clean agent sand # Use TiDB Cloud Filesystem in an Agent Sandbox -This example provisions a Filesystem on a trusted machine, transfers the minimum environment to a clean sandbox, and uses tdc without copying `~/.tdc/`. +This example gives an ephemeral coding agent a durable workspace without copying a user's complete tdc configuration into the sandbox. > **Note:** > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## The agent problem + +Coding agents often start in clean, short-lived sandboxes. The local disk disappears when the sandbox is replaced, but the agent still needs previous artifacts, repository state, and files produced by other workers. Rebuilding that state wastes task time, while copying `~/.tdc/` or injecting TiDB Cloud API keys gives the sandbox control-plane credentials it does not need. + +## Why local storage and full cloud credentials are not enough + +A sandbox-local directory is fast but not durable or shared. Generic object-storage APIs require application-specific download and upload logic instead of ordinary file operations. Giving every sandbox the user's complete cloud credentials solves access at the cost of a much broader security boundary. + +## How tdc changes the workflow + +A trusted machine provisions the Filesystem once. The sandbox receives only the Filesystem owner token, region code, and Filesystem name, and can immediately use data-plane, mount, Git, journal, and vault workflows without `tdc configure`. When an agent needs only selected secrets, use a delegated vault token instead of the owner token. + ## Prerequisites - Install and configure tdc on a trusted machine. diff --git a/ai/tdc/examples/tdc-git-workspace-for-agents-example.md b/ai/tdc/examples/tdc-git-workspace-for-agents-example.md index 4efb162eae68c..6896ba7222bcd 100644 --- a/ai/tdc/examples/tdc-git-workspace-for-agents-example.md +++ b/ai/tdc/examples/tdc-git-workspace-for-agents-example.md @@ -1,16 +1,28 @@ --- title: Prepare a Git Workspace for Agents on TiDB Cloud Filesystem -summary: Mount a Filesystem, create a fast Git workspace and linked worktree, use Git normally, and clean up safely. +summary: Make a large Git workspace visible quickly, hydrate clean objects in the background, and let an agent start work before the full download finishes. --- # Prepare a Git Workspace for Agents on TiDB Cloud Filesystem -This example prepares a repository and an isolated linked worktree for an agent. +This example removes a large repository clone from the critical path of starting an agent task. > **Note:** > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## The agent problem + +An ephemeral agent normally waits for `git clone` and checkout to download a repository before it can inspect the tree or begin work. For a large monorepo, that startup delay is paid again for every replacement sandbox. The agent appears idle even when its first task needs only a small part of the repository. + +## Why a normal clone or partial clone is not enough + +A normal clone blocks until the initial object transfer and checkout finish. A native blobless partial clone reduces the first transfer, but later Git commands and file reads can still trigger many on-demand fetches on the agent's critical path. Neither approach by itself provides a shared Filesystem workspace that can be restored across agent runtimes. + +## How tdc changes the workflow + +`tdc fs-git clone-git-workspace --blobless --hydrate background` registers the Git workspace and exposes its file tree before all clean blobs finish downloading. The command returns so the agent can inspect paths and start working while tdc hydrates the clean tree and local Git object database in the background. Reads that arrive before hydration completes fall back to Git's lazy fetch for correctness. Ordinary Git remains responsible for edits, commits, fetches, and pushes. + ## Prerequisites - Select a Filesystem. @@ -26,22 +38,31 @@ tdc fs mount-file-system \ --driver fuse ``` -## Step 2. Clone and hydrate +## Step 2. Create the workspace and hydrate in the background ```bash tdc fs-git clone-git-workspace \ --repo-url https://github.com/pingcap/tidb.git \ --target-path /path/to/workspace/tidb \ --blobless \ - --hydrate sync + --hydrate background ``` -Verify: +The workspace tree is now available, and hydration continues in the background. Let the agent start with ordinary commands: ```bash +find /path/to/workspace/tidb -maxdepth 2 -type f | head git -C /path/to/workspace/tidb status ``` +Before a deterministic benchmark or before draining the mount, you can wait for hydration explicitly: + +```bash +tdc fs-git hydrate-git-workspace \ + --target-path /path/to/workspace/tidb \ + --timeout 30m +``` + ## Step 3. Create an agent worktree ```bash diff --git a/ai/tdc/examples/tdc-journal-agent-workflow-example.md b/ai/tdc/examples/tdc-journal-agent-workflow-example.md index 788953e6085ca..5b8d4aa01f442 100644 --- a/ai/tdc/examples/tdc-journal-agent-workflow-example.md +++ b/ai/tdc/examples/tdc-journal-agent-workflow-example.md @@ -5,12 +5,24 @@ summary: Create a journal, append structured agent events, search the workflow, # Record an Agent Workflow in a Filesystem Journal -This example records an agent task as structured, ordered events rather than appending unvalidated text to a mutable file. +This example records an agent task as a structured, ordered, and verifiable event history. > **Note:** > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## The agent problem + +An agent task can span planning, tool calls, tests, retries, and handoffs between workers. When the task fails, operators need to know which events happened and in what order. Plain console output is often scattered across processes, while a mutable status file shows only the latest state. + +## Why appending to a normal file is not enough + +A text file can be edited or truncated after an event is written, has no intrinsic sequence or hash chain, and requires every producer to invent parsing and concurrency rules. Retrying an append can also create duplicate events unless the application builds its own idempotency layer. + +## How tdc changes the workflow + +A Filesystem journal stores structured append-only entries with sequence information, searchable fields, optional idempotency keys, and hash-chain verification. Agents append semantic events such as `task.started` and `test.finished`; operators can query the workflow and verify the stored chain without treating a mutable log file as evidence. + ## Prerequisites Select a Filesystem through a configured profile or FS token environment. diff --git a/ai/tdc/examples/tdc-query-sql-with-roles-example.md b/ai/tdc/examples/tdc-query-sql-with-roles-example.md index d9289fc297500..f8fb20e3f91f3 100644 --- a/ai/tdc/examples/tdc-query-sql-with-roles-example.md +++ b/ai/tdc/examples/tdc-query-sql-with-roles-example.md @@ -5,12 +5,24 @@ summary: Prepare tdc-managed SQL users and run read-only, read-write, and admin # Query TiDB Cloud Starter with Explicit SQL Roles -This example uses all three tdc-managed SQL roles without exposing generated passwords. +This example lets an agent perform schema, data, and verification work while making the required privilege level explicit for every statement. > **Note:** > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## The agent problem + +An agent that can inspect data often also needs to apply a migration or update a row. Giving it one administrator connection for the complete task is convenient, but a mistaken statement during an inspection step then has the authority to change or delete data. Giving it only a read-only connection prevents legitimate write and schema work. + +## Why one native database connection is not enough + +TiDB supports SQL privileges, but a conventional client session uses the privileges of the one credential used to connect. Users must create, store, and switch among credentials themselves, and an agent can silently keep using an overly privileged connection across task phases. + +## How tdc changes the workflow + +`tdc db create-db-sql-users` creates stable read-only, read-write, and admin identities and stores their credentials locally. Each `execute-sql-statement` invocation selects one role explicitly, uses the corresponding credential, and executes one statement. The agent can therefore use admin for schema changes, read-write for data changes, and read-only for verification without handling passwords directly. + ## Prerequisites - Configure tdc. diff --git a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md index 32b6d301f67bf..d0028d289b152 100644 --- a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md +++ b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md @@ -5,12 +5,24 @@ summary: Create one Filesystem, securely access it from a second machine, and ve # Share a TiDB Cloud Filesystem Across Machines -This example creates a Filesystem on machine A and accesses the same data from machine B without copying a tdc profile. +This example gives agents or users on two machines one shared workspace without copying files between machine-local disks. > **Note:** > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## The agent problem + +An agent can prepare source files or artifacts on machine A and continue the task on machine B, but each machine normally sees only its own disk. Copying a snapshot before every handoff adds latency, and changes made after the copy are invisible to the other machine. Concurrent handoffs can also create conflicting copies with no clear source of truth. + +## Why native local disks and manual synchronization are not enough + +Local disks do not provide a shared namespace. Commands such as `scp` and archive upload transfer point-in-time copies rather than live state, while object storage does not by itself behave like the mounted directory expected by editors, build tools, and agents. + +## How tdc changes the workflow + +Both machines select the same TiDB Cloud Filesystem. Data-plane commands and the mounted path address one remote namespace, so a write from either interface becomes visible through the other after it is flushed. Machine B needs only the Filesystem token, region code, and name; it does not need TiDB Cloud API keys or a copied profile. + ## Prerequisites - Machine A has configured tdc. diff --git a/ai/tdc/examples/tdc-vault-agent-secrets-example.md b/ai/tdc/examples/tdc-vault-agent-secrets-example.md index 99bf88c5ab705..1b6efcaad23b4 100644 --- a/ai/tdc/examples/tdc-vault-agent-secrets-example.md +++ b/ai/tdc/examples/tdc-vault-agent-secrets-example.md @@ -5,12 +5,24 @@ summary: Store a secret, grant one field to an agent, inject it into a process, # Delegate Filesystem Vault Secrets to an Agent -This example gives an agent temporary access to one field without sharing the Filesystem owner token. +This example gives an agent temporary access to one secret field without sharing the Filesystem owner token or the complete secret. > **Note:** > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## The agent problem + +An agent might need one API endpoint or token to complete a short task. Putting the complete secret in a prompt, `.env` file, or sandbox image exposes it beyond the process and lifetime that need it. Sharing the Filesystem owner token also grants much more access than one secret field requires. + +## Why ordinary environment variables and files are not enough + +Environment variables and files can deliver a secret, but they do not create a scoped, expiring delegation or an access audit trail. A separate cloud secret manager can provide those controls, but it requires another identity, policy, and integration path for every sandbox. + +## How tdc changes the workflow + +The Filesystem owner stores the secret once and creates a short-lived grant scoped to the required field. The agent receives only the delegated vault token and can inject the allowed value into a child process. The owner can inspect audit events and revoke the grant without rotating or exposing the Filesystem owner credential. + ## Prerequisites - Select a Filesystem with owner access. diff --git a/ai/tdc/guides/tdc-filesystem-git.md b/ai/tdc/guides/tdc-filesystem-git.md index 05d41eec7eebc..5772e62c64976 100644 --- a/ai/tdc/guides/tdc-filesystem-git.md +++ b/ai/tdc/guides/tdc-filesystem-git.md @@ -25,17 +25,19 @@ tdc fs-git clone-git-workspace \ --target-path /path/to/workspace/tidb ``` -For a large repository, create a blobless workspace and hydrate synchronously: +For a large repository, create a blobless workspace and hydrate in the background: ```bash tdc fs-git clone-git-workspace \ --repo-url https://github.com/pingcap/tidb.git \ --target-path /path/to/workspace/tidb \ --blobless \ - --hydrate sync + --hydrate background ``` -`--hydrate` accepts `auto`, `background`, `sync`, or `off`. +The command returns after registering the workspace, so the file tree becomes available while clean content and Git objects continue to hydrate. Reads before hydration finishes use Git lazy fetch for correctness. This moves most repository download work out of the agent startup path. + +`--hydrate` accepts `auto`, `background`, `sync`, or `off`. Use `sync` when the caller must wait for hydration before continuing, such as a deterministic benchmark. ## Hydrate an existing workspace diff --git a/ai/tdc/guides/tdc-install-configure-update.md b/ai/tdc/guides/tdc-install-configure-update.md index c0b2166b824ff..bcb1461765708 100644 --- a/ai/tdc/guides/tdc-install-configure-update.md +++ b/ai/tdc/guides/tdc-install-configure-update.md @@ -15,8 +15,15 @@ This guide covers the supported release installers, profile configuration, help ### macOS and Linux +Run the installer: + ```bash 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: + +```bash export PATH="$HOME/.tdc/bin:$PATH" tdc --version ``` @@ -25,10 +32,17 @@ The installer places `tdc` and its `tdc-drive9` companion in `~/.tdc/bin`. Add t ### Windows +Run the installer: + ```powershell $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: + +```powershell $env:Path = "$HOME\.tdc\bin;$env:Path" tdc --version ``` diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md index 2fa41a2768b8f..71d4ebc520c52 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -43,7 +43,7 @@ The profile namespace is selected in this order: 2. `TDC_PROFILE`; 3. `default`. -An explicit empty profile is invalid. Environment credentials do not create an `[env]` profile and do not change the selected namespace. +An explicit empty profile is invalid. ## TiDB Cloud API credentials diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/tdc/reference/tdc-regions-security-and-limitations.md index 1166cf4d2502d..9b7fed86f189f 100644 --- a/ai/tdc/reference/tdc-regions-security-and-limitations.md +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -28,10 +28,14 @@ Alibaba Cloud currently supports only Singapore in tdc. Users cannot configure r ## Filesystem regions -Filesystem endpoint availability is resolved from the hosted Drive9 region manifest. At publication time, TiDB Cloud native Filesystem mode is available for: +Filesystem endpoint availability is resolved from the hosted Drive9 region manifest. At publication time, TiDB Cloud native Filesystem mode is available in: -- `aws-us-east-1`; -- `aws-ap-southeast-1`. +| Cloud provider | Canonical region code | +| --- | --- | +| AWS | `aws-ap-southeast-1` | +| AWS | `aws-us-east-1` | +| AWS | `aws-us-west-2` | +| Alibaba Cloud | `ali-ap-southeast-1` | The hosted manifest is authoritative and can change during Preview. A profile in another TiDB Cloud region can manage Starter databases but receives an unsupported Filesystem endpoint error until that placement appears in the manifest. diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index 841f6ed4b3c47..1d3907448bfc9 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -13,30 +13,42 @@ This quick start installs tdc, configures one profile, and gets a successful res ## 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. The key must be able to access a `tidbx_virtual` project. +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. ## Step 1. Install tdc -On macOS or Linux: +On macOS or Linux, run the installer: ```bash 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: + +```bash export PATH="$HOME/.tdc/bin:$PATH" tdc --version ``` Add `export PATH="$HOME/.tdc/bin:$PATH"` to your shell profile to keep tdc available in new terminals. -On Windows PowerShell: +On Windows PowerShell, run the installer: ```powershell $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: + +```powershell $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. + ## Step 2. Configure tdc Run the interactive configuration: @@ -45,7 +57,7 @@ Run the interactive configuration: tdc configure ``` -Enter your API public key, private key, and a canonical region code such as `aws-us-east-1`. tdc validates the key, discovers the `tidbx_virtual` project, and saves it as the default project. +Enter your API public key, private key, and a canonical region code such as `aws-us-east-1`. Verify the configuration: @@ -59,26 +71,23 @@ Complete either the Filesystem workflow or the Starter database workflow. ### Option A: Write and read a file -Create a Filesystem and capture its owner token without displaying it: +Create a Filesystem and make it the default: ```bash -export TDC_FS_TOKEN="$(tdc fs create-file-system \ +tdc fs create-file-system \ --file-system-name quickstart-fs \ - --query fs_token \ - --output text)" + --set-default \ + --output text ``` -Write and read a file through the data plane: +tdc stores the Filesystem credential locally. Write and read a file directly: ```bash printf 'hello from tdc\n' | tdc fs copy-file \ - --file-system-name quickstart-fs \ --from-stdin \ --to-remote /hello.txt -tdc fs read-file \ - --file-system-name quickstart-fs \ - --path /hello.txt +tdc fs read-file --path /hello.txt ``` Expected output: @@ -93,27 +102,37 @@ Clean up: tdc fs delete-file-system \ --file-system-name quickstart-fs \ --confirm-file-system-name quickstart-fs -unset TDC_FS_TOKEN ``` ### Option B: Query a Starter database -List clusters and select an active cluster ID: +Create a Starter cluster and save its ID: ```bash -tdc db list-db-clusters --output text -export TDC_DB_CLUSTER_ID="" +export TDC_DB_CLUSTER_ID="$(tdc db create-db-cluster \ + --db-cluster-name quickstart-db \ + --db-cluster-type starter \ + --query id \ + --output text)" ``` -If the cluster does not yet have tdc-managed SQL users, create them: +Wait until the cluster is active: ```bash -tdc db create-db-sql-users --db-cluster-id "$TDC_DB_CLUSTER_ID" +until [ "$(tdc db describe-db-cluster \ + --db-cluster-id "$TDC_DB_CLUSTER_ID" \ + --query state \ + --output text)" = "ACTIVE" ]; do + sleep 5 +done ``` -Run a read-only verification query: +Create the SQL users and run a read-only verification query: ```bash +tdc db create-db-sql-users \ + --db-cluster-id "$TDC_DB_CLUSTER_ID" + tdc db execute-sql-statement \ --db-cluster-id "$TDC_DB_CLUSTER_ID" \ --read-only \ @@ -123,6 +142,13 @@ tdc db execute-sql-statement \ The command executes one statement through the HTTPS SQL API and returns a result containing `ready = 1`. +Clean up: + +```bash +tdc db delete-db-cluster --db-cluster-id "$TDC_DB_CLUSTER_ID" +unset TDC_DB_CLUSTER_ID +``` + ## What's next - [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) From d9fcf59d0b0ee3efc81b1ad093b75be42bdffac9 Mon Sep 17 00:00:00 2001 From: Cheese Date: Sat, 18 Jul 2026 22:33:24 +0800 Subject: [PATCH 03/29] docs: document unified wait behavior --- ai/tdc/examples/tdc-agent-sandbox-example.md | 1 + ...-share-filesystem-across-machines-example.md | 1 + ai/tdc/guides/tdc-filesystem.md | 8 ++++++-- ai/tdc/guides/tdc-starter-database.md | 10 ++++++---- ai/tdc/tdc-quick-start.md | 17 +++++------------ 5 files changed, 19 insertions(+), 18 deletions(-) diff --git a/ai/tdc/examples/tdc-agent-sandbox-example.md b/ai/tdc/examples/tdc-agent-sandbox-example.md index d702c00309fa1..a9da22eec7040 100644 --- a/ai/tdc/examples/tdc-agent-sandbox-example.md +++ b/ai/tdc/examples/tdc-agent-sandbox-example.md @@ -34,6 +34,7 @@ A trusted machine provisions the Filesystem once. The sandbox receives only the ```bash export TDC_FS_TOKEN="$(tdc fs create-file-system \ --file-system-name agent-sandbox \ + --wait \ --query fs_token \ --output text)" ``` diff --git a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md index d0028d289b152..b79b1b5a4b2ea 100644 --- a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md +++ b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md @@ -34,6 +34,7 @@ Both machines select the same TiDB Cloud Filesystem. Data-plane commands and the ```bash export TDC_FS_TOKEN="$(tdc fs create-file-system \ --file-system-name shared-workspace \ + --wait \ --query fs_token \ --output text)" diff --git a/ai/tdc/guides/tdc-filesystem.md b/ai/tdc/guides/tdc-filesystem.md index 2a3ba4f1dd252..39a4a73addbf7 100644 --- a/ai/tdc/guides/tdc-filesystem.md +++ b/ai/tdc/guides/tdc-filesystem.md @@ -26,14 +26,18 @@ Create a resource and make it the profile default: ```bash tdc fs create-file-system \ --file-system-name workspace \ - --set-default + --set-default \ + --wait ``` +Without `--wait`, tdc returns after Drive9 accepts provisioning. With the flag, tdc waits up to 10 minutes until the root is readable through the public Drive9 data-plane CLI. A failed wait leaves the resource and locally stored credential intact. + The JSON response includes `fs_token`. Capture it without displaying the complete result: ```bash export TDC_FS_TOKEN="$(tdc fs create-file-system \ --file-system-name sandbox \ + --wait \ --query fs_token \ --output text)" ``` @@ -66,7 +70,7 @@ tdc fs delete-file-system \ --confirm-file-system-name workspace ``` -Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and a locally registered resource; an FS token alone cannot delete the resource. +Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and a locally registered resource; an FS token alone cannot delete the resource. Drive9 deletion is asynchronous, so a successfully accepted request reports `status: "deleting"` while tdc removes the selected local registry entry and credential. ## Select one of multiple Filesystems diff --git a/ai/tdc/guides/tdc-starter-database.md b/ai/tdc/guides/tdc-starter-database.md index 9fd2eb2d8291c..eede33800021c 100644 --- a/ai/tdc/guides/tdc-starter-database.md +++ b/ai/tdc/guides/tdc-starter-database.md @@ -66,10 +66,11 @@ tdc db delete-db-cluster \ --dry-run tdc db delete-db-cluster \ - --db-cluster-id "" + --db-cluster-id "" \ + --wait ``` -tdc resolves the cluster name internally; no name-confirmation flag is required. +tdc resolves the cluster name internally; no name-confirmation flag is required. Without `--wait`, delete returns after TiDB Cloud accepts the asynchronous request. The wait flag waits up to 12 minutes and returns when the cluster is `DELETED` or no longer accessible. ## Manage branches @@ -78,14 +79,15 @@ Create and list branches: ```bash tdc db create-db-cluster-branch \ --db-cluster-id "" \ - --db-cluster-branch-name development + --db-cluster-branch-name development \ + --wait tdc db list-db-cluster-branches \ --db-cluster-id "" \ --page-size 20 ``` -Use `--page-token` to continue a paginated branch list. +Use `--page-token` to continue a paginated branch list. Without `--wait`, branch creation returns after the request is accepted. The wait flag waits up to five minutes for `ACTIVE`. Describe and delete a branch: diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index 1d3907448bfc9..e0bded03a34db 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -77,6 +77,7 @@ Create a Filesystem and make it the default: tdc fs create-file-system \ --file-system-name quickstart-fs \ --set-default \ + --wait \ --output text ``` @@ -112,21 +113,11 @@ Create a Starter cluster and save its ID: export TDC_DB_CLUSTER_ID="$(tdc db create-db-cluster \ --db-cluster-name quickstart-db \ --db-cluster-type starter \ + --wait \ --query id \ --output text)" ``` -Wait until the cluster is active: - -```bash -until [ "$(tdc db describe-db-cluster \ - --db-cluster-id "$TDC_DB_CLUSTER_ID" \ - --query state \ - --output text)" = "ACTIVE" ]; do - sleep 5 -done -``` - Create the SQL users and run a read-only verification query: ```bash @@ -145,7 +136,9 @@ The command executes one statement through the HTTPS SQL API and returns a resul Clean up: ```bash -tdc db delete-db-cluster --db-cluster-id "$TDC_DB_CLUSTER_ID" +tdc db delete-db-cluster \ + --db-cluster-id "$TDC_DB_CLUSTER_ID" \ + --wait unset TDC_DB_CLUSTER_ID ``` From 19599b7bc5f35fb2c0eb38c42d1709761740cd7b Mon Sep 17 00:00:00 2001 From: Cheese Date: Sun, 19 Jul 2026 02:56:57 +0800 Subject: [PATCH 04/29] docs: add Docker FUSE mount guidance --- ai/tdc/guides/tdc-filesystem.md | 82 +++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/ai/tdc/guides/tdc-filesystem.md b/ai/tdc/guides/tdc-filesystem.md index 39a4a73addbf7..c9554e63eb194 100644 --- a/ai/tdc/guides/tdc-filesystem.md +++ b/ai/tdc/guides/tdc-filesystem.md @@ -221,6 +221,88 @@ The default `--driver auto` is platform-specific. `--remote-path` exposes a subt | Linux | FUSE | FUSE3 and access to `/dev/fuse`; install `davfs2` for explicit WebDAV | FUSE supports drain and FUSE cache controls | | Windows | WebDAV | Windows WebClient service | Mount path must be a drive letter such as `X:`; FUSE and vault mount are unavailable | +### Mount in Docker and Docker Compose + +Installing FUSE3 inside an image is not sufficient by itself. The Docker host must provide `/dev/fuse`, and the container must receive permission to perform the mount. The following Dockerfile installs the required Ubuntu package and tdc without storing any cloud or Filesystem credentials in the image: + +```dockerfile +FROM ubuntu:24.04 + +ARG TDC_VERSION=latest + +RUN apt-get update \ + && apt-get install -y --no-install-recommends ca-certificates curl fuse3 \ + && rm -rf /var/lib/apt/lists/* + +RUN curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh \ + | sh -s -- --yes --version "${TDC_VERSION}" + +ENV PATH="/root/.tdc/bin:${PATH}" + +RUN mkdir -p /workspace + +CMD ["bash"] +``` + +Build the image, then pass the Filesystem owner token, canonical region code, and Filesystem name at runtime: + +```bash +docker build -t tdc-fuse . + +docker run --rm -it \ + --device /dev/fuse \ + --cap-add SYS_ADMIN \ + --security-opt apparmor=unconfined \ + --env TDC_FS_TOKEN \ + --env TDC_REGION_CODE \ + --env TDC_FS_FILE_SYSTEM_NAME \ + tdc-fuse +``` + +The three environment variables must already exist in the host shell. Inside the container, mount and use the Filesystem normally: + +```bash +tdc fs mount --mount-path /workspace +printf 'hello from Docker\n' > /workspace/hello.txt +tdc fs drain --mount-path /workspace +tdc fs umount --mount-path /workspace +``` + +Use the equivalent runtime settings in `compose.yaml`: + +```yaml +services: + agent: + build: + context: . + args: + TDC_VERSION: latest + devices: + - /dev/fuse:/dev/fuse + cap_add: + - SYS_ADMIN + security_opt: + - apparmor=unconfined + environment: + TDC_FS_TOKEN: ${TDC_FS_TOKEN} + TDC_REGION_CODE: ${TDC_REGION_CODE} + TDC_FS_FILE_SYSTEM_NAME: ${TDC_FS_FILE_SYSTEM_NAME} + stdin_open: true + tty: true +``` + +Start an interactive container with: + +```bash +docker compose run --rm agent +``` + +`fuse3` provides `/usr/bin/fusermount3`. If mounting reports `fusermount3: mount failed: Permission denied`, confirm that the host has `/dev/fuse` and that all required `devices`, `cap_add`, and AppArmor settings reached the container. `apparmor=unconfined` applies to AppArmor-enabled hosts such as Ubuntu and can be omitted where AppArmor is not active. + +> **Warning:** +> +> `SYS_ADMIN` and an unconfined AppArmor profile weaken container isolation. Use them only for a dedicated, trusted agent container. Rootless Docker and managed container platforms might prohibit these settings; use tdc fs data-plane commands without a mount when FUSE cannot be granted. The mount exists in the container mount namespace and disappears when the container stops, so drain and unmount before stopping a container that might have pending writes. + macOS intentionally keeps WebDAV as the automatic choice even when macFUSE is installed. To use FUSE, install a supported release from the [official macFUSE site](https://macfuse.github.io/), complete any approval or restart requested by its installer, and run: ```bash From 64cb6646a31eb8655111f01270902a4d6bbfd28b Mon Sep 17 00:00:00 2001 From: Cheese Date: Mon, 20 Jul 2026 23:53:20 +0800 Subject: [PATCH 05/29] docs: clarify filesystem lifecycle and mount paths --- .../concepts/tdc-concepts-and-architecture.md | 2 +- ai/tdc/examples/tdc-agent-sandbox-example.md | 20 ++++--- ai/tdc/examples/tdc-daily-workflow-example.md | 3 +- .../tdc-git-workspace-for-agents-example.md | 3 +- ...hare-filesystem-across-machines-example.md | 13 ++--- ai/tdc/guides/tdc-filesystem-git.md | 3 +- ai/tdc/guides/tdc-filesystem.md | 52 +++++++++++++++---- ai/tdc/guides/tdc-install-configure-update.md | 5 +- .../tdc-regions-security-and-limitations.md | 5 +- ai/tdc/reference/tdc-troubleshooting.md | 30 +++++++++-- ai/tdc/tdc-quick-start.md | 3 +- 11 files changed, 91 insertions(+), 48 deletions(-) diff --git a/ai/tdc/concepts/tdc-concepts-and-architecture.md b/ai/tdc/concepts/tdc-concepts-and-architecture.md index eed0164f523e5..748d56d6bf230 100644 --- a/ai/tdc/concepts/tdc-concepts-and-architecture.md +++ b/ai/tdc/concepts/tdc-concepts-and-architecture.md @@ -120,7 +120,7 @@ The companion owns: - FUSE and WebDAV mount processes, caches, drain, and unmount; - pack/unpack, Git workspace, journal, and vault semantics. -A background mount leaves a long-running `tdc-drive9 mount --foreground` process. `tdc fs drain-file-system` asks that process to flush pending FUSE work, and `tdc fs unmount-file-system` stops the mount. Do not terminate a machine with unflushed writes or local-only overlay data that you need to keep. +A background mount leaves a long-running `tdc-drive9 mount --foreground` process. `tdc fs unmount-file-system` gracefully flushes pending FUSE work and stops that process. `tdc fs drain-file-system` provides an explicit, reportable durability barrier while leaving a FUSE mount active so it can accept later writes. Do not abruptly terminate a machine with unflushed writes or local-only overlay data that you need to keep. ## What's next diff --git a/ai/tdc/examples/tdc-agent-sandbox-example.md b/ai/tdc/examples/tdc-agent-sandbox-example.md index a9da22eec7040..d7fdc8ce06b90 100644 --- a/ai/tdc/examples/tdc-agent-sandbox-example.md +++ b/ai/tdc/examples/tdc-agent-sandbox-example.md @@ -76,34 +76,32 @@ sandbox ready On Linux with FUSE: ```bash -mkdir -p /workspace +mkdir -p "$HOME/workspace" tdc fs mount-file-system \ --file-system-name agent-sandbox \ - --mount-path /workspace \ + --mount-path "$HOME/workspace" \ --driver fuse -cat /workspace/sandbox/status.txt +cat "$HOME/workspace/sandbox/status.txt" ``` -On macOS, omit `--driver fuse` to use the default WebDAV path. Use FUSE only after installing macFUSE. +Using a path under `$HOME` also avoids the default `fusermount3` AppArmor mount-path restriction on Ubuntu 26.04. On macOS, omit `--driver fuse` to use the default WebDAV path. Use FUSE only after installing macFUSE. After mounting, you can use `tdc fs-git`, `tdc fs-journal`, and owner-authorized `tdc fs-vault` commands with the same FS environment. Give agents a delegated `TDC_VAULT_TOKEN` instead of the owner token when they need only selected secret fields. ## Cleanup -Stop writers. For FUSE: +Stop writers and unmount. A graceful FUSE unmount automatically flushes and drains pending work: ```bash -tdc fs drain-file-system --mount-path /workspace -tdc fs unmount-file-system --mount-path /workspace +tdc fs unmount-file-system --mount-path "$HOME/workspace" ``` -For WebDAV, close files and run only unmount. Back on the trusted machine: +Use `tdc fs drain-file-system --mount-path "$HOME/workspace"` separately when you need to verify remote durability while keeping the mount online. Back on the trusted machine: ```bash tdc fs delete-file-system \ - --file-system-name agent-sandbox \ - --confirm-file-system-name agent-sandbox + --file-system-name agent-sandbox ``` ## Security notes @@ -111,7 +109,7 @@ tdc fs delete-file-system \ - Treat `TDC_FS_TOKEN` as an owner credential. - Do not place it in an image, repository, command flag, or operation log. - Deleting the sandbox does not delete the remote Filesystem. -- Draining is required before deleting a FUSE sandbox when pending writes must be durable. +- Graceful unmount drains pending FUSE writes; deleting the sandbox without unmounting does not. ## What's next diff --git a/ai/tdc/examples/tdc-daily-workflow-example.md b/ai/tdc/examples/tdc-daily-workflow-example.md index 655177738bbc6..b129ddcdb4927 100644 --- a/ai/tdc/examples/tdc-daily-workflow-example.md +++ b/ai/tdc/examples/tdc-daily-workflow-example.md @@ -91,8 +91,7 @@ tdc update ```bash tdc fs delete-file-system \ - --file-system-name daily-workspace \ - --confirm-file-system-name daily-workspace + --file-system-name daily-workspace tdc db delete-db-cluster \ --db-cluster-id "" diff --git a/ai/tdc/examples/tdc-git-workspace-for-agents-example.md b/ai/tdc/examples/tdc-git-workspace-for-agents-example.md index 6896ba7222bcd..c97105b31cd95 100644 --- a/ai/tdc/examples/tdc-git-workspace-for-agents-example.md +++ b/ai/tdc/examples/tdc-git-workspace-for-agents-example.md @@ -86,11 +86,10 @@ Commit or push required changes before removing the worktree. tdc fs-git remove-git-worktree \ --worktree-path /path/to/workspace/tidb-agent-task -tdc fs drain-file-system --mount-path /path/to/workspace tdc fs unmount-file-system --mount-path /path/to/workspace ``` -Use `--force` for worktree removal only when uncommitted changes can be discarded. +Use `--force` for worktree removal only when uncommitted changes can be discarded. Filesystem unmount performs a graceful drain automatically; use `tdc fs drain-file-system` separately only when you need to flush remote work without unmounting. ## Security and durability notes diff --git a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md index b79b1b5a4b2ea..7fc69e298aaa7 100644 --- a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md +++ b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md @@ -80,13 +80,7 @@ The first read proves data-plane writes are visible through the mount. The final ## Cleanup -Stop writers. If the mount is FUSE: - -```bash -tdc fs drain-file-system --mount-path /path/to/shared-workspace -``` - -Unmount either driver: +Stop writers and unmount either driver. A graceful FUSE unmount automatically drains pending work: ```bash tdc fs unmount-file-system --mount-path /path/to/shared-workspace @@ -97,15 +91,14 @@ On machine A: ```bash tdc fs delete-file-system \ - --file-system-name shared-workspace \ - --confirm-file-system-name shared-workspace + --file-system-name shared-workspace ``` ## Security notes - The FS token grants owner access. Transfer it as a secret, not in chat or command history. - Concurrent writers can overwrite the same paths; coordinate ownership at the workflow level. -- Do not terminate a machine before pending FUSE writes are drained. +- Do not terminate a machine before graceful unmount completes. Use an explicit drain only when you need remote durability while keeping the FUSE mount online. ## What's next diff --git a/ai/tdc/guides/tdc-filesystem-git.md b/ai/tdc/guides/tdc-filesystem-git.md index 5772e62c64976..a37d1ce392e60 100644 --- a/ai/tdc/guides/tdc-filesystem-git.md +++ b/ai/tdc/guides/tdc-filesystem-git.md @@ -89,8 +89,7 @@ Before terminating an ephemeral machine: 1. Commit or otherwise preserve required working-tree changes. 2. Remove linked worktrees you no longer need. -3. Drain the Filesystem mount. -4. Unmount it. +3. Unmount the Filesystem. Graceful unmount automatically drains pending FUSE work. The default coding-agent mount profile keeps `.git` and rebuildable generated files in local overlay storage. Preserve or pack that local state when it must survive machine deletion. diff --git a/ai/tdc/guides/tdc-filesystem.md b/ai/tdc/guides/tdc-filesystem.md index c9554e63eb194..eaa25e337ed8d 100644 --- a/ai/tdc/guides/tdc-filesystem.md +++ b/ai/tdc/guides/tdc-filesystem.md @@ -66,8 +66,7 @@ Delete a resource only after removing data you need: ```bash tdc fs delete-file-system \ - --file-system-name workspace \ - --confirm-file-system-name workspace + --file-system-name workspace ``` Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and a locally registered resource; an FS token alone cannot delete the resource. Drive9 deletion is asynchronous, so a successfully accepted request reports `status: "deleting"` while tdc removes the selected local registry entry and credential. @@ -264,7 +263,6 @@ The three environment variables must already exist in the host shell. Inside the ```bash tdc fs mount --mount-path /workspace printf 'hello from Docker\n' > /workspace/hello.txt -tdc fs drain --mount-path /workspace tdc fs umount --mount-path /workspace ``` @@ -301,7 +299,7 @@ docker compose run --rm agent > **Warning:** > -> `SYS_ADMIN` and an unconfined AppArmor profile weaken container isolation. Use them only for a dedicated, trusted agent container. Rootless Docker and managed container platforms might prohibit these settings; use tdc fs data-plane commands without a mount when FUSE cannot be granted. The mount exists in the container mount namespace and disappears when the container stops, so drain and unmount before stopping a container that might have pending writes. +> `SYS_ADMIN` and an unconfined AppArmor profile weaken container isolation. Use them only for a dedicated, trusted agent container. Rootless Docker and managed container platforms might prohibit these settings; use tdc fs data-plane commands without a mount when FUSE cannot be granted. The mount exists in the container mount namespace and disappears when the container stops, so wait for graceful unmount to succeed before stopping a container that might have pending writes. macOS intentionally keeps WebDAV as the automatic choice even when macFUSE is installed. To use FUSE, install a supported release from the [official macFUSE site](https://macfuse.github.io/), complete any approval or restart requested by its installer, and run: @@ -325,28 +323,62 @@ tdc fs mount-file-system \ --read-cache-ttl 30s ``` +### Ubuntu 26.04 mount paths + +Ubuntu 26.04 enforces an AppArmor profile for `/usr/bin/fusermount3`. The default profile allows FUSE mounts under the current user's home directory, `/mnt`, `/media`, `/tmp`, and `/run/user/`, but not directly under `/workspace`. This restriction applies to root as well as non-root users and produces an error similar to `/usr/bin/fusermount3: mount failed: Permission denied`. + +Prefer an allowed mount path: + +```bash +mkdir -p "$HOME/workspace" +tdc fs mount-file-system \ + --file-system-name workspace \ + --mount-path "$HOME/workspace" +``` + +For a system-level path, `/mnt/workspace` is allowed by the default profile: + +```bash +sudo mkdir -p /mnt/workspace +sudo chown "$(id -u):$(id -g)" /mnt/workspace +tdc fs mount-file-system \ + --file-system-name workspace \ + --mount-path /mnt/workspace +``` + +If an application requires `/workspace`, add the following rules to `/etc/apparmor.d/local/fusermount3`, and then reload the profile with `sudo apparmor_parser -r /etc/apparmor.d/fusermount3`: + +```text +mount fstype=@{fuse_types} options=(nosuid,nodev) options in (ro,rw,noatime,dirsync,nodiratime,noexec,sync) -> /workspace/{,**/}, +umount /workspace/{,**/}, +``` + The default mount profile is `coding-agent`, which keeps common development state such as dependencies, caches, generated output, and Git internals in a local overlay. Those local-only files do not survive machine deletion unless you pack or preserve the local volume. Use `--mount-profile portable` when you want automatic portable pack behavior, or `none` when you do not want the coding-agent overlay policy. ## Drain and unmount -Stop writers and close open files before cleanup. For FUSE: +Stop writers and close open files before cleanup. A normal unmount performs a graceful shutdown: the companion flushes open handles and pending FUSE write-back work, waits for its upload queues, and then exits. You do not need to run drain first: + +```bash +tdc fs unmount-file-system \ + --mount-path /path/to/workspace +``` + +Use drain when you need an explicit durability barrier while keeping a FUSE mount online, for example before handing the mount to another process or checking remote visibility: ```bash tdc fs drain-file-system \ --mount-path /path/to/workspace \ --timeout 30s - -tdc fs unmount-file-system \ - --mount-path /path/to/workspace ``` -Drain waits for dirty handles and pending writes. It is not supported for WebDAV. `unmount-file-system` also supports `--timeout`, `--force`, `--ignore-absent`, `--pack-archive-path`, and `--no-auto-pack`. +Drain flushes dirty handles and waits for pending writes, but the mount remains available and can accept new writes afterward. It is not supported for WebDAV. `unmount-file-system` also supports `--timeout`, `--force`, `--ignore-absent`, `--pack-archive-path`, and `--no-auto-pack`. A successful background mount writes a non-secret locator under `~/.tdc/mounts/`. Drain and unmount can use that locator from the same `HOME` without `TDC_FS_TOKEN` or `TDC_REGION_CODE`. > **Warning:** > -> Do not terminate a sandbox or virtual machine while writes remain pending. Remote-committed data survives, but in-memory writes, write-back data on a deleted local disk, and coding-agent local-only files can be lost. +> Do not terminate a sandbox or virtual machine while writes remain pending or after unmount returns a timeout or error. Remote-committed data survives, but in-memory writes, write-back data on a deleted local disk, and coding-agent local-only files can be lost. ## Unix-style aliases diff --git a/ai/tdc/guides/tdc-install-configure-update.md b/ai/tdc/guides/tdc-install-configure-update.md index bcb1461765708..7e0fb98c4f10e 100644 --- a/ai/tdc/guides/tdc-install-configure-update.md +++ b/ai/tdc/guides/tdc-install-configure-update.md @@ -123,15 +123,14 @@ Install a specific tdc release: tdc update --target-version v0.1.2 ``` -The update command replaces both binaries in the user-owned install directory. An active Filesystem mount keeps running the already loaded companion process. To avoid mixing the old mount runtime with new CLI commands, stop writers, drain FUSE mounts, and unmount before updating: +The update command replaces both binaries in the user-owned install directory. An active Filesystem mount keeps running the already loaded companion process. To avoid mixing the old mount runtime with new CLI commands, stop writers and unmount before updating. Graceful unmount automatically flushes and drains pending FUSE work: ```bash -tdc fs drain-file-system --mount-path /path/to/workspace tdc fs unmount-file-system --mount-path /path/to/workspace tdc update ``` -For WebDAV, close writers and unmount; drain is FUSE-only. Installations in protected or package-manager-owned locations are not modified. Run the installer once to migrate an older `/usr/local/bin` installation to `~/.tdc/bin`. +For WebDAV, close writers and unmount. Use the FUSE-only drain command separately only when you need a durability barrier without unmounting. Installations in protected or package-manager-owned locations are not modified. Run the installer once to migrate an older `/usr/local/bin` installation to `~/.tdc/bin`. ## Uninstall tdc diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/tdc/reference/tdc-regions-security-and-limitations.md index 9b7fed86f189f..0968e2214ff57 100644 --- a/ai/tdc/reference/tdc-regions-security-and-limitations.md +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -71,10 +71,13 @@ TiDB Cloud API calls use Digest authentication. SQL HTTPS execution uses generat FUSE and WebDAV are implemented by the bundled [Drive9](https://github.com/mem9-ai/drive9) companion. tdc does not fall back to a separate native mount implementation. +Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path under `$HOME` or `/mnt`; `/workspace` requires an explicit local AppArmor rule even when tdc runs as root. + ## Durability limitations - Default FUSE behavior uses local buffering and asynchronous remote work where permitted by the companion. -- `drain-file-system` is FUSE-only. +- A successful `unmount-file-system` gracefully flushes and drains FUSE work; a separate drain is not required first. +- `drain-file-system` is a FUSE-only online durability barrier that leaves the mount active. - Abruptly killing the mount process or deleting a machine can lose uncommitted memory/write-back state. - The default coding-agent mount profile stores dependency trees, generated output, caches, and Git internals locally. Local-only data disappears when its disk disappears unless it is packed or otherwise preserved. - A running mount remains on the companion version loaded at mount time. Unmount and remount after updating tdc. diff --git a/ai/tdc/reference/tdc-troubleshooting.md b/ai/tdc/reference/tdc-troubleshooting.md index eb73ce5c4fd39..e2b2429087825 100644 --- a/ai/tdc/reference/tdc-troubleshooting.md +++ b/ai/tdc/reference/tdc-troubleshooting.md @@ -143,6 +143,30 @@ tdc fs mount-file-system \ Linux needs FUSE3 and access to `/dev/fuse`. Windows WebDAV needs the WebClient service and a drive letter such as `X:`. +## Ubuntu 26.04 rejects a FUSE mount under `/workspace` + +Ubuntu 26.04 applies an AppArmor profile to `fusermount3`. Its default mount-path allowlist does not include `/workspace`, so root and non-root users can both receive: + +```text +/usr/bin/fusermount3: mount failed: Permission denied +``` + +Confirm the denial: + +```bash +sudo journalctl -k --since "10 minutes ago" | + grep 'profile="fusermount3"' +``` + +An entry with `operation="mount"`, `name="/workspace/"`, and `info="failed mntpnt match"` identifies this restriction. Mount under `$HOME` or `/mnt` instead: + +```bash +mkdir -p "$HOME/workspace" +tdc fs mount-file-system --mount-path "$HOME/workspace" +``` + +Changing the owner or mode of `/workspace` does not bypass AppArmor. If the path cannot change, add explicit `/workspace` mount and unmount rules to `/etc/apparmor.d/local/fusermount3` as described in [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md#ubuntu-2604-mount-paths). + ## Mount becomes stale after a process crash If the companion is killed without graceful unmount, FUSE access can return `EIO` or `Transport endpoint is not connected`. Stop processes with open files, then try: @@ -157,14 +181,13 @@ Use `--ignore-absent` when cleanup should succeed if no locator remains. Abrupt ## Unmount reports busy -Close editors, shells whose working directory is inside the mount, and other open file handles. For FUSE, drain before retrying: +Close editors, shells whose working directory is inside the mount, and other open file handles, and then retry: ```bash -tdc fs drain-file-system --mount-path /path/to/workspace --timeout 30s tdc fs unmount-file-system --mount-path /path/to/workspace ``` -Do not use drain for WebDAV. +Unmount performs the graceful FUSE drain automatically. Running `drain-file-system` separately does not close file descriptors or resolve a busy mount; use it only when you need to flush pending work while leaving the mount online. Drain is not supported for WebDAV. ## An interrupted command leaves resources @@ -181,7 +204,6 @@ Preview supported cleanup: tdc db delete-db-cluster --db-cluster-id "" --dry-run tdc fs delete-file-system \ --file-system-name "" \ - --confirm-file-system-name "" \ --dry-run ``` diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index e0bded03a34db..2f14c13877049 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -101,8 +101,7 @@ Clean up: ```bash tdc fs delete-file-system \ - --file-system-name quickstart-fs \ - --confirm-file-system-name quickstart-fs + --file-system-name quickstart-fs ``` ### Option B: Query a Starter database From 977c8a596cc0a411797af1d1782dabf837178190 Mon Sep 17 00:00:00 2001 From: Cheese Date: Tue, 21 Jul 2026 15:21:10 +0800 Subject: [PATCH 06/29] docs: document root command usage error --- ai/tdc/reference/tdc-cli-reference.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md index cebe12aeb9059..b98cee16cdff3 100644 --- a/ai/tdc/reference/tdc-cli-reference.md +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -85,6 +85,23 @@ Read-only commands reject `--dry-run`. Dry-run is not a general global simulatio ## Help and version forms +Running `tdc` without a command returns exit code `2` and prints a compact command-tree synopsis to stderr: + +```text +tdc [ERROR]: the following arguments are required: command + +The TiDB Cloud Command Line Interface is a unified tool to manage your TiDB Cloud Filesystem (FS) and Starter services. + +usage: tdc [ ...] [parameters] +To see help information, you can run: + + tdc help + tdc help + tdc help +``` + +Use an explicit help form to display commands and flags: + ```bash tdc help tdc db help From 5b982012db3df30e19a8c00c3f967607155e6e0a Mon Sep 17 00:00:00 2001 From: Cheese Date: Tue, 21 Jul 2026 17:13:36 +0800 Subject: [PATCH 07/29] docs: correct root command depth --- ai/tdc/reference/tdc-cli-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md index b98cee16cdff3..7c87880410d7b 100644 --- a/ai/tdc/reference/tdc-cli-reference.md +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -92,7 +92,7 @@ tdc [ERROR]: the following arguments are required: command The TiDB Cloud Command Line Interface is a unified tool to manage your TiDB Cloud Filesystem (FS) and Starter services. -usage: tdc [ ...] [parameters] +usage: tdc [] [parameters] To see help information, you can run: tdc help From 7079820d4a958dccb5783f0f80c65b4af9f02359 Mon Sep 17 00:00:00 2001 From: Cheese Date: Tue, 21 Jul 2026 18:08:23 +0800 Subject: [PATCH 08/29] docs: document tdc help flag formatting --- ai/tdc/reference/tdc-cli-reference.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md index 7c87880410d7b..a33cb0c1c5f2a 100644 --- a/ai/tdc/reference/tdc-cli-reference.md +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -28,6 +28,13 @@ tdc db describe-db-cluster [--view ] ``` +In the generated `Flags` and `Global Flags` sections, value types are enclosed in angle brackets and required flags include `(required)` after the flag name and type: + +```text +--db-cluster-name (required) Starter DB cluster display name +--project-id TiDB Cloud project ID +``` + ## Global flags | Flag | Description | @@ -117,7 +124,7 @@ tdc fs --version ## Errors and exit behavior -Human-readable errors use a stable prefix: +Human-readable errors start with a blank line and use a stable prefix: ```text tdc [ERROR]: From 775717eb6ab206cb0b53ef30837a3a45e784464b Mon Sep 17 00:00:00 2001 From: Cheese Date: Wed, 22 Jul 2026 16:50:56 +0800 Subject: [PATCH 09/29] Apply suggestions from code review Co-authored-by: Grace Cai --- TOC-ai.md | 41 ++++++++++++++++++++--------------------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/TOC-ai.md b/TOC-ai.md index cbf1494523e9f..9feb117ecd295 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -5,17 +5,16 @@ ## QUICK START -- [Get Started via Python](/ai/quickstart-via-python.md) -- [Get Started via SQL](/ai/quickstart-via-sql.md) -- TiDB Cloud CLI (tdc) (Preview) - - [Overview](/ai/tdc/tdc-overview.md) - - [Quick Start](/ai/tdc/tdc-quick-start.md) +- [Get Started with Vector Search via Python](/ai/quickstart-via-python.md) +- [Get Started with Vector Search via SQL](/ai/quickstart-via-sql.md) +- [Get Started with TiDB Cloud CLI (tdc)](/ai/tdc-quick-start.md) ## CONCEPTS - [Vector Search](/ai/concepts/vector-search-overview.md) -- TiDB Cloud CLI (tdc) (Preview) - - [Concepts and Architecture](/ai/tdc/concepts/tdc-concepts-and-architecture.md) +- TiDB Cloud CLI (tdc) + - [Overview](/ai/tdc/tdc-overview.md) + - [Concepts and Architecture](/ai/tdc/concepts/tdc-concepts-and-architecture.md) ## GUIDES @@ -35,14 +34,14 @@ - [Join Queries](/ai/guides/join-queries.md) - [Raw SQL Queries](/ai/guides/raw-queries.md) - [Transactions](/ai/guides/transactions.md) -- TiDB Cloud CLI (tdc) (Preview) +- Manage Starter Instances and File System via TiDB Cloud CLI (tdc) - [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) - - [Organization](/ai/tdc/guides/tdc-organization.md) - - [Starter Database](/ai/tdc/guides/tdc-starter-database.md) - - [Filesystem](/ai/tdc/guides/tdc-filesystem.md) - - [Filesystem Git](/ai/tdc/guides/tdc-filesystem-git.md) - - [Filesystem Journal](/ai/tdc/guides/tdc-filesystem-journal.md) - - [Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) + - [Manage Organizations and Projects](/ai/tdc/guides/tdc-organization.md) + - [Manage Starter Databases and SQL Access](/ai/tdc/guides/tdc-starter-database.md) + - [Manage Cloud Filesystem Resources](/ai/tdc/guides/tdc-filesystem.md) + - [Use Git Workspaces on Cloud Filesystem](/ai/tdc/guides/tdc-filesystem-git.md) + - [Track Changes with Filesystem Journals](/ai/tdc/guides/tdc-filesystem-journal.md) + - [Manage Secrets with Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) ## EXAMPLES @@ -58,13 +57,13 @@ - [Conversational Memory](/ai/examples/memory-with-pytidb.md) - [Text-to-SQL](/ai/examples/text2sql-with-pytidb.md) - TiDB Cloud CLI (tdc) (Preview) - - [Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) - - [Daily Workflow](/ai/tdc/examples/tdc-daily-workflow-example.md) - - [Query SQL with Roles](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) - - [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) - - [Git Workspace for Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) - - [Journal an Agent Workflow](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) - - [Delegate Vault Secrets](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) + - [Set Up an Agent Sandbox Environment](/ai/tdc/examples/tdc-agent-sandbox-example.md) + - [Automate Daily Database Operations](/ai/tdc/examples/tdc-daily-workflow-example.md) + - [Run SQL Queries with Role-Based Access](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) + - [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) + - [Set Up a Git Workspace for AI Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) + - [Record Agent Workflows in a Journal](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) + - [Delegate Secrets Securely to Agents](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) ## INTEGRATIONS From a9d82a20af9c0a54b5cdcf1a4b62d8b15f89d4a8 Mon Sep 17 00:00:00 2001 From: Cheese Date: Wed, 22 Jul 2026 18:34:06 +0800 Subject: [PATCH 10/29] docs: clarify tdc workflows and CLI transition --- TOC-ai.md | 50 +++++++------- TOC-tidb-cloud-essential.md | 4 +- TOC-tidb-cloud-starter.md | 4 +- ai/_index.md | 19 ++++-- .../concepts/tdc-concepts-and-architecture.md | 8 +++ ai/tdc/guides/tdc-organization.md | 4 +- .../tdc-regions-security-and-limitations.md | 18 ++--- ai/tdc/tdc-overview.md | 66 ++++++++++++++----- ai/tdc/tdc-quick-start.md | 4 ++ tidb-cloud/cli-reference.md | 12 ++-- tidb-cloud/get-started-with-cli.md | 12 ++-- 11 files changed, 134 insertions(+), 67 deletions(-) diff --git a/TOC-ai.md b/TOC-ai.md index 9feb117ecd295..ae6c2de0ae09a 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -5,16 +5,16 @@ ## QUICK START -- [Get Started with Vector Search via Python](/ai/quickstart-via-python.md) -- [Get Started with Vector Search via SQL](/ai/quickstart-via-sql.md) -- [Get Started with TiDB Cloud CLI (tdc)](/ai/tdc-quick-start.md) +- [Get Started with Vector Search via Python](/ai/quickstart-via-python.md) +- [Get Started with Vector Search via SQL](/ai/quickstart-via-sql.md) +- [Get Started with TiDB Cloud CLI (tdc)](/ai/tdc/tdc-quick-start.md) ## CONCEPTS - [Vector Search](/ai/concepts/vector-search-overview.md) -- TiDB Cloud CLI (tdc) - - [Overview](/ai/tdc/tdc-overview.md) - - [Concepts and Architecture](/ai/tdc/concepts/tdc-concepts-and-architecture.md) +- TiDB Cloud CLI (tdc) + - [Overview](/ai/tdc/tdc-overview.md) + - [Concepts and Architecture](/ai/tdc/concepts/tdc-concepts-and-architecture.md) ## GUIDES @@ -27,21 +27,22 @@ - [Full-Text Search via SQL](/ai/guides/vector-search-full-text-search-sql.md) - [Hybrid Search](/ai/guides/vector-search-hybrid-search.md) - [Image Search](/ai/guides/image-search.md) -- Advanced Features +- Advanced Search Features - [Auto Embedding](/ai/guides/auto-embedding.md) - [Filtering](/ai/guides/filtering.md) - [Reranking](/ai/guides/reranking.md) - [Join Queries](/ai/guides/join-queries.md) - [Raw SQL Queries](/ai/guides/raw-queries.md) - [Transactions](/ai/guides/transactions.md) -- Manage Starter Instances and File System via TiDB Cloud CLI (tdc) +- Manage Starter Instances and File System via TiDB Cloud CLI (tdc) - [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) - - [Manage Organizations and Projects](/ai/tdc/guides/tdc-organization.md) - - [Manage Starter Databases and SQL Access](/ai/tdc/guides/tdc-starter-database.md) - - [Manage Cloud Filesystem Resources](/ai/tdc/guides/tdc-filesystem.md) - - [Use Git Workspaces on Cloud Filesystem](/ai/tdc/guides/tdc-filesystem-git.md) - - [Track Changes with Filesystem Journals](/ai/tdc/guides/tdc-filesystem-journal.md) - - [Manage Secrets with Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) + - [Manage Projects in TiDB Cloud Organizations](/ai/tdc/guides/tdc-organization.md) + - [Manage Starter Databases and SQL Access](/ai/tdc/guides/tdc-starter-database.md) + - [Manage Cloud Filesystem Resources](/ai/tdc/guides/tdc-filesystem.md) + - [Use Git Workspaces on Cloud Filesystem](/ai/tdc/guides/tdc-filesystem-git.md) + - [Track Changes with Filesystem Journals](/ai/tdc/guides/tdc-filesystem-journal.md) + - [Manage Secrets with Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) + - [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) ## EXAMPLES @@ -56,14 +57,16 @@ - [RAG Application](/ai/examples/rag-with-pytidb.md) - [Conversational Memory](/ai/examples/memory-with-pytidb.md) - [Text-to-SQL](/ai/examples/text2sql-with-pytidb.md) -- TiDB Cloud CLI (tdc) (Preview) - - [Set Up an Agent Sandbox Environment](/ai/tdc/examples/tdc-agent-sandbox-example.md) - - [Automate Daily Database Operations](/ai/tdc/examples/tdc-daily-workflow-example.md) - - [Run SQL Queries with Role-Based Access](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) - - [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) - - [Set Up a Git Workspace for AI Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) - - [Record Agent Workflows in a Journal](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) - - [Delegate Secrets Securely to Agents](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) +- TiDB Cloud CLI (tdc) + - For Users and Automation + - [Automate Daily Database Operations](/ai/tdc/examples/tdc-daily-workflow-example.md) + - [Run SQL Queries with Role-Based Access](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) + - [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) + - For AI Agents + - [Set Up an Agent Sandbox Environment](/ai/tdc/examples/tdc-agent-sandbox-example.md) + - [Set Up a Git Workspace for AI Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) + - [Record Agent Workflows in a Journal](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) + - [Delegate Secrets Securely to Agents](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) ## INTEGRATIONS @@ -104,8 +107,7 @@ - [Performance Tuning](/ai/reference/vector-search-improve-performance.md) - [Limitations](/ai/reference/vector-search-limitations.md) - [Changelogs](/ai/reference/vector-search-changelogs.md) -- TiDB Cloud CLI (tdc) (Preview) +- TiDB Cloud CLI (tdc) - [CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) - [Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) - [Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) - - [Troubleshooting](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index 8ff041c162ee8..130ec98cb10a7 100644 --- a/TOC-tidb-cloud-essential.md +++ b/TOC-tidb-cloud-essential.md @@ -12,7 +12,7 @@ - Get Started - [Try Out TiDB Cloud](/tidb-cloud/tidb-cloud-quickstart.md) - [Try Out HTAP](/tidb-cloud/tidb-cloud-htap-quickstart.md) - - [Try Out TiDB Cloud CLI](/tidb-cloud/get-started-with-cli.md) + - [Try Out TiDB Cloud CLI (ticloud, Legacy)](/tidb-cloud/get-started-with-cli.md) - Key Concepts - [Overview](/tidb-cloud/key-concepts.md) - [Architecture](/tidb-cloud/architecture-concepts.md) @@ -457,7 +457,7 @@ - [`schema_unused_indexes`](/sys-schema/sys-schema-unused-indexes.md) - [Metadata Lock](/metadata-lock.md) - [TiDB Accelerated Table Creation](/accelerated-table-creation.md) -- CLI Reference ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) +- TiDB Cloud CLI (ticloud, Legacy) Reference ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) - [Overview](/tidb-cloud/cli-reference.md) - auth - [login](/tidb-cloud/ticloud-auth-login.md) diff --git a/TOC-tidb-cloud-starter.md b/TOC-tidb-cloud-starter.md index 729b4b716101a..c5ebaa552b356 100644 --- a/TOC-tidb-cloud-starter.md +++ b/TOC-tidb-cloud-starter.md @@ -13,7 +13,7 @@ - [Try Out TiDB Cloud](/tidb-cloud/tidb-cloud-quickstart.md) - [Try Out TiDB + AI Tools](/tidb-cloud/use-tidb-cloud-with-ai-tools.md) - [Try Out HTAP](/tidb-cloud/tidb-cloud-htap-quickstart.md) - - [Try Out TiDB Cloud CLI](/tidb-cloud/get-started-with-cli.md) + - [Try Out TiDB Cloud CLI (ticloud, Legacy)](/tidb-cloud/get-started-with-cli.md) - Key Concepts - [Overview](/tidb-cloud/key-concepts.md) - [Architecture](/tidb-cloud/architecture-concepts.md) @@ -461,7 +461,7 @@ - [`schema_unused_indexes`](/sys-schema/sys-schema-unused-indexes.md) - [Metadata Lock](/metadata-lock.md) - [TiDB Accelerated Table Creation](/accelerated-table-creation.md) -- CLI Reference ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) +- TiDB Cloud CLI (ticloud, Legacy) Reference ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) - [Overview](/tidb-cloud/cli-reference.md) - auth - [login](/tidb-cloud/ticloud-auth-login.md) diff --git a/ai/_index.md b/ai/_index.md index fbb035e71d94c..b9e030f93b0fb 100644 --- a/ai/_index.md +++ b/ai/_index.md @@ -20,7 +20,7 @@ Get up and running quickly with TiDB's AI capabilities. | Document | Description | | --- | --- | -| [tdc Overview](/ai/tdc/tdc-overview.md) | Understand what tdc manages and how it uses its bundled Filesystem companion. | +| [tdc Overview](/ai/tdc/tdc-overview.md) | Learn when to use tdc, how it differs from the legacy ticloud CLI and TiDB Cloud console, and which Starter and Filesystem workflows it supports. | | [Get Started with tdc](/ai/tdc/tdc-quick-start.md) | Install and configure tdc, then complete a first database or Filesystem operation. | ## Concepts @@ -49,15 +49,18 @@ Step-by-step guides for building AI applications with TiDB using the [`pytidb`]( ### TiDB Cloud CLI (tdc) (Preview) +Use these guides to complete a focused task or manage one tdc feature area. + | Document | Description | | --- | --- | | [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) | Install release binaries, configure profiles, update, and uninstall tdc. | -| [Organization](/ai/tdc/guides/tdc-organization.md) | List projects and understand virtual-project selection. | +| [Manage Projects in TiDB Cloud Organizations with tdc](/ai/tdc/guides/tdc-organization.md) | List projects and understand virtual-project selection. | | [Starter Database](/ai/tdc/guides/tdc-starter-database.md) | Manage clusters, branches, SQL users, connection strings, and SQL execution. | | [Filesystem](/ai/tdc/guides/tdc-filesystem.md) | Manage resources, data, layers, packs, and FUSE or WebDAV mounts. | | [Filesystem Git](/ai/tdc/guides/tdc-filesystem-git.md) | Clone, hydrate, and manage linked Git worktrees. | | [Filesystem Journal](/ai/tdc/guides/tdc-filesystem-journal.md) | Record, search, and verify append-only workflow events. | | [Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) | Store secrets, delegate access, audit, inject, and mount a read-only vault. | +| [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) | Diagnose authentication, quota, SQL, companion, selection, and mount failures. | ## Examples @@ -74,12 +77,21 @@ Complete code examples and demos showcasing TiDB's AI capabilities. ### TiDB Cloud CLI (tdc) (Preview) +These examples combine multiple commands into end-to-end scenarios. Choose a workflow based on who runs it. + +#### For users and automation + | Document | Description | | --- | --- | -| [Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) | Give a clean sandbox Filesystem access without TiDB Cloud API keys. | | [Daily Workflow](/ai/tdc/examples/tdc-daily-workflow-example.md) | Manage one Starter cluster and Filesystem in a routine operator flow. | | [Query SQL with Roles](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) | Use explicit read-only, read-write, and admin SQL roles. | | [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) | Transfer an owner token securely and verify cross-machine visibility. | + +#### For AI agents + +| Document | Description | +| --- | --- | +| [Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) | Give a clean sandbox Filesystem access without TiDB Cloud API keys. | | [Git Workspace for Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) | Prepare a mounted Git workspace and isolated linked worktree. | | [Journal an Agent Workflow](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) | Record structured events and verify their hash chain. | | [Delegate Vault Secrets](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) | Grant an agent temporary access to one secret field. | @@ -115,4 +127,3 @@ Technical reference documentation for TiDB's AI and vector search features. | [CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) | Global flags, output, queries, dry-run, help, errors, and aliases. | | [Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) | Profiles, precedence, local state, credentials, mount locators, and logs. | | [Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) | Placement, authentication boundaries, platforms, durability, and Preview constraints. | -| [Troubleshooting](/ai/tdc/reference/tdc-troubleshooting.md) | Diagnose authentication, quota, SQL, companion, selection, and mount failures. | diff --git a/ai/tdc/concepts/tdc-concepts-and-architecture.md b/ai/tdc/concepts/tdc-concepts-and-architecture.md index 748d56d6bf230..1b00611596d81 100644 --- a/ai/tdc/concepts/tdc-concepts-and-architecture.md +++ b/ai/tdc/concepts/tdc-concepts-and-architecture.md @@ -25,6 +25,14 @@ The command tree is at most two levels. Long, descriptive command and flag names Structured commands return JSON by default. Use `--output text` for a terminal-oriented representation and `--query` for a JMESPath projection. +## Product boundaries + +tdc is the new CLI for TiDB Cloud Starter and TiDB Cloud Filesystem. It is intended for users, scripts, CI jobs, and AI agents that need predictable non-interactive commands and structured output. + +The legacy `ticloud` CLI manages TiDB Cloud Starter and Essential. During the transition to tdc, continue to use `ticloud` for Essential and for operations that tdc does not yet expose, including import, export, and audit-log commands. The `ticloud` CLI will be gradually retired as supported workflows move to tdc. + +The TiDB Cloud console remains the browser-based interface for visual inspection and guided manual operations. Choosing tdc does not prevent you from using the console against the same cloud resources. + ## Profiles and regions A profile is a named local namespace containing TiDB Cloud placement, a default virtual project, and credentials. The default profile is named `default`; select another with `--profile`. diff --git a/ai/tdc/guides/tdc-organization.md b/ai/tdc/guides/tdc-organization.md index fc0a923afd974..f872e3ec4ba9d 100644 --- a/ai/tdc/guides/tdc-organization.md +++ b/ai/tdc/guides/tdc-organization.md @@ -1,9 +1,9 @@ --- -title: Manage TiDB Cloud Organizations with tdc +title: Manage Projects in TiDB Cloud Organizations with tdc summary: List accessible TiDB Cloud projects and understand regular and virtual project types used by tdc. --- -# Manage TiDB Cloud Organizations with tdc +# Manage Projects in TiDB Cloud Organizations with tdc Use `tdc organization` to inspect the projects accessible to the configured TiDB Cloud API key. diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/tdc/reference/tdc-regions-security-and-limitations.md index 0968e2214ff57..7e6bafc1891ac 100644 --- a/ai/tdc/reference/tdc-regions-security-and-limitations.md +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -52,14 +52,16 @@ The hosted manifest is authoritative and can change during Preview. A profile in TiDB Cloud API calls use Digest authentication. SQL HTTPS execution uses generated SQL username/password Basic authentication over TLS. These credentials are not interchangeable. -## Security guidance - -- Prefer environment variables or protected credential files for secrets. -- Use explicit read-only, read-write, or admin roles for SQL. -- Give agents delegated vault grants instead of FS owner tokens when only secret access is required. -- Use `--dry-run` before destructive control-plane operations. -- Keep `~/.tdc/credentials`, resource credentials, and DB SQL credentials owner-readable only. -- Review local operation logs before sharing diagnostics even though tdc redacts known secret classes. +## Security best practices + +- Create TiDB Cloud API keys with only the organization and project access required for the workflow. Do not reuse a personal administrator key in unattended automation. +- Inject automation credentials from a CI secret store or runtime secret manager. Do not place credentials in source control, container images, shell scripts, or command-line arguments that can appear in process listings and shell history. +- Do not copy the complete `~/.tdc/` directory into an agent sandbox. For an existing Filesystem, pass only `TDC_FS_TOKEN`, `TDC_REGION_CODE`, and `TDC_FS_FILE_SYSTEM_NAME`. +- Treat an FS owner token as full access to that Filesystem. When an agent needs only selected secrets, create a vault grant with the narrowest field scope and shortest practical TTL, and pass the delegated vault token instead. +- Use `--read-only` for SQL inspection by untrusted or exploratory agents. Use `--admin` only for DDL or privilege management, and use `--read-write` only when data changes are intended. +- Use `--dry-run` before destructive control-plane operations. Keep `~/.tdc/credentials`, resource credentials, and DB SQL credentials owner-readable only. +- Grant Docker access to `/dev/fuse`, `SYS_ADMIN`, and an unconfined AppArmor profile only to dedicated, trusted containers. These settings reduce container isolation. +- Review local operation logs before sharing diagnostics. tdc redacts known secret classes, but SQL text, resource names, paths, and operational context can still be sensitive. ## Mount platform limitations diff --git a/ai/tdc/tdc-overview.md b/ai/tdc/tdc-overview.md index f7d0c0fb2cbdf..a5577046446d8 100644 --- a/ai/tdc/tdc-overview.md +++ b/ai/tdc/tdc-overview.md @@ -1,27 +1,50 @@ --- title: TiDB Cloud CLI (tdc) Overview -summary: Learn how the Preview tdc command-line interface manages TiDB Cloud Starter databases and TiDB Cloud Filesystem for users, scripts, and AI agents. +summary: Learn when to use the Preview tdc command-line interface to manage TiDB Cloud Starter databases and persistent Filesystems for users, automation, and AI agents. --- # TiDB Cloud CLI (tdc) Overview -tdc is a command-line interface for managing TiDB Cloud Starter databases and TiDB Cloud Filesystem. It provides deterministic JSON output, explicit permissions, scriptable configuration, and commands designed for both users and AI agents. +tdc is the new TiDB Cloud command-line interface 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. > **Note:** > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. -## What you can do with tdc +## When to use tdc -With tdc, you can: +Use tdc when a workflow needs to manage TiDB Cloud from a terminal, script, CI job, or AI agent environment. Typical scenarios include: -- create, inspect, update, and delete TiDB Cloud Starter clusters; -- create and manage Starter branches; -- create read-only, read-write, and admin SQL users, format connection strings, and execute SQL; -- create and select multiple TiDB Cloud Filesystem resources in one profile; -- access Filesystem data directly or mount it through FUSE or WebDAV; -- use Filesystem layers, packs, Git workspaces, append-only journals, and delegated secrets; -- use JSON output and JMESPath queries in scripts and agent workflows. +- **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 legacy CLI operations that tdc does not yet provide, continue to use `ticloud` during the transition. + +## tdc, ticloud, and the TiDB Cloud console + +TiDB Cloud currently has two command-line interfaces. `tdc` is the new CLI and `ticloud` is the legacy CLI that is being gradually replaced. + +| Interface | Use it for | Interaction model | +| --- | --- | --- | +| `tdc` (Preview) | New TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows | Predictable commands, JSON output by default, and non-interactive operation except for `tdc configure` | +| `ticloud` (legacy) | TiDB Cloud Essential and operations not yet available in tdc, such as import, export, and audit-log commands | Traditional CLI workflows with interactive and non-interactive modes | +| TiDB Cloud console | Visual resource inspection, guided setup, and manual operations | Browser-based and interactive | + +New Starter and Filesystem automation should use tdc. During the transition, keep `ticloud` for Essential and any command that has no tdc equivalent. The legacy `ticloud` CLI will be gradually retired as its supported workflows move to tdc. + +## What tdc manages + +tdc 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. tdc has a two-level command model: @@ -37,27 +60,37 @@ tdc installs a bundled [Drive9](https://github.com/mem9-ai/drive9) companion nam You do not need to install, configure, or invoke Drive9 separately for normal tdc workflows. -## Start using tdc +## Find the right documentation -- [Quick Start](/ai/tdc/tdc-quick-start.md) -- [Concepts and Architecture](/ai/tdc/concepts/tdc-concepts-and-architecture.md) +- Follow the [Quick Start](/ai/tdc/tdc-quick-start.md) to install tdc and complete your first Starter or Filesystem workflow. +- Read [Concepts and Architecture](/ai/tdc/concepts/tdc-concepts-and-architecture.md) to understand profiles, credentials, regions, SQL roles, and the Filesystem companion. ### Guides +Use guides to complete one focused task or manage one feature area: + - [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) -- [Manage TiDB Cloud Organizations](/ai/tdc/guides/tdc-organization.md) +- [Manage Projects in TiDB Cloud Organizations with tdc](/ai/tdc/guides/tdc-organization.md) - [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) - [Manage TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem.md) - [Use Git Workspaces on TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem-git.md) - [Use Filesystem Journals](/ai/tdc/guides/tdc-filesystem-journal.md) - [Use Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) +- [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) ### Examples -- [Use a Filesystem in an Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) +Use examples to follow a complete scenario that combines multiple commands and features: + +For users and automation: + - [Run a Daily tdc Workflow](/ai/tdc/examples/tdc-daily-workflow-example.md) - [Query SQL with Explicit Roles](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) - [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) + +For AI agents: + +- [Use a Filesystem in an Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) - [Prepare a Git Workspace for Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) - [Record an Agent Workflow in a Journal](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) - [Delegate Secrets to an Agent](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) @@ -67,6 +100,5 @@ You do not need to install, configure, or invoke Drive9 separately for normal td - [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) - [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) - [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) -- [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) To report a problem or suggest an improvement, create an issue in the [tdc GitHub repository](https://github.com/tidbcloud/tdc/issues). diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index 2f14c13877049..7787baa3b8ae8 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -11,6 +11,10 @@ This quick start installs tdc, configures one profile, and gets a successful res > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## When to use this quick start + +Use this quick start when you want to automate a new Starter database or create a persistent workspace for a user, script, or AI agent. It follows the new tdc workflow. If you manage TiDB Cloud Essential or need a legacy operation that tdc does not yet provide, use the [`ticloud` CLI documentation](/tidb-cloud/get-started-with-cli.md) during the transition. + ## 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. diff --git a/tidb-cloud/cli-reference.md b/tidb-cloud/cli-reference.md index 742ddb62356e7..a250ad713c13a 100644 --- a/tidb-cloud/cli-reference.md +++ b/tidb-cloud/cli-reference.md @@ -1,15 +1,19 @@ --- -title: TiDB Cloud CLI Reference (PREVIEW) -summary: Provides an overview of TiDB Cloud CLI. +title: TiDB Cloud CLI (ticloud) Reference (PREVIEW) +summary: Provides an overview of the legacy ticloud CLI for TiDB Cloud Starter and Essential. --- -# TiDB Cloud CLI Reference (PREVIEW) +# TiDB Cloud CLI (ticloud) Reference (PREVIEW) > **Note:** > > Currently, TiDB Cloud CLI is in public preview and not applicable to TiDB Cloud Dedicated clusters. -TiDB Cloud CLI is a command line interface, which allows you to operate TiDB Cloud from your terminal with a few lines of commands. In the TiDB Cloud CLI, you can easily manage your {{{ .starter }}} and Essential instances, import data to your instances, and perform more operations. +> **Note:** +> +> `ticloud` is the legacy TiDB Cloud CLI and is being gradually replaced by the new [`tdc` CLI](/ai/tdc/tdc-overview.md). For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use tdc. During the transition, continue to use `ticloud` for TiDB Cloud Essential and operations that tdc does not yet provide, such as import, export, and audit-log commands. + +The legacy `ticloud` CLI is a command-line interface that lets you operate TiDB Cloud from your terminal. It manages {{{ .starter }}} and Essential instances, imports and exports data, and supports other legacy CLI workflows. ## Before you begin diff --git a/tidb-cloud/get-started-with-cli.md b/tidb-cloud/get-started-with-cli.md index 425c141e73763..c111180e8ae31 100644 --- a/tidb-cloud/get-started-with-cli.md +++ b/tidb-cloud/get-started-with-cli.md @@ -1,11 +1,15 @@ --- -title: TiDB Cloud CLI Quick Start -summary: Learn how to manage {{{ .starter }}} and Essential instances through the TiDB Cloud CLI. +title: TiDB Cloud CLI (ticloud) Quick Start +summary: Learn how to manage {{{ .starter }}} and Essential instances through the legacy ticloud CLI. --- -# TiDB Cloud CLI Quick Start +# TiDB Cloud CLI (ticloud) Quick Start -TiDB Cloud provides a command-line interface (CLI) [`ticloud`](https://github.com/tidbcloud/tidbcloud-cli) for you to interact with TiDB Cloud from your terminal with a few lines of commands. For example, you can easily perform the following operations using `ticloud`: +> **Note:** +> +> `ticloud` is the legacy TiDB Cloud CLI and is being gradually replaced by the new [`tdc` CLI](/ai/tdc/tdc-overview.md). For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use tdc. During the transition, continue to use `ticloud` for TiDB Cloud Essential and operations that tdc does not yet provide, such as import, export, and audit-log commands. + +TiDB Cloud provides the legacy command-line interface (CLI) [`ticloud`](https://github.com/tidbcloud/tidbcloud-cli) for you to interact with TiDB Cloud Starter and Essential from your terminal with a few lines of commands. For example, you can perform the following operations using `ticloud`: - Create, delete, and list your {{{ .starter }}} or Essential instances. - Import data to your {{{ .starter }}} or Essential instances. From c2e0f5c989dbb3f6a37722e6a105aff80ccf7d76 Mon Sep 17 00:00:00 2001 From: Cheese Date: Wed, 22 Jul 2026 19:14:20 +0800 Subject: [PATCH 11/29] docs: reorganize tdc content as reference --- TOC-ai.md | 46 +++--- ai/_index.md | 72 +++++---- .../concepts/tdc-concepts-and-architecture.md | 137 ------------------ .../tdc-agent-sandbox-example.md | 2 +- .../tdc-ci-artifact-handoff-example.md | 81 +++++++++++ ai/tdc/reference/tdc-cli-reference.md | 98 +++++++++++-- .../tdc-daily-workflow-example.md | 9 +- .../tdc-filesystem-git.md | 27 +++- .../tdc-filesystem-journal.md | 27 +++- .../tdc-filesystem-vault.md | 39 ++++- .../{guides => reference}/tdc-filesystem.md | 112 ++++++++++++-- .../tdc-git-workspace-for-agents-example.md | 4 +- .../tdc-install-configure-update.md | 27 +++- .../tdc-journal-agent-workflow-example.md | 4 +- .../{guides => reference}/tdc-organization.md | 18 ++- .../tdc-parallel-agent-dataset-example.md | 81 +++++++++++ .../tdc-persistent-agent-state-example.md | 84 +++++++++++ .../tdc-query-sql-with-roles-example.md | 2 +- .../tdc-regions-security-and-limitations.md | 2 +- ...hare-filesystem-across-machines-example.md | 4 +- .../tdc-starter-database.md | 66 +++++---- ai/tdc/reference/tdc-troubleshooting.md | 4 +- .../tdc-vault-agent-secrets-example.md | 2 +- ai/tdc/tdc-overview.md | 43 +++--- ai/tdc/tdc-quick-start.md | 5 +- 25 files changed, 682 insertions(+), 314 deletions(-) delete mode 100644 ai/tdc/concepts/tdc-concepts-and-architecture.md rename ai/tdc/{examples => reference}/tdc-agent-sandbox-example.md (98%) create mode 100644 ai/tdc/reference/tdc-ci-artifact-handoff-example.md rename ai/tdc/{examples => reference}/tdc-daily-workflow-example.md (88%) rename ai/tdc/{guides => reference}/tdc-filesystem-git.md (68%) rename ai/tdc/{guides => reference}/tdc-filesystem-journal.md (59%) rename ai/tdc/{guides => reference}/tdc-filesystem-vault.md (61%) rename ai/tdc/{guides => reference}/tdc-filesystem.md (69%) rename ai/tdc/{examples => reference}/tdc-git-workspace-for-agents-example.md (95%) rename ai/tdc/{guides => reference}/tdc-install-configure-update.md (78%) rename ai/tdc/{examples => reference}/tdc-journal-agent-workflow-example.md (95%) rename ai/tdc/{guides => reference}/tdc-organization.md (77%) create mode 100644 ai/tdc/reference/tdc-parallel-agent-dataset-example.md create mode 100644 ai/tdc/reference/tdc-persistent-agent-state-example.md rename ai/tdc/{examples => reference}/tdc-query-sql-with-roles-example.md (97%) rename ai/tdc/{examples => reference}/tdc-share-filesystem-across-machines-example.md (95%) rename ai/tdc/{guides => reference}/tdc-starter-database.md (58%) rename ai/tdc/{examples => reference}/tdc-vault-agent-secrets-example.md (97%) diff --git a/TOC-ai.md b/TOC-ai.md index ae6c2de0ae09a..7d49e5203ca9b 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -12,9 +12,6 @@ ## CONCEPTS - [Vector Search](/ai/concepts/vector-search-overview.md) -- TiDB Cloud CLI (tdc) - - [Overview](/ai/tdc/tdc-overview.md) - - [Concepts and Architecture](/ai/tdc/concepts/tdc-concepts-and-architecture.md) ## GUIDES @@ -34,15 +31,6 @@ - [Join Queries](/ai/guides/join-queries.md) - [Raw SQL Queries](/ai/guides/raw-queries.md) - [Transactions](/ai/guides/transactions.md) -- Manage Starter Instances and File System via TiDB Cloud CLI (tdc) - - [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) - - [Manage Projects in TiDB Cloud Organizations](/ai/tdc/guides/tdc-organization.md) - - [Manage Starter Databases and SQL Access](/ai/tdc/guides/tdc-starter-database.md) - - [Manage Cloud Filesystem Resources](/ai/tdc/guides/tdc-filesystem.md) - - [Use Git Workspaces on Cloud Filesystem](/ai/tdc/guides/tdc-filesystem-git.md) - - [Track Changes with Filesystem Journals](/ai/tdc/guides/tdc-filesystem-journal.md) - - [Manage Secrets with Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) - - [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) ## EXAMPLES @@ -57,16 +45,6 @@ - [RAG Application](/ai/examples/rag-with-pytidb.md) - [Conversational Memory](/ai/examples/memory-with-pytidb.md) - [Text-to-SQL](/ai/examples/text2sql-with-pytidb.md) -- TiDB Cloud CLI (tdc) - - For Users and Automation - - [Automate Daily Database Operations](/ai/tdc/examples/tdc-daily-workflow-example.md) - - [Run SQL Queries with Role-Based Access](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) - - [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) - - For AI Agents - - [Set Up an Agent Sandbox Environment](/ai/tdc/examples/tdc-agent-sandbox-example.md) - - [Set Up a Git Workspace for AI Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) - - [Record Agent Workflows in a Journal](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) - - [Delegate Secrets Securely to Agents](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) ## INTEGRATIONS @@ -108,6 +86,28 @@ - [Limitations](/ai/reference/vector-search-limitations.md) - [Changelogs](/ai/reference/vector-search-changelogs.md) - TiDB Cloud CLI (tdc) - - [CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) + - [Overview](/ai/tdc/tdc-overview.md) + - Command Reference + - [CLI Syntax and Global Behavior](/ai/tdc/reference/tdc-cli-reference.md) + - [Install, Configure, and Update](/ai/tdc/reference/tdc-install-configure-update.md) + - [Organization and Projects](/ai/tdc/reference/tdc-organization.md) + - [Starter Databases and SQL](/ai/tdc/reference/tdc-starter-database.md) + - [Filesystem](/ai/tdc/reference/tdc-filesystem.md) + - [Filesystem Git Workspaces](/ai/tdc/reference/tdc-filesystem-git.md) + - [Filesystem Journals](/ai/tdc/reference/tdc-filesystem-journal.md) + - [Filesystem Vault](/ai/tdc/reference/tdc-filesystem-vault.md) + - Scenarios for Users and Automation + - [Automate Daily Database Operations](/ai/tdc/reference/tdc-daily-workflow-example.md) + - [Run SQL Queries with Role-Based Access](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) + - [Share a Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) + - [Hand Off CI Artifacts Between Jobs](/ai/tdc/reference/tdc-ci-artifact-handoff-example.md) + - Scenarios for AI Agents + - [Set Up an Agent Sandbox Environment](/ai/tdc/reference/tdc-agent-sandbox-example.md) + - [Persist Agent State Across Sandboxes](/ai/tdc/reference/tdc-persistent-agent-state-example.md) + - [Share a Read-Only Dataset Across Parallel Agents](/ai/tdc/reference/tdc-parallel-agent-dataset-example.md) + - [Set Up a Git Workspace for AI Agents](/ai/tdc/reference/tdc-git-workspace-for-agents-example.md) + - [Record Agent Workflows in a Journal](/ai/tdc/reference/tdc-journal-agent-workflow-example.md) + - [Delegate Secrets Securely to Agents](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) - [Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) - [Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) + - [Troubleshooting](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/_index.md b/ai/_index.md index b9e030f93b0fb..72e6069fda98f 100644 --- a/ai/_index.md +++ b/ai/_index.md @@ -30,7 +30,6 @@ Understand the foundational concepts behind AI-powered search in TiDB. | Document | Description | | --- | --- | | [Vector Search](/ai/concepts/vector-search-overview.md) | Comprehensive overview of vector search, including concepts, how it works, and use cases. | -| [tdc Concepts and Architecture (Preview)](/ai/tdc/concepts/tdc-concepts-and-architecture.md) | Understand profiles, regions, credentials, SQL roles, Filesystems, and the Drive9 companion boundary. | ## Guides @@ -47,21 +46,6 @@ Step-by-step guides for building AI applications with TiDB using the [`pytidb`]( | [Auto Embedding](/ai/guides/auto-embedding.md) | Automatically generate embeddings on data insertion. | | [Filtering](/ai/guides/filtering.md) | Filter search results with metadata conditions. | -### TiDB Cloud CLI (tdc) (Preview) - -Use these guides to complete a focused task or manage one tdc feature area. - -| Document | Description | -| --- | --- | -| [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) | Install release binaries, configure profiles, update, and uninstall tdc. | -| [Manage Projects in TiDB Cloud Organizations with tdc](/ai/tdc/guides/tdc-organization.md) | List projects and understand virtual-project selection. | -| [Starter Database](/ai/tdc/guides/tdc-starter-database.md) | Manage clusters, branches, SQL users, connection strings, and SQL execution. | -| [Filesystem](/ai/tdc/guides/tdc-filesystem.md) | Manage resources, data, layers, packs, and FUSE or WebDAV mounts. | -| [Filesystem Git](/ai/tdc/guides/tdc-filesystem-git.md) | Clone, hydrate, and manage linked Git worktrees. | -| [Filesystem Journal](/ai/tdc/guides/tdc-filesystem-journal.md) | Record, search, and verify append-only workflow events. | -| [Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) | Store secrets, delegate access, audit, inject, and mount a read-only vault. | -| [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) | Diagnose authentication, quota, SQL, companion, selection, and mount failures. | - ## Examples Complete code examples and demos showcasing TiDB's AI capabilities. @@ -75,27 +59,6 @@ Complete code examples and demos showcasing TiDB's AI capabilities. | [Conversational Memory](/ai/examples/memory-with-pytidb.md) | Persistent memory for AI agents and chatbots. | | [Text-to-SQL](/ai/examples/text2sql-with-pytidb.md) | Convert natural language to SQL queries. | -### TiDB Cloud CLI (tdc) (Preview) - -These examples combine multiple commands into end-to-end scenarios. Choose a workflow based on who runs it. - -#### For users and automation - -| Document | Description | -| --- | --- | -| [Daily Workflow](/ai/tdc/examples/tdc-daily-workflow-example.md) | Manage one Starter cluster and Filesystem in a routine operator flow. | -| [Query SQL with Roles](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) | Use explicit read-only, read-write, and admin SQL roles. | -| [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) | Transfer an owner token securely and verify cross-machine visibility. | - -#### For AI agents - -| Document | Description | -| --- | --- | -| [Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) | Give a clean sandbox Filesystem access without TiDB Cloud API keys. | -| [Git Workspace for Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) | Prepare a mounted Git workspace and isolated linked worktree. | -| [Journal an Agent Workflow](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) | Record structured events and verify their hash chain. | -| [Delegate Vault Secrets](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) | Grant an agent temporary access to one secret field. | - ## Integrations Integrate TiDB with popular AI frameworks, embedding providers, and development tools. @@ -122,8 +85,41 @@ Technical reference documentation for TiDB's AI and vector search features. ### TiDB Cloud CLI (tdc) (Preview) +The command references document every tdc command family and provide examples for each operation. The scenario references combine commands into complete user, automation, and AI agent workflows. + +#### Command reference + | Document | Description | | --- | --- | -| [CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) | Global flags, output, queries, dry-run, help, errors, and aliases. | +| [tdc Overview](/ai/tdc/tdc-overview.md) | Decide when to use tdc and understand its scope relative to ticloud and the TiDB Cloud console. | +| [CLI Syntax and Global Behavior](/ai/tdc/reference/tdc-cli-reference.md) | Command tree, global flags, output, queries, dry-run, help, errors, and aliases. | +| [Install, Configure, and Update](/ai/tdc/reference/tdc-install-configure-update.md) | Install releases, configure profiles, update, and uninstall tdc. | +| [Organization and Projects](/ai/tdc/reference/tdc-organization.md) | List projects and understand virtual-project selection. | +| [Starter Databases and SQL](/ai/tdc/reference/tdc-starter-database.md) | Manage clusters, branches, SQL users, connection strings, and SQL execution. | +| [Filesystem](/ai/tdc/reference/tdc-filesystem.md) | Manage resources, data, layers, packs, and FUSE or WebDAV mounts. | +| [Filesystem Git Workspaces](/ai/tdc/reference/tdc-filesystem-git.md) | Clone, hydrate, and manage linked Git worktrees. | +| [Filesystem Journals](/ai/tdc/reference/tdc-filesystem-journal.md) | Record, search, and verify append-only workflow events. | +| [Filesystem Vault](/ai/tdc/reference/tdc-filesystem-vault.md) | Store secrets, delegate access, audit, inject, and mount a read-only vault. | | [Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) | Profiles, precedence, local state, credentials, mount locators, and logs. | | [Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) | Placement, authentication boundaries, platforms, durability, and Preview constraints. | +| [Troubleshooting](/ai/tdc/reference/tdc-troubleshooting.md) | Diagnose authentication, quota, SQL, companion, selection, and mount failures. | + +#### Scenarios for users and automation + +| Document | Description | +| --- | --- | +| [Daily Workflow](/ai/tdc/reference/tdc-daily-workflow-example.md) | Manage one Starter cluster and Filesystem in a routine operator flow. | +| [Query SQL with Roles](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) | Use explicit read-only, read-write, and admin SQL roles. | +| [Share a Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) | Transfer an owner token securely and verify cross-machine visibility. | +| [Hand Off CI Artifacts Between Jobs](/ai/tdc/reference/tdc-ci-artifact-handoff-example.md) | Persist build output across isolated jobs without copying a complete tdc profile. | + +#### Scenarios for AI agents + +| Document | Description | +| --- | --- | +| [Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) | Give a clean sandbox Filesystem access without TiDB Cloud API keys. | +| [Persistent Agent State](/ai/tdc/reference/tdc-persistent-agent-state-example.md) | Preserve plans, checkpoints, and results across disposable sandboxes. | +| [Parallel Agent Dataset](/ai/tdc/reference/tdc-parallel-agent-dataset-example.md) | Give multiple agents read-only access to one shared unstructured dataset. | +| [Git Workspace for Agents](/ai/tdc/reference/tdc-git-workspace-for-agents-example.md) | Prepare a mounted Git workspace and isolated linked worktree. | +| [Journal an Agent Workflow](/ai/tdc/reference/tdc-journal-agent-workflow-example.md) | Record structured events and verify their hash chain. | +| [Delegate Vault Secrets](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) | Grant an agent temporary access to one secret field. | diff --git a/ai/tdc/concepts/tdc-concepts-and-architecture.md b/ai/tdc/concepts/tdc-concepts-and-architecture.md deleted file mode 100644 index 1b00611596d81..0000000000000 --- a/ai/tdc/concepts/tdc-concepts-and-architecture.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: tdc Concepts and Architecture -summary: Understand tdc profiles, regions, credentials, SQL roles, Filesystem resources, local state, and the bundled Drive9 companion. ---- - -# tdc Concepts and Architecture - -This document explains the concepts needed to use tdc with TiDB Cloud Starter and TiDB Cloud Filesystem. - -> **Note:** -> -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. - -## Command model - -tdc uses service nouns and explicit operation names: - -```text -tdc db create-db-cluster -tdc fs copy-file -tdc fs-git clone-git-workspace -``` - -The command tree is at most two levels. Long, descriptive command and flag names make intent explicit in logs and agent-generated commands. Commands are non-interactive except for `tdc configure`. - -Structured commands return JSON by default. Use `--output text` for a terminal-oriented representation and `--query` for a JMESPath projection. - -## Product boundaries - -tdc is the new CLI for TiDB Cloud Starter and TiDB Cloud Filesystem. It is intended for users, scripts, CI jobs, and AI agents that need predictable non-interactive commands and structured output. - -The legacy `ticloud` CLI manages TiDB Cloud Starter and Essential. During the transition to tdc, continue to use `ticloud` for Essential and for operations that tdc does not yet expose, including import, export, and audit-log commands. The `ticloud` CLI will be gradually retired as supported workflows move to tdc. - -The TiDB Cloud console remains the browser-based interface for visual inspection and guided manual operations. Choosing tdc does not prevent you from using the console against the same cloud resources. - -## Profiles and regions - -A profile is a named local namespace containing TiDB Cloud placement, a default virtual project, and credentials. The default profile is named `default`; select another with `--profile`. - -tdc represents placement with one canonical region code: - -```text -aws-us-east-1 -aws-ap-southeast-1 -ali-ap-southeast-1 -``` - -The prefix identifies the cloud provider. A global `--region` value overrides `TDC_REGION_CODE` and the profile region for one command without changing saved configuration. - -During `tdc configure`, tdc calls the organization API and requires one accessible project with `type = "tidbx_virtual"`. It stores that project ID as the default for Starter cluster creation. - -## Credential boundaries - -tdc uses separate credentials for separate security boundaries: - -| Credential | Purpose | Storage | -| --- | --- | --- | -| TiDB Cloud API public/private key | Organization, Starter control plane, Filesystem provisioning and deletion | `~/.tdc/credentials` | -| DB SQL username/password | SQL access to one Starter cluster | `~/.tdc/db_users//credentials` | -| Filesystem owner token | Filesystem data plane, mounts, Git, journal, and owner vault operations | Per-resource credentials under `~/.tdc/fs_resources/` or `TDC_FS_TOKEN` | -| Delegated vault token | Limited access to selected secret fields | `TDC_VAULT_TOKEN` or an explicit command input | - -TiDB Cloud API keys are never reused as SQL passwords or Filesystem tokens. - -## SQL roles - -`tdc db create-db-sql-users` creates or repairs three stable users for a cluster: - -- `read_only` for queries that must not modify data; -- `read_write` for normal application and agent work; -- `admin` for DDL and privilege administration. - -Role selection is explicit with `--read-only`, `--read-write`, or `--admin`. Read-write is the default when no role flag is supplied. - -## One profile, multiple Filesystems - -One profile can register multiple Filesystem resources. Each resource has an isolated config file and credential file. Select a resource in this order: - -1. `--file-system-name`; -2. `TDC_FS_FILE_SYSTEM_NAME`; -3. the profile's default Filesystem; -4. the only registered Filesystem, when exactly one exists. - -If multiple resources exist and none is selected, tdc fails instead of guessing. Use `tdc fs set-default-file-system` to choose a default. - -## Config-free sandbox access - -A clean agent sandbox does not need `tdc configure` or TiDB Cloud API keys to use an existing Filesystem. Supply: - -```bash -export TDC_FS_TOKEN="" -export TDC_REGION_CODE="aws-us-east-1" -export TDC_FS_FILE_SYSTEM_NAME="workspace" -``` - -tdc resolves these values into an in-memory profile namespace. It does not write an `[env]` profile or persist the token. - -## Local state - -All tdc-owned state is under `~/.tdc/`: - -| Path | Contents | -| --- | --- | -| `config` | Non-sensitive profile, default project, and logging settings | -| `credentials` | TiDB Cloud API keys | -| `fs_resources/` | Per-profile, per-Filesystem metadata and owner credentials | -| `db_users/` | Cluster-scoped SQL credentials | -| `mounts/` | Non-secret locators for active background mounts | -| `logs/tdc.jsonl` | Redacted local operation log | -| `bin/` | Installed `tdc` and `tdc-drive9` binaries | - -Operation logging is local and is not telemetry. Set `TDC_LOGGING=off` to disable it for one process. - -## tdc and the Drive9 companion - -tdc installs [Drive9](https://github.com/mem9-ai/drive9) as the private companion name `tdc-drive9`. - -tdc owns: - -- profile, credential, region, and Filesystem selection; -- TiDB Cloud control-plane calls; -- JSON/text output, queries, errors, and local logging; -- translation from the tdc command surface to the companion. - -The companion owns: - -- Filesystem reads, writes, metadata, links, search, and layers; -- FUSE and WebDAV mount processes, caches, drain, and unmount; -- pack/unpack, Git workspace, journal, and vault semantics. - -A background mount leaves a long-running `tdc-drive9 mount --foreground` process. `tdc fs unmount-file-system` gracefully flushes pending FUSE work and stops that process. `tdc fs drain-file-system` provides an explicit, reportable durability barrier while leaving a FUSE mount active so it can accept later writes. Do not abruptly terminate a machine with unflushed writes or local-only overlay data that you need to keep. - -## What's next - -- [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) -- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/examples/tdc-agent-sandbox-example.md b/ai/tdc/reference/tdc-agent-sandbox-example.md similarity index 98% rename from ai/tdc/examples/tdc-agent-sandbox-example.md rename to ai/tdc/reference/tdc-agent-sandbox-example.md index d7fdc8ce06b90..fb2a9a64e1515 100644 --- a/ai/tdc/examples/tdc-agent-sandbox-example.md +++ b/ai/tdc/reference/tdc-agent-sandbox-example.md @@ -113,5 +113,5 @@ tdc fs delete-file-system \ ## What's next -- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) - [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-ci-artifact-handoff-example.md b/ai/tdc/reference/tdc-ci-artifact-handoff-example.md new file mode 100644 index 0000000000000..d7a6f26eddd8a --- /dev/null +++ b/ai/tdc/reference/tdc-ci-artifact-handoff-example.md @@ -0,0 +1,81 @@ +--- +title: Hand Off CI Artifacts Between Isolated Jobs with tdc +summary: Persist build output in TiDB Cloud Filesystem and consume it from a later CI job without copying a complete tdc profile. +--- + +# Hand Off CI Artifacts Between Isolated Jobs with tdc + +This scenario uses a Filesystem as a durable handoff point between isolated CI jobs or runners. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## The problem + +Build and verification jobs often run on different ephemeral machines. Local output disappears with the producer, while provider-specific artifact services add another upload API, retention model, and download step to agent automation. + +## How tdc changes the workflow + +The pipeline injects one Filesystem token, region, and name into both jobs. The producer uploads output under a run-specific path, and the consumer downloads or streams that exact path. Neither job needs TiDB Cloud API keys or a copied `~/.tdc/` directory. + +## Prerequisites + +Provision a Filesystem on a trusted machine and store these values as protected CI secrets or variables: + +```text +TDC_FS_TOKEN +TDC_REGION_CODE +TDC_FS_FILE_SYSTEM_NAME +``` + +Use a CI-generated run identifier such as `RUN_ID` to isolate concurrent pipelines. + +## Producer job + +Build the artifact, then upload it: + +```bash +tar -czf app.tar.gz ./dist +tdc fs copy-file \ + --from-local ./app.tar.gz \ + --to-remote "/ci/${RUN_ID}/app.tar.gz" \ + --tag pipeline=build \ + --description "artifact for run ${RUN_ID}" +``` + +## Consumer job + +Download and verify the artifact from another runner: + +```bash +tdc fs copy-file \ + --from-remote "/ci/${RUN_ID}/app.tar.gz" \ + --to-local ./app.tar.gz \ + --create-parents + +tar -tzf app.tar.gz +``` + +For a command that accepts stdin, avoid an intermediate local file: + +```bash +tdc fs copy-file --from-remote "/ci/${RUN_ID}/app.tar.gz" --to-stdout \ + | tar -tzf - +``` + +## Cleanup and isolation + +Delete only the run-specific directory after all consumers finish: + +```bash +tdc fs delete-file --path "/ci/${RUN_ID}" --recursive +``` + +Use unique run IDs and do not delete the whole Filesystem from an individual job. Filesystem deletion requires the trusted control-plane configuration and should remain a separate owner operation. + +## Related reference + +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md index a33cb0c1c5f2a..2e7c847f4a707 100644 --- a/ai/tdc/reference/tdc-cli-reference.md +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -19,6 +19,86 @@ tdc [subcommand] [required flags] [optional flags] [global flags] tdc accepts long flags only. A one-letter flag such as `-p` is rejected. +## Command tree + +```text +tdc +├── configure +├── update +├── organization +│ └── list-projects +├── db +│ ├── create-db-cluster +│ ├── list-db-clusters +│ ├── describe-db-cluster +│ ├── update-db-cluster +│ ├── delete-db-cluster +│ ├── create-db-cluster-branch +│ ├── list-db-cluster-branches +│ ├── describe-db-cluster-branch +│ ├── delete-db-cluster-branch +│ ├── create-db-sql-users +│ ├── format-db-connection-string +│ └── execute-sql-statement +├── fs +│ ├── create-file-system +│ ├── list-file-systems +│ ├── describe-file-system +│ ├── set-default-file-system +│ ├── unset-default-file-system +│ ├── check-file-system +│ ├── delete-file-system +│ ├── copy-file +│ ├── read-file +│ ├── list-files +│ ├── describe-file +│ ├── move-file +│ ├── delete-file +│ ├── create-directory +│ ├── chmod-file +│ ├── create-symlink +│ ├── create-hardlink +│ ├── search-file-content +│ ├── find-files +│ ├── create-layer +│ ├── list-layers +│ ├── describe-layer +│ ├── diff-layer +│ ├── create-layer-checkpoint +│ ├── rollback-layer +│ ├── commit-layer +│ ├── pack-file-system +│ ├── unpack-file-system +│ ├── mount-file-system +│ ├── drain-file-system +│ └── unmount-file-system +├── fs-git +│ ├── clone-git-workspace +│ ├── hydrate-git-workspace +│ ├── add-git-worktree +│ └── remove-git-worktree +├── fs-journal +│ ├── create-journal +│ ├── append-journal-entries +│ ├── read-journal-entries +│ ├── search-journal-entries +│ └── verify-journal +└── fs-vault + ├── create-secret + ├── replace-secret + ├── read-secret + ├── list-secrets + ├── delete-secret + ├── create-grant + ├── delete-grant + ├── list-audit-events + ├── run-with-secret + ├── mount-vault + └── unmount-vault +``` + +For each command's inputs and examples, see the family references linked in [Command families](#command-families). + Required flags appear before optional flags in generated usage. Optional flags are enclosed in brackets: ```text @@ -138,14 +218,14 @@ Errors are written to stderr and successful command output is written to stdout. | Command | Purpose | | --- | --- | -| `tdc configure` | Configure a local profile | -| `tdc update` | Check or apply release updates | -| `tdc organization` | Inspect projects | -| `tdc db` | Manage Starter clusters, branches, and SQL | -| `tdc fs` | Manage Filesystems, files, layers, packs, and mounts | -| `tdc fs-git` | Manage Git workspaces on mounted Filesystems | -| `tdc fs-journal` | Manage verifiable journals | -| `tdc fs-vault` | Manage secrets and delegated access | +| [`tdc configure`](/ai/tdc/reference/tdc-install-configure-update.md) | Configure a local profile | +| [`tdc update`](/ai/tdc/reference/tdc-install-configure-update.md) | Check or apply release updates | +| [`tdc organization`](/ai/tdc/reference/tdc-organization.md) | Inspect projects | +| [`tdc db`](/ai/tdc/reference/tdc-starter-database.md) | Manage Starter clusters, branches, and SQL | +| [`tdc fs`](/ai/tdc/reference/tdc-filesystem.md) | Manage Filesystems, files, layers, packs, and mounts | +| [`tdc fs-git`](/ai/tdc/reference/tdc-filesystem-git.md) | Manage Git workspaces on mounted Filesystems | +| [`tdc fs-journal`](/ai/tdc/reference/tdc-filesystem-journal.md) | Manage verifiable journals | +| [`tdc fs-vault`](/ai/tdc/reference/tdc-filesystem-vault.md) | Manage secrets and delegated access | For complete commands and flags, run: @@ -178,5 +258,5 @@ Aliases use the same long flags, authentication, output, query, and error behavi ## Related documentation -- [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) +- [Install, Configure, and Update tdc](/ai/tdc/reference/tdc-install-configure-update.md) - [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/examples/tdc-daily-workflow-example.md b/ai/tdc/reference/tdc-daily-workflow-example.md similarity index 88% rename from ai/tdc/examples/tdc-daily-workflow-example.md rename to ai/tdc/reference/tdc-daily-workflow-example.md index b129ddcdb4927..be9e51d41c2bc 100644 --- a/ai/tdc/examples/tdc-daily-workflow-example.md +++ b/ai/tdc/reference/tdc-daily-workflow-example.md @@ -29,15 +29,14 @@ tdc fs list-file-systems --output text ```bash tdc db create-db-cluster \ --db-cluster-name daily-demo \ - --db-cluster-type starter \ --dry-run tdc db create-db-cluster \ --db-cluster-name daily-demo \ - --db-cluster-type starter + --wait ``` -Record the returned cluster ID and wait until the cluster is active: +Record the returned cluster ID. Because `--wait` was set, the create command returns after the cluster is active. You can inspect it again later: ```bash tdc db describe-db-cluster \ @@ -107,5 +106,5 @@ Deleting local tdc configuration is not a substitute for deleting remote resourc ## What's next -- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) -- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) +- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/guides/tdc-filesystem-git.md b/ai/tdc/reference/tdc-filesystem-git.md similarity index 68% rename from ai/tdc/guides/tdc-filesystem-git.md rename to ai/tdc/reference/tdc-filesystem-git.md index a37d1ce392e60..260a91444935e 100644 --- a/ai/tdc/guides/tdc-filesystem-git.md +++ b/ai/tdc/reference/tdc-filesystem-git.md @@ -1,9 +1,9 @@ --- -title: Use Git Workspaces on TiDB Cloud Filesystem -summary: Clone, hydrate, and manage linked Git worktrees in a mounted TiDB Cloud Filesystem workspace. +title: tdc fs-git Command Reference +summary: Reference every tdc fs-git command for cloning, hydrating, and managing linked Git worktrees. --- -# Use Git Workspaces on TiDB Cloud Filesystem +# tdc fs-git Command Reference `tdc fs-git` accelerates Git workspace setup on mounted TiDB Cloud Filesystem paths. It augments Git; you continue to use ordinary `git` commands for status, edit, add, commit, fetch, and push. @@ -11,6 +11,23 @@ summary: Clone, hydrate, and manage linked Git worktrees in a mounted TiDB Cloud > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## Command tree + +```text +tdc fs-git +├── clone-git-workspace +├── hydrate-git-workspace +├── add-git-worktree +└── remove-git-worktree +``` + +| Command | Purpose and key inputs | Example | +| --- | --- | --- | +| `clone-git-workspace` | Clones into a mounted Filesystem path. `--blobless` and `--hydrate background` expose the tree before all clean data finishes hydrating. | `tdc fs-git clone-git-workspace --repo-url https://github.com/pingcap/tidb.git --target-path /workspace/tidb --blobless --hydrate background` | +| `hydrate-git-workspace` | Materializes clean Git data for an existing fast or blobless workspace. | `tdc fs-git hydrate-git-workspace --target-path /workspace/tidb --timeout 30m` | +| `add-git-worktree` | Creates a linked worktree from a base workspace. | `tdc fs-git add-git-worktree --base-path /workspace/tidb --worktree-path /workspace/feature --branch-name feature-x` | +| `remove-git-worktree` | Removes a linked worktree; dirty worktrees require explicit `--force`. | `tdc fs-git remove-git-worktree --worktree-path /workspace/feature` | + ## Prerequisites - Mount a Filesystem through FUSE. Git workspace acceleration relies on the mounted Filesystem runtime. @@ -95,5 +112,5 @@ The default coding-agent mount profile keeps `.git` and rebuildable generated fi ## What's next -- [Prepare a Git Workspace for Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) -- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) +- [Prepare a Git Workspace for Agents](/ai/tdc/reference/tdc-git-workspace-for-agents-example.md) +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/guides/tdc-filesystem-journal.md b/ai/tdc/reference/tdc-filesystem-journal.md similarity index 59% rename from ai/tdc/guides/tdc-filesystem-journal.md rename to ai/tdc/reference/tdc-filesystem-journal.md index 3eb31a3053dd1..658cb74c2f3bd 100644 --- a/ai/tdc/guides/tdc-filesystem-journal.md +++ b/ai/tdc/reference/tdc-filesystem-journal.md @@ -1,9 +1,9 @@ --- -title: Use TiDB Cloud Filesystem Journals -summary: Create append-only workflow journals, append and search structured events, and verify their hash chains. +title: tdc fs-journal Command Reference +summary: Reference every tdc fs-journal command for creating, appending, reading, searching, and verifying journals. --- -# Use TiDB Cloud Filesystem Journals +# tdc fs-journal Command Reference `tdc fs-journal` provides an append-only, verifiable ledger for agent and workflow events. Unlike a mutable text file, a journal assigns ordered sequence numbers, supports structured search, and maintains a hash chain that can detect alteration. @@ -11,6 +11,25 @@ summary: Create append-only workflow journals, append and search structured even > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## Command tree + +```text +tdc fs-journal +├── create-journal +├── append-journal-entries +├── read-journal-entries +├── search-journal-entries +└── verify-journal +``` + +| Command | Purpose and key inputs | Example | +| --- | --- | --- | +| `create-journal` | Creates a journal with an optional caller-provided ID, kind, actor, title, and labels. | `tdc fs-journal create-journal --journal-kind agent --title "review task" --actor agent:reviewer` | +| `append-journal-entries` | Appends JSON entries from repeatable flags, JSON Lines stdin, or a JSON array. | `tdc fs-journal append-journal-entries --journal-id jrn-demo --entry-json '{"type":"task.started"}'` | +| `read-journal-entries` | Reads ordered entries after a sequence number. | `tdc fs-journal read-journal-entries --journal-id jrn-demo --after-seq 0 --limit 100` | +| `search-journal-entries` | Searches journals and entries by type, kind, actor, status, subject, label, or time. | `tdc fs-journal search-journal-entries --entry-type task.started --include-entries` | +| `verify-journal` | Recalculates and verifies one journal's ordered hash chain. | `tdc fs-journal verify-journal --journal-id jrn-demo --output text` | + ## Prerequisites Select a Filesystem through a profile or provide `TDC_FS_TOKEN`, `TDC_REGION_CODE`, and `TDC_FS_FILE_SYSTEM_NAME`. @@ -78,5 +97,5 @@ Verification recalculates the ordered hash chain and reports whether the entries ## What's next -- [Record an Agent Workflow in a Journal](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) +- [Record an Agent Workflow in a Journal](/ai/tdc/reference/tdc-journal-agent-workflow-example.md) - [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/guides/tdc-filesystem-vault.md b/ai/tdc/reference/tdc-filesystem-vault.md similarity index 61% rename from ai/tdc/guides/tdc-filesystem-vault.md rename to ai/tdc/reference/tdc-filesystem-vault.md index 293407d189509..1fbb583f6b0ea 100644 --- a/ai/tdc/guides/tdc-filesystem-vault.md +++ b/ai/tdc/reference/tdc-filesystem-vault.md @@ -1,9 +1,9 @@ --- -title: Use TiDB Cloud Filesystem Vault -summary: Store Filesystem secrets, delegate limited access, inject secrets into processes, audit access, and mount a read-only vault. +title: tdc fs-vault Command Reference +summary: Reference every tdc fs-vault command for secrets, grants, audit events, process injection, and read-only mounts. --- -# Use TiDB Cloud Filesystem Vault +# tdc fs-vault Command Reference `tdc fs-vault` stores structured secrets and delegates limited, expiring access to agents. Owner operations use the Filesystem owner credential; delegated reads use a vault token scoped to selected secrets or fields. @@ -11,6 +11,37 @@ summary: Store Filesystem secrets, delegate limited access, inject secrets into > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## Command tree + +```text +tdc fs-vault +├── create-secret +├── replace-secret +├── read-secret +├── list-secrets +├── delete-secret +├── create-grant +├── delete-grant +├── list-audit-events +├── run-with-secret +├── mount-vault +└── unmount-vault +``` + +| Command | Purpose and key inputs | Example | +| --- | --- | --- | +| `create-secret` | Creates a structured secret from repeatable literal, file, or stdin fields. | `tdc fs-vault create-secret --secret-name db-prod --field PASSWORD=@./password.txt` | +| `replace-secret` | Replaces all fields from files in one directory. | `tdc fs-vault replace-secret --secret-path /n/vault/db-prod --from-directory ./secret-fields` | +| `read-secret` | Reads all fields or one field as structured, raw, or environment output. | `tdc fs-vault read-secret --secret-name db-prod --field DB_URL --format raw` | +| `list-secrets` | Lists secrets visible to the active owner or delegated credential. | `tdc fs-vault list-secrets` | +| `delete-secret` | Deletes one owner-visible secret. | `tdc fs-vault delete-secret --secret-name db-prod` | +| `create-grant` | Creates a scoped, expiring delegated token for one agent. | `tdc fs-vault create-grant --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m` | +| `delete-grant` | Revokes one grant by ID. | `tdc fs-vault delete-grant --grant-id "" --reason completed` | +| `list-audit-events` | Lists vault access events using secret, agent, time, and limit filters. | `tdc fs-vault list-audit-events --secret-name db-prod --limit 20` | +| `run-with-secret` | Runs a child command with secret fields injected as environment variables. | `tdc fs-vault run-with-secret --secret-path /n/vault/db-prod -- ./deploy.sh` | +| `mount-vault` | Mounts delegated readable fields as a local read-only FUSE filesystem. | `tdc fs-vault mount-vault --mount-path /path/to/vault --vault-token "$TDC_VAULT_TOKEN"` | +| `unmount-vault` | Unmounts a local vault mount. | `tdc fs-vault unmount-vault --mount-path /path/to/vault` | + ## Prerequisites Select a Filesystem through a profile or the config-free FS environment variables. Never print, log, or commit owner or delegated tokens. @@ -137,5 +168,5 @@ Unmount also supports `--timeout`, `--force`, and `--ignore-absent`. Vault mount ## What's next -- [Delegate Secrets to an Agent](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) +- [Delegate Secrets to an Agent](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) - [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/guides/tdc-filesystem.md b/ai/tdc/reference/tdc-filesystem.md similarity index 69% rename from ai/tdc/guides/tdc-filesystem.md rename to ai/tdc/reference/tdc-filesystem.md index eaa25e337ed8d..811993a7cdcd6 100644 --- a/ai/tdc/guides/tdc-filesystem.md +++ b/ai/tdc/reference/tdc-filesystem.md @@ -1,9 +1,9 @@ --- -title: Manage TiDB Cloud Filesystem with tdc -summary: Manage Filesystem resources, operate on files, use layers and packs, and mount Filesystems through the bundled Drive9 companion. +title: tdc fs Command Reference +summary: Reference every tdc fs command for Filesystem resources, files, layers, packs, and mounts. --- -# Manage TiDB Cloud Filesystem with tdc +# tdc fs Command Reference Use `tdc fs` to provision TiDB Cloud Filesystem resources and access their data from commands or local mounts. @@ -11,6 +11,96 @@ Use `tdc fs` to provision TiDB Cloud Filesystem resources and access their data > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## Command tree + +```text +tdc fs +├── create-file-system +├── list-file-systems +├── describe-file-system +├── set-default-file-system +├── unset-default-file-system +├── check-file-system +├── delete-file-system +├── copy-file +├── read-file +├── list-files +├── describe-file +├── move-file +├── delete-file +├── create-directory +├── chmod-file +├── create-symlink +├── create-hardlink +├── search-file-content +├── find-files +├── create-layer +├── list-layers +├── describe-layer +├── diff-layer +├── create-layer-checkpoint +├── rollback-layer +├── commit-layer +├── pack-file-system +├── unpack-file-system +├── mount-file-system +├── drain-file-system +└── unmount-file-system +``` + +## Command details + +### Resource commands + +| Command | Purpose and key inputs | Example | +| --- | --- | --- | +| `create-file-system` | Provisions a Filesystem. Requires `--file-system-name`; `--set-default` selects it and `--wait` waits until data-plane access is ready. | `tdc fs create-file-system --file-system-name workspace --set-default --wait` | +| `list-file-systems` | Lists resources registered in the selected local profile. | `tdc fs list-file-systems --output text` | +| `describe-file-system` | Reads one locally registered resource by name. | `tdc fs describe-file-system --file-system-name workspace` | +| `set-default-file-system` | Sets the default resource used when no name is supplied. | `tdc fs set-default-file-system --file-system-name workspace` | +| `unset-default-file-system` | Clears the profile's default resource without deleting it. | `tdc fs unset-default-file-system` | +| `check-file-system` | Verifies resource selection, endpoint resolution, credentials, and companion access. | `tdc fs check-file-system --file-system-name workspace` | +| `delete-file-system` | Requests asynchronous deletion and removes its local registration. Requires TiDB Cloud credentials and the owner resource credential. | `tdc fs delete-file-system --file-system-name workspace` | + +### Data and namespace commands + +| Command | Purpose and key inputs | Example | +| --- | --- | --- | +| `copy-file` | Uploads, downloads, streams, appends, resumes, or recursively copies local and remote paths. | `tdc fs copy-file --from-local ./report.md --to-remote /reports/report.md` | +| `read-file` | Writes a complete file or byte range to stdout. | `tdc fs read-file --path /reports/report.md --offset 0 --length 1024` | +| `list-files` | Lists entries under a remote path. | `tdc fs list-files --path /reports --output text` | +| `describe-file` | Returns metadata for one remote path. | `tdc fs describe-file --path /reports/report.md` | +| `move-file` | Moves or renames one remote path. | `tdc fs move-file --from-remote /draft.md --to-remote /reports/final.md` | +| `delete-file` | Deletes one remote path; `--recursive` is required for non-empty directories. | `tdc fs delete-file --path /scratch --recursive` | +| `create-directory` | Creates a remote directory and optionally sets its mode. | `tdc fs create-directory --path /reports/archive --mode 0755` | +| `chmod-file` | Changes remote POSIX mode metadata. | `tdc fs chmod-file --path /reports/final.md --mode 0600` | +| `create-symlink` | Creates a symbolic link with a target string and link path. | `tdc fs create-symlink --target final.md --link-path /reports/latest.md` | +| `create-hardlink` | Creates a hard link from an existing remote path. | `tdc fs create-hardlink --source-path /reports/final.md --link-path /reports/final-copy.md` | +| `search-file-content` | Searches file contents below a path, optionally within a layer. | `tdc fs search-file-content --path /reports --pattern "TODO"` | +| `find-files` | Finds paths by name, type, tags, size, or timestamps. | `tdc fs find-files --path /reports --file-name-pattern "*.md" --tag stage=review` | + +### Layer and portability commands + +| Command | Purpose and key inputs | Example | +| --- | --- | --- | +| `create-layer` | Creates an isolated change layer over `--base-root-path`; returns a generated layer ID when one is not supplied. | `tdc fs create-layer --base-root-path /workspace --layer-name task` | +| `list-layers` | Lists layers for the selected Filesystem. | `tdc fs list-layers --output text` | +| `describe-layer` | Reads one layer by ID. | `tdc fs describe-layer --layer-id ""` | +| `diff-layer` | Lists changes recorded in one layer. | `tdc fs diff-layer --layer-id ""` | +| `create-layer-checkpoint` | Records a named checkpoint for a layer. | `tdc fs create-layer-checkpoint --layer-id "" --checkpoint-id before-review` | +| `rollback-layer` | Restores a layer to its rollback state without committing it to the base. | `tdc fs rollback-layer --layer-id ""` | +| `commit-layer` | Applies a layer's changes to the base Filesystem. | `tdc fs commit-layer --layer-id ""` | +| `pack-file-system` | Stores selected local overlay state in a remote archive. | `tdc fs pack-file-system --mount-path /path/to/workspace` | +| `unpack-file-system` | Restores local overlay state from a remote archive. | `tdc fs unpack-file-system --mount-path /path/to/workspace` | + +### Mount commands + +| Command | Purpose and key inputs | Example | +| --- | --- | --- | +| `mount-file-system` | Mounts a resource through automatic, FUSE, or WebDAV mode. Requires `--mount-path`; resource selection can come from a flag, environment, or profile. | `tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace` | +| `drain-file-system` | Flushes pending FUSE work while leaving the mount online. | `tdc fs drain-file-system --mount-path /path/to/workspace --timeout 30s` | +| `unmount-file-system` | Gracefully flushes and unmounts a background FUSE or WebDAV mount. | `tdc fs unmount-file-system --mount-path /path/to/workspace` | + ## Prerequisites - Run `tdc configure` before provisioning or deleting a Filesystem. @@ -402,18 +492,8 @@ Aliases change only the command name. All flags remain long and identical to the | `tdc fs drain` | `tdc fs drain-file-system` | | `tdc fs umount` | `tdc fs unmount-file-system` | -## Command summary - -| Area | Commands | -| --- | --- | -| Resources | `create-file-system`, `list-file-systems`, `describe-file-system`, `set-default-file-system`, `unset-default-file-system`, `check-file-system`, `delete-file-system` | -| Data | `copy-file`, `read-file`, `list-files`, `describe-file`, `move-file`, `delete-file`, `create-directory`, `chmod-file`, `create-symlink`, `create-hardlink`, `search-file-content`, `find-files` | -| Layers | `create-layer`, `list-layers`, `describe-layer`, `diff-layer`, `create-layer-checkpoint`, `rollback-layer`, `commit-layer` | -| Portability | `pack-file-system`, `unpack-file-system` | -| Mounts | `mount-file-system`, `drain-file-system`, `unmount-file-system` | - ## What's next -- [Use a Filesystem in an Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) -- [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) -- [Use Git Workspaces on TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem-git.md) +- [Use a Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) +- [Share a Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) +- [tdc fs-git Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) diff --git a/ai/tdc/examples/tdc-git-workspace-for-agents-example.md b/ai/tdc/reference/tdc-git-workspace-for-agents-example.md similarity index 95% rename from ai/tdc/examples/tdc-git-workspace-for-agents-example.md rename to ai/tdc/reference/tdc-git-workspace-for-agents-example.md index c97105b31cd95..8a9be1ac7c684 100644 --- a/ai/tdc/examples/tdc-git-workspace-for-agents-example.md +++ b/ai/tdc/reference/tdc-git-workspace-for-agents-example.md @@ -99,5 +99,5 @@ Use `--force` for worktree removal only when uncommitted changes can be discarde ## What's next -- [Use Git Workspaces on TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem-git.md) -- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) +- [tdc fs-git Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/guides/tdc-install-configure-update.md b/ai/tdc/reference/tdc-install-configure-update.md similarity index 78% rename from ai/tdc/guides/tdc-install-configure-update.md rename to ai/tdc/reference/tdc-install-configure-update.md index 7e0fb98c4f10e..c84bd0ddc02cd 100644 --- a/ai/tdc/guides/tdc-install-configure-update.md +++ b/ai/tdc/reference/tdc-install-configure-update.md @@ -1,16 +1,31 @@ --- -title: Install, Configure, and Update tdc -summary: Install tdc release binaries, configure profiles interactively or in automation, update safely, and remove the CLI. +title: tdc Installation, Configuration, and Update Command Reference +summary: Reference tdc release installation, configure and update commands, version checks, and uninstallation. --- -# Install, Configure, and Update tdc +# tdc Installation, Configuration, and Update Command Reference -This guide covers the supported release installers, profile configuration, help and version behavior, updates, and uninstallation. +This reference documents the supported release installers, top-level configuration and update commands, help and version behavior, and uninstallation. > **Note:** > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## Command tree + +```text +tdc +├── configure +└── update +``` + +| Command | Required inputs | Main optional inputs | Example | +| --- | --- | --- | --- | +| `tdc configure` | Interactive input, or region and TiDB Cloud API keys in non-interactive mode | `--profile`, `--non-interactive`, `--region-code`, key flags | `tdc configure --profile staging` | +| `tdc update` | None | `--check`, `--fail-if-update-available`, `--dry-run`, `--target-version` | `tdc update --check` | + +Run `tdc configure help` or `tdc update help` for the complete generated flag list. + ## Install tdc ### macOS and Linux @@ -157,5 +172,5 @@ Deleting local state does not delete remote Starter clusters or Filesystem resou ## What's next - [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) -- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) -- [Manage TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem.md) +- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/examples/tdc-journal-agent-workflow-example.md b/ai/tdc/reference/tdc-journal-agent-workflow-example.md similarity index 95% rename from ai/tdc/examples/tdc-journal-agent-workflow-example.md rename to ai/tdc/reference/tdc-journal-agent-workflow-example.md index 5b8d4aa01f442..e5db1e3e377a5 100644 --- a/ai/tdc/examples/tdc-journal-agent-workflow-example.md +++ b/ai/tdc/reference/tdc-journal-agent-workflow-example.md @@ -92,5 +92,5 @@ Journals are append-only and currently have no delete command in the tdc public ## What's next -- [Use TiDB Cloud Filesystem Journals](/ai/tdc/guides/tdc-filesystem-journal.md) -- [Delegate Secrets to an Agent](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) +- [tdc fs-journal Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) +- [Delegate Secrets to an Agent](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) diff --git a/ai/tdc/guides/tdc-organization.md b/ai/tdc/reference/tdc-organization.md similarity index 77% rename from ai/tdc/guides/tdc-organization.md rename to ai/tdc/reference/tdc-organization.md index f872e3ec4ba9d..5ec7471c18f4b 100644 --- a/ai/tdc/guides/tdc-organization.md +++ b/ai/tdc/reference/tdc-organization.md @@ -1,9 +1,9 @@ --- -title: Manage Projects in TiDB Cloud Organizations with tdc -summary: List accessible TiDB Cloud projects and understand regular and virtual project types used by tdc. +title: tdc organization Command Reference +summary: Reference the tdc organization command tree, project listing inputs, output, and examples. --- -# Manage Projects in TiDB Cloud Organizations with tdc +# tdc organization Command Reference Use `tdc organization` to inspect the projects accessible to the configured TiDB Cloud API key. @@ -11,6 +11,15 @@ Use `tdc organization` to inspect the projects accessible to the configured TiDB > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## Command tree + +```text +tdc organization +└── list-projects +``` + +`list-projects` requires a configured TiDB Cloud API key. It accepts `--page-size` and `--page-token` for pagination, plus the global output and query flags. + ## Prerequisites Run `tdc configure` with a TiDB Cloud API key that can list organization projects. @@ -55,11 +64,10 @@ project_id = "..." ```bash tdc db create-db-cluster \ --db-cluster-name project-specific-cluster \ - --db-cluster-type starter \ --project-id "" ``` ## What's next -- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) +- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) - [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-parallel-agent-dataset-example.md b/ai/tdc/reference/tdc-parallel-agent-dataset-example.md new file mode 100644 index 0000000000000..b8cfeaa158cbd --- /dev/null +++ b/ai/tdc/reference/tdc-parallel-agent-dataset-example.md @@ -0,0 +1,81 @@ +--- +title: Share a Read-Only Dataset Across Parallel Agents with tdc +summary: Upload one unstructured dataset and expose the same read-only mounted namespace to multiple agent workers. +--- + +# Share a Read-Only Dataset Across Parallel Agents with tdc + +This scenario gives multiple short-lived workers one shared corpus without copying it into every sandbox. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## The problem + +Parallel document-processing or evaluation agents often need the same PDFs, images, logs, or model artifacts. Downloading the complete corpus into every worker delays startup, duplicates storage, and leaves each worker with a different point-in-time copy. + +## How tdc changes the workflow + +An owner uploads the corpus once. Every worker selects the same Filesystem and mounts it read-only, so ordinary tools can traverse a common namespace. Workers write results to separate task paths or a different output Filesystem. + +## Step 1. Upload the corpus + +On a trusted machine: + +```bash +tdc fs create-file-system \ + --file-system-name shared-corpus \ + --set-default \ + --wait + +tdc fs copy-file \ + --from-local ./corpus \ + --to-remote /datasets/corpus \ + --recursive + +tdc fs find-files \ + --path /datasets/corpus \ + --file-name-pattern "*.pdf" \ + --output text +``` + +Transfer the returned FS token through a secret manager. + +## Step 2. Mount in each worker + +Inject the resource token, region, and name into each worker, then run: + +```bash +mkdir -p "$HOME/corpus" +tdc fs mount-file-system \ + --file-system-name shared-corpus \ + --mount-path "$HOME/corpus" \ + --remote-path /datasets/corpus \ + --read-only +``` + +The worker can use standard tools without a storage SDK: + +```bash +find "$HOME/corpus" -type f -name '*.pdf' -print +``` + +Unmount before terminating the worker: + +```bash +tdc fs unmount-file-system --mount-path "$HOME/corpus" +``` + +## Operational notes + +- `--read-only` prevents writes through that mount. The underlying FS owner token remains an owner credential and is not a read-only security token. +- Do not let workers use direct mutating `tdc fs` commands when the workflow requires read-only behavior. +- Partition result paths by agent or run ID if workers write to the same output Filesystem. +- On platforms where FUSE or WebDAV mounting is unavailable, use `read-file`, `find-files`, and `copy-file --to-local` directly. + +## Related reference + +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [Use a Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) +- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/reference/tdc-persistent-agent-state-example.md b/ai/tdc/reference/tdc-persistent-agent-state-example.md new file mode 100644 index 0000000000000..471b6813184dd --- /dev/null +++ b/ai/tdc/reference/tdc-persistent-agent-state-example.md @@ -0,0 +1,84 @@ +--- +title: Persist Agent State Across Disposable Sandboxes with tdc +summary: Preserve plans, checkpoints, outputs, and workflow history in a TiDB Cloud Filesystem while replacing agent sandboxes. +--- + +# Persist Agent State Across Disposable Sandboxes with tdc + +This scenario keeps an agent's durable state in TiDB Cloud Filesystem while its compute environment remains disposable. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## The problem + +An agent sandbox can disappear after a timeout, failure, or deployment. Plans, intermediate results, and diagnostic files stored only on its local disk disappear with it. Keeping the sandbox alive only to preserve state ties storage durability to compute lifecycle and wastes resources. + +## How tdc changes the workflow + +A trusted machine provisions one Filesystem. Each sandbox receives only the Filesystem token, region code, and name. The agent writes durable task state to the remote namespace and records workflow transitions in a journal. A replacement sandbox can read both without receiving TiDB Cloud control-plane keys. + +## Step 1. Provision the state Filesystem + +On a trusted machine: + +```bash +export TDC_FS_TOKEN="$(tdc fs create-file-system \ + --file-system-name agent-state \ + --wait \ + --query fs_token \ + --output text)" +``` + +Store `TDC_FS_TOKEN` in a secret manager. Also record the configured canonical region code and the Filesystem name. + +## Step 2. Start the first sandbox + +Inject the following environment variables: + +```bash +export TDC_FS_TOKEN="" +export TDC_REGION_CODE="aws-us-east-1" +export TDC_FS_FILE_SYSTEM_NAME="agent-state" +``` + +Write a plan and create a workflow journal: + +```bash +printf '%s\n' '# Plan' '1. inspect' '2. change' '3. verify' \ + | tdc fs copy-file --from-stdin --to-remote /tasks/task-42/plan.md + +tdc fs-journal create-journal \ + --journal-id task-42 \ + --journal-kind agent \ + --title "task 42" \ + --actor agent:worker-1 + +tdc fs-journal append-journal-entries \ + --journal-id task-42 \ + --entry-json '{"type":"task.checkpoint","step":"inspection-complete"}' +``` + +## Step 3. Resume in a replacement sandbox + +Inject the same three FS variables into the new sandbox, then restore the durable state: + +```bash +tdc fs read-file --path /tasks/task-42/plan.md +tdc fs-journal read-journal-entries --journal-id task-42 --after-seq 0 +``` + +Continue writing results under the same task path. Use a unique task ID so parallel agents do not overwrite each other's files. + +## Operational notes + +- The FS token is an owner credential. Keep it in a runtime secret store and do not include it in images or task prompts. +- A completed direct data-plane write is remotely visible. For mounted FUSE writes, unmount gracefully before deleting the sandbox. +- Journals preserve ordered workflow evidence; task files preserve mutable working state. Use both when you need state and history. + +## Related reference + +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [tdc fs-journal Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) +- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/examples/tdc-query-sql-with-roles-example.md b/ai/tdc/reference/tdc-query-sql-with-roles-example.md similarity index 97% rename from ai/tdc/examples/tdc-query-sql-with-roles-example.md rename to ai/tdc/reference/tdc-query-sql-with-roles-example.md index f8fb20e3f91f3..8d574a21d8fe6 100644 --- a/ai/tdc/examples/tdc-query-sql-with-roles-example.md +++ b/ai/tdc/reference/tdc-query-sql-with-roles-example.md @@ -111,5 +111,5 @@ rm -f .env.tidb ## What's next -- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) +- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) - [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/tdc/reference/tdc-regions-security-and-limitations.md index 7e6bafc1891ac..612701e9ef24d 100644 --- a/ai/tdc/reference/tdc-regions-security-and-limitations.md +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -98,6 +98,6 @@ Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path ## Related documentation -- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) - [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) - [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md b/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md similarity index 95% rename from ai/tdc/examples/tdc-share-filesystem-across-machines-example.md rename to ai/tdc/reference/tdc-share-filesystem-across-machines-example.md index 7fc69e298aaa7..f291f36946632 100644 --- a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md +++ b/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md @@ -102,5 +102,5 @@ tdc fs delete-file-system \ ## What's next -- [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md) -- [Use a Filesystem in an Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [Use a Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) diff --git a/ai/tdc/guides/tdc-starter-database.md b/ai/tdc/reference/tdc-starter-database.md similarity index 58% rename from ai/tdc/guides/tdc-starter-database.md rename to ai/tdc/reference/tdc-starter-database.md index eede33800021c..0136464095d93 100644 --- a/ai/tdc/guides/tdc-starter-database.md +++ b/ai/tdc/reference/tdc-starter-database.md @@ -1,9 +1,9 @@ --- -title: Manage TiDB Cloud Starter Databases with tdc -summary: Manage Starter clusters and branches, create SQL users, format connection strings, and execute SQL with explicit roles. +title: tdc db Command Reference +summary: Reference every tdc db command for Starter clusters, branches, SQL users, connection strings, and SQL execution. --- -# Manage TiDB Cloud Starter Databases with tdc +# tdc db Command Reference Use `tdc db` to manage TiDB Cloud Starter clusters, branches, and SQL access. @@ -11,6 +11,41 @@ Use `tdc db` to manage TiDB Cloud Starter clusters, branches, and SQL access. > > tdc is currently in Preview. Its features and command-line interface might change without prior notice. +## Command tree + +```text +tdc db +├── create-db-cluster +├── list-db-clusters +├── describe-db-cluster +├── update-db-cluster +├── delete-db-cluster +├── create-db-cluster-branch +├── list-db-cluster-branches +├── describe-db-cluster-branch +├── delete-db-cluster-branch +├── create-db-sql-users +├── format-db-connection-string +└── execute-sql-statement +``` + +## Command details + +| Command | Purpose and key inputs | Example | +| --- | --- | --- | +| `create-db-cluster` | Creates a Starter cluster. Requires `--db-cluster-name`; `--db-cluster-type` is optional and defaults to `starter`. Use `--wait` for an `ACTIVE` result. | `tdc db create-db-cluster --db-cluster-name app-db --wait` | +| `list-db-clusters` | Lists Starter clusters with pagination, filter, ordering, and query support. | `tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name}'` | +| `describe-db-cluster` | Reads one cluster by `--db-cluster-id`; `--view FULL` requests expanded fields. | `tdc db describe-db-cluster --db-cluster-id "" --view FULL` | +| `update-db-cluster` | Changes the name or monthly spending limit of one cluster. Supports `--dry-run`. | `tdc db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2` | +| `delete-db-cluster` | Deletes one cluster by ID. Use `--wait` to wait until deletion is observable. | `tdc db delete-db-cluster --db-cluster-id "" --wait` | +| `create-db-cluster-branch` | Creates a branch from a cluster. Requires cluster ID and branch name; supports `--wait`. | `tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name dev --wait` | +| `list-db-cluster-branches` | Lists branches for one cluster with pagination. | `tdc db list-db-cluster-branches --db-cluster-id "" --output text` | +| `describe-db-cluster-branch` | Reads one branch by cluster ID and branch ID. | `tdc db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id ""` | +| `delete-db-cluster-branch` | Deletes one branch. Supports `--dry-run`. | `tdc db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id ""` | +| `create-db-sql-users` | Idempotently creates or repairs read-only, read-write, and admin users for one cluster. | `tdc db create-db-sql-users --db-cluster-id ""` | +| `format-db-connection-string` | Formats stored SQL credentials as a MySQL URI, JDBC, Go, SQLAlchemy, or environment output. | `tdc db format-db-connection-string --db-cluster-id "" --read-only --format env` | +| `execute-sql-statement` | Executes exactly one statement using read-write by default or an explicit SQL role. | `tdc db execute-sql-statement --db-cluster-id "" --read-only --sql "SELECT 1"` | + ## Prerequisites - Configure tdc with `tdc configure`. @@ -24,15 +59,13 @@ Preview and create a Starter cluster: ```bash tdc db create-db-cluster \ --db-cluster-name demo-cluster \ - --db-cluster-type starter \ --dry-run tdc db create-db-cluster \ - --db-cluster-name demo-cluster \ - --db-cluster-type starter + --db-cluster-name demo-cluster ``` -The configured virtual project is used unless you provide `--project-id`. `--monthly-spending-limit-usd-cents` is optional; setting it can require a payment method. +The configured virtual project is used unless you provide `--project-id`. `--db-cluster-type` is optional and defaults to `starter`; the only accepted explicit value is `starter`. `--monthly-spending-limit-usd-cents` is optional; setting it can require a payment method. List and filter clusters: @@ -182,25 +215,8 @@ tdc db execute-sql-statement \ The default `--transport https` sends the SQL request over HTTPS without a persistent database connection. Use `--transport mysql` as an explicit compatibility fallback; it opens a connection for the command and closes it afterward. -## Command summary - -| Command | Purpose | -| --- | --- | -| `create-db-cluster` | Create a Starter cluster | -| `list-db-clusters` | List Starter clusters | -| `describe-db-cluster` | Read one cluster | -| `update-db-cluster` | Change cluster name or spending limit | -| `delete-db-cluster` | Delete a cluster | -| `create-db-cluster-branch` | Create a branch | -| `list-db-cluster-branches` | List branches | -| `describe-db-cluster-branch` | Read one branch | -| `delete-db-cluster-branch` | Delete a branch | -| `create-db-sql-users` | Create or repair three SQL roles | -| `format-db-connection-string` | Format prepared credentials | -| `execute-sql-statement` | Execute one SQL statement | - ## What's next -- [Query SQL with Explicit Roles](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) +- [Query SQL with Explicit Roles](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) - [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) - [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-troubleshooting.md b/ai/tdc/reference/tdc-troubleshooting.md index e2b2429087825..346b697d03708 100644 --- a/ai/tdc/reference/tdc-troubleshooting.md +++ b/ai/tdc/reference/tdc-troubleshooting.md @@ -5,7 +5,7 @@ summary: Diagnose tdc authentication, project, Filesystem selection, companion, # Troubleshoot tdc -Use this guide to diagnose common current tdc failures. Add `--debug` only when needed; debug output is redacted but should still be reviewed before sharing. +Use this reference to diagnose common current tdc failures. Add `--debug` only when needed; debug output is redacted but should still be reviewed before sharing. > **Note:** > @@ -165,7 +165,7 @@ mkdir -p "$HOME/workspace" tdc fs mount-file-system --mount-path "$HOME/workspace" ``` -Changing the owner or mode of `/workspace` does not bypass AppArmor. If the path cannot change, add explicit `/workspace` mount and unmount rules to `/etc/apparmor.d/local/fusermount3` as described in [Manage TiDB Cloud Filesystem with tdc](/ai/tdc/guides/tdc-filesystem.md#ubuntu-2604-mount-paths). +Changing the owner or mode of `/workspace` does not bypass AppArmor. If the path cannot change, add explicit `/workspace` mount and unmount rules to `/etc/apparmor.d/local/fusermount3` as described in [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md#ubuntu-2604-mount-paths). ## Mount becomes stale after a process crash diff --git a/ai/tdc/examples/tdc-vault-agent-secrets-example.md b/ai/tdc/reference/tdc-vault-agent-secrets-example.md similarity index 97% rename from ai/tdc/examples/tdc-vault-agent-secrets-example.md rename to ai/tdc/reference/tdc-vault-agent-secrets-example.md index 1b6efcaad23b4..543da0688e721 100644 --- a/ai/tdc/examples/tdc-vault-agent-secrets-example.md +++ b/ai/tdc/reference/tdc-vault-agent-secrets-example.md @@ -105,5 +105,5 @@ rm -f ./api-token.txt ## What's next -- [Use TiDB Cloud Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) +- [tdc fs-vault Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) - [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/tdc-overview.md b/ai/tdc/tdc-overview.md index a5577046446d8..c47d0257c8412 100644 --- a/ai/tdc/tdc-overview.md +++ b/ai/tdc/tdc-overview.md @@ -63,37 +63,36 @@ You do not need to install, configure, or invoke Drive9 separately for normal td ## Find the right documentation - Follow the [Quick Start](/ai/tdc/tdc-quick-start.md) to install tdc and complete your first Starter or Filesystem workflow. -- Read [Concepts and Architecture](/ai/tdc/concepts/tdc-concepts-and-architecture.md) to understand profiles, credentials, regions, SQL roles, and the Filesystem companion. - -### Guides - -Use guides to complete one focused task or manage one feature area: - -- [Install, Configure, and Update tdc](/ai/tdc/guides/tdc-install-configure-update.md) -- [Manage Projects in TiDB Cloud Organizations with tdc](/ai/tdc/guides/tdc-organization.md) -- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) -- [Manage TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem.md) -- [Use Git Workspaces on TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem-git.md) -- [Use Filesystem Journals](/ai/tdc/guides/tdc-filesystem-journal.md) -- [Use Filesystem Vault](/ai/tdc/guides/tdc-filesystem-vault.md) +- Use the command references for exact command trees, inputs, behavior, and examples: + +- [Install, Configure, and Update tdc](/ai/tdc/reference/tdc-install-configure-update.md) +- [Manage Projects in TiDB Cloud Organizations with tdc](/ai/tdc/reference/tdc-organization.md) +- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [tdc fs-git Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) +- [tdc fs-journal Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) +- [tdc fs-vault Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) - [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) -### Examples +### Scenario references -Use examples to follow a complete scenario that combines multiple commands and features: +Use scenarios to follow a complete workflow that combines multiple commands and features: For users and automation: -- [Run a Daily tdc Workflow](/ai/tdc/examples/tdc-daily-workflow-example.md) -- [Query SQL with Explicit Roles](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) -- [Share a Filesystem Across Machines](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) +- [Run a Daily tdc Workflow](/ai/tdc/reference/tdc-daily-workflow-example.md) +- [Query SQL with Explicit Roles](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) +- [Share a Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) +- [Hand Off CI Artifacts Between Jobs](/ai/tdc/reference/tdc-ci-artifact-handoff-example.md) For AI agents: -- [Use a Filesystem in an Agent Sandbox](/ai/tdc/examples/tdc-agent-sandbox-example.md) -- [Prepare a Git Workspace for Agents](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) -- [Record an Agent Workflow in a Journal](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) -- [Delegate Secrets to an Agent](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) +- [Use a Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) +- [Persist Agent State Across Sandboxes](/ai/tdc/reference/tdc-persistent-agent-state-example.md) +- [Share a Read-Only Dataset Across Parallel Agents](/ai/tdc/reference/tdc-parallel-agent-dataset-example.md) +- [Prepare a Git Workspace for Agents](/ai/tdc/reference/tdc-git-workspace-for-agents-example.md) +- [Record an Agent Workflow in a Journal](/ai/tdc/reference/tdc-journal-agent-workflow-example.md) +- [Delegate Secrets to an Agent](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) ### Reference diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index 7787baa3b8ae8..c7d246dea7fb1 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -115,7 +115,6 @@ Create a Starter cluster and save its ID: ```bash export TDC_DB_CLUSTER_ID="$(tdc db create-db-cluster \ --db-cluster-name quickstart-db \ - --db-cluster-type starter \ --wait \ --query id \ --output text)" @@ -147,6 +146,6 @@ unset TDC_DB_CLUSTER_ID ## What's next -- [Manage TiDB Cloud Starter Databases](/ai/tdc/guides/tdc-starter-database.md) -- [Manage TiDB Cloud Filesystem](/ai/tdc/guides/tdc-filesystem.md) +- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) - [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) From 66db63c015cfcfa47ecb59c0a4691a9992774505 Mon Sep 17 00:00:00 2001 From: Cheese Date: Wed, 22 Jul 2026 22:24:26 +0800 Subject: [PATCH 12/29] docs: add per-command tdc reference pages --- TOC-ai.md | 79 +++++++++++++++++-- ai/_index.md | 19 ++--- .../db/tdc-db-create-db-cluster-branch.md | 38 +++++++++ .../commands/db/tdc-db-create-db-cluster.md | 40 ++++++++++ .../commands/db/tdc-db-create-db-sql-users.md | 36 +++++++++ .../db/tdc-db-delete-db-cluster-branch.md | 37 +++++++++ .../commands/db/tdc-db-delete-db-cluster.md | 37 +++++++++ .../db/tdc-db-describe-db-cluster-branch.md | 37 +++++++++ .../commands/db/tdc-db-describe-db-cluster.md | 36 +++++++++ .../db/tdc-db-execute-sql-statement.md | 41 ++++++++++ .../db/tdc-db-format-db-connection-string.md | 43 ++++++++++ .../db/tdc-db-list-db-cluster-branches.md | 37 +++++++++ .../commands/db/tdc-db-list-db-clusters.md | 39 +++++++++ .../commands/db/tdc-db-update-db-cluster.md | 38 +++++++++ .../fs-git/tdc-fs-git-add-git-worktree.md | 44 +++++++++++ .../fs-git/tdc-fs-git-clone-git-workspace.md | 41 ++++++++++ .../tdc-fs-git-hydrate-git-workspace.md | 38 +++++++++ .../fs-git/tdc-fs-git-remove-git-worktree.md | 39 +++++++++ .../tdc-fs-journal-append-journal-entries.md | 44 +++++++++++ .../tdc-fs-journal-create-journal.md | 42 ++++++++++ .../tdc-fs-journal-read-journal-entries.md | 39 +++++++++ .../tdc-fs-journal-search-journal-entries.md | 47 +++++++++++ .../tdc-fs-journal-verify-journal.md | 37 +++++++++ .../fs-vault/tdc-fs-vault-create-grant.md | 43 ++++++++++ .../fs-vault/tdc-fs-vault-create-secret.md | 39 +++++++++ .../fs-vault/tdc-fs-vault-delete-grant.md | 40 ++++++++++ .../fs-vault/tdc-fs-vault-delete-secret.md | 38 +++++++++ .../tdc-fs-vault-list-audit-events.md | 40 ++++++++++ .../fs-vault/tdc-fs-vault-list-secrets.md | 37 +++++++++ .../fs-vault/tdc-fs-vault-mount-vault.md | 41 ++++++++++ .../fs-vault/tdc-fs-vault-read-secret.md | 40 ++++++++++ .../fs-vault/tdc-fs-vault-replace-secret.md | 39 +++++++++ .../fs-vault/tdc-fs-vault-run-with-secret.md | 38 +++++++++ .../fs-vault/tdc-fs-vault-unmount-vault.md | 39 +++++++++ .../commands/fs/tdc-fs-check-file-system.md | 36 +++++++++ .../commands/fs/tdc-fs-chmod-file.md | 39 +++++++++ .../commands/fs/tdc-fs-commit-layer.md | 38 +++++++++ .../reference/commands/fs/tdc-fs-copy-file.md | 51 ++++++++++++ .../commands/fs/tdc-fs-create-directory.md | 39 +++++++++ .../commands/fs/tdc-fs-create-file-system.md | 38 +++++++++ .../commands/fs/tdc-fs-create-hardlink.md | 39 +++++++++ .../fs/tdc-fs-create-layer-checkpoint.md | 40 ++++++++++ .../commands/fs/tdc-fs-create-layer.md | 43 ++++++++++ .../commands/fs/tdc-fs-create-symlink.md | 39 +++++++++ .../commands/fs/tdc-fs-delete-file-system.md | 37 +++++++++ .../commands/fs/tdc-fs-delete-file.md | 39 +++++++++ .../fs/tdc-fs-describe-file-system.md | 35 ++++++++ .../commands/fs/tdc-fs-describe-file.md | 37 +++++++++ .../commands/fs/tdc-fs-describe-layer.md | 37 +++++++++ .../commands/fs/tdc-fs-diff-layer.md | 38 +++++++++ .../commands/fs/tdc-fs-drain-file-system.md | 37 +++++++++ .../commands/fs/tdc-fs-find-files.md | 46 +++++++++++ .../commands/fs/tdc-fs-list-file-systems.md | 34 ++++++++ .../commands/fs/tdc-fs-list-files.md | 37 +++++++++ .../commands/fs/tdc-fs-list-layers.md | 36 +++++++++ .../commands/fs/tdc-fs-mount-file-system.md | 53 +++++++++++++ .../reference/commands/fs/tdc-fs-move-file.md | 40 ++++++++++ .../commands/fs/tdc-fs-pack-file-system.md | 43 ++++++++++ .../reference/commands/fs/tdc-fs-read-file.md | 39 +++++++++ .../commands/fs/tdc-fs-rollback-layer.md | 38 +++++++++ .../commands/fs/tdc-fs-search-file-content.md | 40 ++++++++++ .../fs/tdc-fs-set-default-file-system.md | 36 +++++++++ .../commands/fs/tdc-fs-unmount-file-system.md | 41 ++++++++++ .../commands/fs/tdc-fs-unpack-file-system.md | 43 ++++++++++ .../fs/tdc-fs-unset-default-file-system.md | 35 ++++++++ .../tdc-organization-list-projects.md | 36 +++++++++ .../reference/commands/tdc/tdc-configure.md | 38 +++++++++ ai/tdc/reference/commands/tdc/tdc-update.md | 38 +++++++++ ai/tdc/reference/tdc-cli-reference.md | 23 +++--- 69 files changed, 2693 insertions(+), 27 deletions(-) create mode 100644 ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md create mode 100644 ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md create mode 100644 ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md create mode 100644 ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md create mode 100644 ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md create mode 100644 ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md create mode 100644 ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md create mode 100644 ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md create mode 100644 ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md create mode 100644 ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md create mode 100644 ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md create mode 100644 ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md create mode 100644 ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md create mode 100644 ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md create mode 100644 ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md create mode 100644 ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md create mode 100644 ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md create mode 100644 ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md create mode 100644 ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md create mode 100644 ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md create mode 100644 ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md create mode 100644 ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md create mode 100644 ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md create mode 100644 ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md create mode 100644 ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md create mode 100644 ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md create mode 100644 ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md create mode 100644 ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md create mode 100644 ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md create mode 100644 ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md create mode 100644 ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md create mode 100644 ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-copy-file.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-create-directory.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-create-layer.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-delete-file.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-describe-file.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-find-files.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-list-files.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-list-layers.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-move-file.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-read-file.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-set-default-file-system.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-unset-default-file-system.md create mode 100644 ai/tdc/reference/commands/organization/tdc-organization-list-projects.md create mode 100644 ai/tdc/reference/commands/tdc/tdc-configure.md create mode 100644 ai/tdc/reference/commands/tdc/tdc-update.md diff --git a/TOC-ai.md b/TOC-ai.md index 7d49e5203ca9b..5d9a208c466ed 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -89,13 +89,78 @@ - [Overview](/ai/tdc/tdc-overview.md) - Command Reference - [CLI Syntax and Global Behavior](/ai/tdc/reference/tdc-cli-reference.md) - - [Install, Configure, and Update](/ai/tdc/reference/tdc-install-configure-update.md) - - [Organization and Projects](/ai/tdc/reference/tdc-organization.md) - - [Starter Databases and SQL](/ai/tdc/reference/tdc-starter-database.md) - - [Filesystem](/ai/tdc/reference/tdc-filesystem.md) - - [Filesystem Git Workspaces](/ai/tdc/reference/tdc-filesystem-git.md) - - [Filesystem Journals](/ai/tdc/reference/tdc-filesystem-journal.md) - - [Filesystem Vault](/ai/tdc/reference/tdc-filesystem-vault.md) + - [configure](/ai/tdc/reference/commands/tdc/tdc-configure.md) + - [update](/ai/tdc/reference/commands/tdc/tdc-update.md) + - organization + - [list-projects](/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md) + - db + - [create-db-cluster](/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md) + - [list-db-clusters](/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md) + - [describe-db-cluster](/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md) + - [update-db-cluster](/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md) + - [delete-db-cluster](/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md) + - [create-db-cluster-branch](/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md) + - [list-db-cluster-branches](/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md) + - [describe-db-cluster-branch](/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md) + - [delete-db-cluster-branch](/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md) + - [create-db-sql-users](/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md) + - [format-db-connection-string](/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md) + - [execute-sql-statement](/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md) + - fs + - [create-file-system](/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md) + - [list-file-systems](/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md) + - [describe-file-system](/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md) + - [set-default-file-system](/ai/tdc/reference/commands/fs/tdc-fs-set-default-file-system.md) + - [unset-default-file-system](/ai/tdc/reference/commands/fs/tdc-fs-unset-default-file-system.md) + - [check-file-system](/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md) + - [delete-file-system](/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md) + - [copy-file](/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md) + - [read-file](/ai/tdc/reference/commands/fs/tdc-fs-read-file.md) + - [list-files](/ai/tdc/reference/commands/fs/tdc-fs-list-files.md) + - [describe-file](/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md) + - [move-file](/ai/tdc/reference/commands/fs/tdc-fs-move-file.md) + - [delete-file](/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md) + - [create-directory](/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md) + - [chmod-file](/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md) + - [create-symlink](/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md) + - [create-hardlink](/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md) + - [search-file-content](/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md) + - [find-files](/ai/tdc/reference/commands/fs/tdc-fs-find-files.md) + - [create-layer](/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md) + - [list-layers](/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md) + - [describe-layer](/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md) + - [diff-layer](/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md) + - [create-layer-checkpoint](/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md) + - [rollback-layer](/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md) + - [commit-layer](/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md) + - [pack-file-system](/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md) + - [unpack-file-system](/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md) + - [mount-file-system](/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md) + - [drain-file-system](/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md) + - [unmount-file-system](/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md) + - fs-git + - [clone-git-workspace](/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md) + - [hydrate-git-workspace](/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md) + - [add-git-worktree](/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md) + - [remove-git-worktree](/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md) + - fs-journal + - [create-journal](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md) + - [append-journal-entries](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md) + - [read-journal-entries](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md) + - [search-journal-entries](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md) + - [verify-journal](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md) + - fs-vault + - [create-secret](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md) + - [replace-secret](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md) + - [read-secret](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md) + - [list-secrets](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md) + - [delete-secret](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md) + - [create-grant](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md) + - [delete-grant](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md) + - [list-audit-events](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md) + - [run-with-secret](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md) + - [mount-vault](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md) + - [unmount-vault](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md) - Scenarios for Users and Automation - [Automate Daily Database Operations](/ai/tdc/reference/tdc-daily-workflow-example.md) - [Run SQL Queries with Role-Based Access](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) diff --git a/ai/_index.md b/ai/_index.md index 72e6069fda98f..83b962a76b979 100644 --- a/ai/_index.md +++ b/ai/_index.md @@ -85,21 +85,22 @@ Technical reference documentation for TiDB's AI and vector search features. ### TiDB Cloud CLI (tdc) (Preview) -The command references document every tdc command family and provide examples for each operation. The scenario references combine commands into complete user, automation, and AI agent workflows. +The command reference follows the two-level tdc command tree. Every command has a dedicated page with its syntax and examples. Expand **Command Reference** in the documentation navigation to browse commands by family. #### Command reference | Document | Description | | --- | --- | | [tdc Overview](/ai/tdc/tdc-overview.md) | Decide when to use tdc and understand its scope relative to ticloud and the TiDB Cloud console. | -| [CLI Syntax and Global Behavior](/ai/tdc/reference/tdc-cli-reference.md) | Command tree, global flags, output, queries, dry-run, help, errors, and aliases. | -| [Install, Configure, and Update](/ai/tdc/reference/tdc-install-configure-update.md) | Install releases, configure profiles, update, and uninstall tdc. | -| [Organization and Projects](/ai/tdc/reference/tdc-organization.md) | List projects and understand virtual-project selection. | -| [Starter Databases and SQL](/ai/tdc/reference/tdc-starter-database.md) | Manage clusters, branches, SQL users, connection strings, and SQL execution. | -| [Filesystem](/ai/tdc/reference/tdc-filesystem.md) | Manage resources, data, layers, packs, and FUSE or WebDAV mounts. | -| [Filesystem Git Workspaces](/ai/tdc/reference/tdc-filesystem-git.md) | Clone, hydrate, and manage linked Git worktrees. | -| [Filesystem Journals](/ai/tdc/reference/tdc-filesystem-journal.md) | Record, search, and verify append-only workflow events. | -| [Filesystem Vault](/ai/tdc/reference/tdc-filesystem-vault.md) | Store secrets, delegate access, audit, inject, and mount a read-only vault. | +| [CLI Syntax and Global Behavior](/ai/tdc/reference/tdc-cli-reference.md) | Command tree, global flags, output, queries, dry-run, help, errors, aliases, and links to command pages. | +| [`tdc configure`](/ai/tdc/reference/commands/tdc/tdc-configure.md) | Configure a local profile interactively or non-interactively. | +| [`tdc update`](/ai/tdc/reference/commands/tdc/tdc-update.md) | Check for and install release updates. | +| [`tdc organization list-projects`](/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md) | List accessible TiDB Cloud projects. | +| [`tdc db create-db-cluster`](/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md) | Start with the database command reference. | +| [`tdc fs create-file-system`](/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md) | Start with the Filesystem command reference. | +| [`tdc fs-git clone-git-workspace`](/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md) | Start with the Filesystem Git command reference. | +| [`tdc fs-journal create-journal`](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md) | Start with the Filesystem journal command reference. | +| [`tdc fs-vault create-secret`](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md) | Start with the Filesystem Vault command reference. | | [Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) | Profiles, precedence, local state, credentials, mount locators, and logs. | | [Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) | Placement, authentication boundaries, platforms, durability, and Preview constraints. | | [Troubleshooting](/ai/tdc/reference/tdc-troubleshooting.md) | Diagnose authentication, quota, SQL, companion, selection, and mount failures. | diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md new file mode 100644 index 0000000000000..4fb1af326db08 --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md @@ -0,0 +1,38 @@ +--- +title: tdc db create-db-cluster-branch +summary: Create a branch for a TiDB Cloud Starter cluster. +--- + +# tdc db create-db-cluster-branch + +Creates a branch for one Starter cluster. `--wait` waits for the branch to become `ACTIVE`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db create-db-cluster-branch + --db-cluster-branch-name + --db-cluster-id + [--dry-run] + [--help] + [--version] + [--wait] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name dev --wait +tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name preview --dry-run +``` diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md new file mode 100644 index 0000000000000..2e790ddfe5798 --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md @@ -0,0 +1,40 @@ +--- +title: tdc db create-db-cluster +summary: Create a TiDB Cloud Starter cluster. +--- + +# tdc db create-db-cluster + +Creates a Starter cluster. `--db-cluster-type` defaults to `starter`, and `--wait` waits for the cluster to become `ACTIVE`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db create-db-cluster + --db-cluster-name + [--db-cluster-type ] + [--dry-run] + [--help] + [--monthly-spending-limit-usd-cents ] + [--project-id ] + [--version] + [--wait] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db create-db-cluster --db-cluster-name app-db --wait +tdc db create-db-cluster --db-cluster-name app-db --dry-run +``` diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md b/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md new file mode 100644 index 0000000000000..d2d06f8c46064 --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md @@ -0,0 +1,36 @@ +--- +title: tdc db create-db-sql-users +summary: Create tdc-managed SQL users for a Starter cluster. +--- + +# tdc db create-db-sql-users + +Idempotently creates or repairs the read-only, read-write, and admin SQL users managed by tdc. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db create-db-sql-users + --db-cluster-id + [--dry-run] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db create-db-sql-users --db-cluster-id "" --dry-run +tdc db create-db-sql-users --db-cluster-id "" +``` diff --git a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md new file mode 100644 index 0000000000000..e665abe498fde --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md @@ -0,0 +1,37 @@ +--- +title: tdc db delete-db-cluster-branch +summary: Delete a branch from a TiDB Cloud Starter cluster. +--- + +# tdc db delete-db-cluster-branch + +Deletes one branch from a Starter cluster. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db delete-db-cluster-branch + --db-cluster-branch-id + --db-cluster-id + [--dry-run] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" --dry-run +tdc db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" +``` diff --git a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md new file mode 100644 index 0000000000000..f3c2f5790ea30 --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md @@ -0,0 +1,37 @@ +--- +title: tdc db delete-db-cluster +summary: Delete a TiDB Cloud Starter cluster. +--- + +# tdc db delete-db-cluster + +Deletes one Starter cluster. `--wait` waits until deletion is observable. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db delete-db-cluster + --db-cluster-id + [--dry-run] + [--help] + [--version] + [--wait] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db delete-db-cluster --db-cluster-id "" --dry-run +tdc db delete-db-cluster --db-cluster-id "" --wait +``` diff --git a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md new file mode 100644 index 0000000000000..11eb4aaff881f --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md @@ -0,0 +1,37 @@ +--- +title: tdc db describe-db-cluster-branch +summary: Describe a branch for a TiDB Cloud Starter cluster. +--- + +# tdc db describe-db-cluster-branch + +Describes one branch by cluster ID and branch ID. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db describe-db-cluster-branch + --db-cluster-branch-id + --db-cluster-id + [--help] + [--version] + [--view ] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" +tdc db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" --view FULL +``` diff --git a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md new file mode 100644 index 0000000000000..76d51fbaf40b5 --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md @@ -0,0 +1,36 @@ +--- +title: tdc db describe-db-cluster +summary: Describe a TiDB Cloud Starter cluster. +--- + +# tdc db describe-db-cluster + +Describes one Starter cluster. Use `--view FULL` to request expanded fields. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db describe-db-cluster + --db-cluster-id + [--help] + [--version] + [--view ] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db describe-db-cluster --db-cluster-id "" +tdc db describe-db-cluster --db-cluster-id "" --view FULL +``` diff --git a/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md b/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md new file mode 100644 index 0000000000000..440b32a11eb50 --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md @@ -0,0 +1,41 @@ +--- +title: tdc db execute-sql-statement +summary: Execute one SQL statement against a TiDB Cloud Starter cluster. +--- + +# tdc db execute-sql-statement + +Executes exactly one SQL statement. Read-write is the default role; explicit role selection is recommended. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db execute-sql-statement + --db-cluster-id + --sql + [--admin] + [--database ] + [--help] + [--read-only] + [--read-write] + [--transport ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db execute-sql-statement --db-cluster-id "" --read-only --sql "SELECT 1" --output text +tdc db execute-sql-statement --db-cluster-id "" --admin --sql "CREATE DATABASE IF NOT EXISTS app" +``` diff --git a/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md b/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md new file mode 100644 index 0000000000000..cc223b6abd8db --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md @@ -0,0 +1,43 @@ +--- +title: tdc db format-db-connection-string +summary: Format a connection string for a tdc-managed SQL user. +--- + +# tdc db format-db-connection-string + +Formats stored SQL credentials for read-write, read-only, or admin access. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db format-db-connection-string + --db-cluster-id + [--admin] + [--database ] + [--env-database-url-name ] + [--env-include-database-url] + [--env-prefix ] + [--format ] + [--help] + [--read-only] + [--read-write] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db format-db-connection-string --db-cluster-id "" --read-write --format mysql-uri +tdc db format-db-connection-string --db-cluster-id "" --read-only --format env --env-prefix TIDB_ +``` diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md b/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md new file mode 100644 index 0000000000000..03f63fd887339 --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md @@ -0,0 +1,37 @@ +--- +title: tdc db list-db-cluster-branches +summary: List branches for a TiDB Cloud Starter cluster. +--- + +# tdc db list-db-cluster-branches + +Lists branches for one Starter cluster, with optional pagination. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db list-db-cluster-branches + --db-cluster-id + [--help] + [--page-size ] + [--page-token ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db list-db-cluster-branches --db-cluster-id "" --output text +tdc db list-db-cluster-branches --db-cluster-id "" --query 'branches[].id' +``` diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md new file mode 100644 index 0000000000000..614988ccf8304 --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md @@ -0,0 +1,39 @@ +--- +title: tdc db list-db-clusters +summary: List TiDB Cloud Starter clusters. +--- + +# tdc db list-db-clusters + +Lists Starter clusters with optional pagination, filtering, ordering, and JMESPath projection. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db list-db-clusters + [--filter ] + [--help] + [--order-by ] + [--page-size ] + [--page-token ] + [--skip ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db list-db-clusters --output text +tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name,state:state}' +``` diff --git a/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md new file mode 100644 index 0000000000000..1ef8bf2b21b06 --- /dev/null +++ b/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md @@ -0,0 +1,38 @@ +--- +title: tdc db update-db-cluster +summary: Update a TiDB Cloud Starter cluster. +--- + +# tdc db update-db-cluster + +Updates the display name or monthly spending limit of one Starter cluster. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc db update-db-cluster + --db-cluster-id + [--db-cluster-name ] + [--dry-run] + [--help] + [--monthly-spending-limit-usd-cents ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2 +tdc db update-db-cluster --db-cluster-id "" --monthly-spending-limit-usd-cents 1000 --dry-run +``` diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md new file mode 100644 index 0000000000000..df61065804850 --- /dev/null +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md @@ -0,0 +1,44 @@ +--- +title: tdc fs-git add-git-worktree +summary: Add a linked Git worktree in a mounted TiDB Cloud Filesystem. +--- + +# tdc fs-git add-git-worktree + +Adds a linked Git worktree from a base workspace. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-git add-git-worktree + --base-path + --worktree-path + [--blobless] + [--branch-name ] + [--commit-ish ] + [--detach] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--hydrate ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-git add-git-worktree --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-feature --branch-name feature-x +tdc fs-git add-git-worktree --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-review --commit-ish origin/main --detach +``` diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md new file mode 100644 index 0000000000000..07abc4d976467 --- /dev/null +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md @@ -0,0 +1,41 @@ +--- +title: tdc fs-git clone-git-workspace +summary: Clone a Git repository into a mounted TiDB Cloud Filesystem. +--- + +# tdc fs-git clone-git-workspace + +Clones a repository into a mounted Filesystem path. Hydration can run synchronously or in the background. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-git clone-git-workspace + --repo-url + --target-path + [--blobless] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--hydrate ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-git clone-git-workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb +tdc fs-git clone-git-workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate background +``` diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md new file mode 100644 index 0000000000000..27d9e30e32bfe --- /dev/null +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md @@ -0,0 +1,38 @@ +--- +title: tdc fs-git hydrate-git-workspace +summary: Hydrate clean Git objects in a tdc Git workspace. +--- + +# tdc fs-git hydrate-git-workspace + +Hydrates clean Git objects for an existing tdc Git workspace. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-git hydrate-git-workspace + --target-path + [--file-system-name ] + [--fs-token ] + [--help] + [--timeout ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-git hydrate-git-workspace --target-path /path/to/workspace/tidb +tdc fs-git hydrate-git-workspace --target-path /path/to/workspace/tidb --timeout 30m +``` diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md new file mode 100644 index 0000000000000..3fcfd41b16002 --- /dev/null +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md @@ -0,0 +1,39 @@ +--- +title: tdc fs-git remove-git-worktree +summary: Remove a linked Git worktree from a mounted TiDB Cloud Filesystem. +--- + +# tdc fs-git remove-git-worktree + +Removes a linked worktree without recursively deleting shared clean-tree data. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-git remove-git-worktree + --worktree-path + [--dry-run] + [--file-system-name ] + [--force] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-git remove-git-worktree --worktree-path /path/to/workspace/tidb-feature --dry-run +tdc fs-git remove-git-worktree --worktree-path /path/to/workspace/tidb-feature --force +``` diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md new file mode 100644 index 0000000000000..0a98c792c4cac --- /dev/null +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md @@ -0,0 +1,44 @@ +--- +title: tdc fs-journal append-journal-entries +summary: Append entries to a Filesystem journal. +--- + +# tdc fs-journal append-journal-entries + +Appends one JSON event or a JSON array to a journal. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-journal append-journal-entries + --journal-id + [--dry-run] + [--entry-json ] + [--entry-type ] + [--file-system-name ] + [--fs-token ] + [--help] + [--idempotency-key ] + [--json-array] + [--source ] + [--subject ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-journal append-journal-entries --journal-id jrn-demo --entry-json '{"type":"task.started"}' +tdc fs-journal append-journal-entries --journal-id jrn-demo --entry-type task.completed --subject issue-42 --idempotency-key issue-42-complete +``` diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md new file mode 100644 index 0000000000000..735e214c6e63f --- /dev/null +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md @@ -0,0 +1,42 @@ +--- +title: tdc fs-journal create-journal +summary: Create an append-only Filesystem journal. +--- + +# tdc fs-journal create-journal + +Creates a journal. If `--journal-id` is omitted, the service generates one. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-journal create-journal + [--actor ] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--journal-id ] + [--journal-kind ] + [--label ] + [--title ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-journal create-journal --journal-id jrn-demo --journal-kind agent --title "demo task" +tdc fs-journal create-journal --journal-kind deployment --actor agent:tdc --label env=dev --dry-run +``` diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md new file mode 100644 index 0000000000000..03b8a171f1822 --- /dev/null +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md @@ -0,0 +1,39 @@ +--- +title: tdc fs-journal read-journal-entries +summary: Read entries from a Filesystem journal. +--- + +# tdc fs-journal read-journal-entries + +Reads entries from one journal in sequence order. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-journal read-journal-entries + --journal-id + [--after-seq ] + [--file-system-name ] + [--fs-token ] + [--help] + [--limit ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-journal read-journal-entries --journal-id jrn-demo +tdc fs-journal read-journal-entries --journal-id jrn-demo --after-seq 100 --limit 50 +``` diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md new file mode 100644 index 0000000000000..a71b34887af2f --- /dev/null +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md @@ -0,0 +1,47 @@ +--- +title: tdc fs-journal search-journal-entries +summary: Search Filesystem journals and entries. +--- + +# tdc fs-journal search-journal-entries + +Searches journals and optionally returns matching entries. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-journal search-journal-entries + [--actor ] + [--cursor ] + [--entry-type ] + [--file-system-name ] + [--fs-token ] + [--help] + [--include-entries] + [--journal-kind ] + [--label ] + [--limit ] + [--since ] + [--status ] + [--subject ] + [--until ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-journal search-journal-entries --entry-type task.started --include-entries +tdc fs-journal search-journal-entries --label env=dev --since 2026-07-01T00:00:00Z --limit 100 +``` diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md new file mode 100644 index 0000000000000..812d76bebbe22 --- /dev/null +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md @@ -0,0 +1,37 @@ +--- +title: tdc fs-journal verify-journal +summary: Verify a Filesystem journal hash chain. +--- + +# tdc fs-journal verify-journal + +Verifies the integrity of one journal hash chain. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-journal verify-journal + --journal-id + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-journal verify-journal --journal-id jrn-demo +tdc fs-journal verify-journal --journal-id jrn-demo --output text +``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md new file mode 100644 index 0000000000000..43a5954847bde --- /dev/null +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md @@ -0,0 +1,43 @@ +--- +title: tdc fs-vault create-grant +summary: Create a delegated Filesystem Vault grant. +--- + +# tdc fs-vault create-grant + +Creates a time-limited delegated grant for one agent and scope. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-vault create-grant + --agent-id + --permission + --scope + --ttl + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--label-hint ] + [--token-only] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-vault create-grant --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m +tdc fs-vault create-grant --agent-id ci-agent --scope api-dev/TOKEN --permission read --ttl 5m --token-only +``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md new file mode 100644 index 0000000000000..7ebd4d4b96633 --- /dev/null +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md @@ -0,0 +1,39 @@ +--- +title: tdc fs-vault create-secret +summary: Create a secret in Filesystem Vault. +--- + +# tdc fs-vault create-secret + +Creates a secret from one or more `NAME=value` or `NAME=@file` fields. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-vault create-secret + --field + --secret-name + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-vault create-secret --secret-name db-prod --field DB_URL=mysql://example --field PASSWORD=@./password.txt +tdc fs-vault create-secret --secret-name api-dev --field TOKEN=@./token.txt --dry-run +``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md new file mode 100644 index 0000000000000..904511239cf81 --- /dev/null +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md @@ -0,0 +1,40 @@ +--- +title: tdc fs-vault delete-grant +summary: Revoke a delegated Filesystem Vault grant. +--- + +# tdc fs-vault delete-grant + +Revokes one delegated Filesystem Vault grant. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-vault delete-grant + --grant-id + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--reason ] + [--revoked-by ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-vault delete-grant --grant-id "" --reason rotated +tdc fs-vault delete-grant --grant-id "" --revoked-by operator --dry-run +``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md new file mode 100644 index 0000000000000..8b08a5d90b123 --- /dev/null +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md @@ -0,0 +1,38 @@ +--- +title: tdc fs-vault delete-secret +summary: Delete a secret from Filesystem Vault. +--- + +# tdc fs-vault delete-secret + +Deletes one Filesystem Vault secret. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-vault delete-secret + --secret-name + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-vault delete-secret --secret-name db-prod --dry-run +tdc fs-vault delete-secret --secret-name db-prod +``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md new file mode 100644 index 0000000000000..af53d7431cb84 --- /dev/null +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md @@ -0,0 +1,40 @@ +--- +title: tdc fs-vault list-audit-events +summary: List Filesystem Vault audit events. +--- + +# tdc fs-vault list-audit-events + +Lists vault audit events with optional agent, secret, and time filters. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-vault list-audit-events + [--agent-id ] + [--file-system-name ] + [--fs-token ] + [--help] + [--limit ] + [--secret-name ] + [--since ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-vault list-audit-events --secret-name db-prod --limit 20 +tdc fs-vault list-audit-events --agent-id deploy-agent --since 24h --output text +``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md new file mode 100644 index 0000000000000..2e58565973398 --- /dev/null +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md @@ -0,0 +1,37 @@ +--- +title: tdc fs-vault list-secrets +summary: List secrets visible to a Filesystem Vault credential. +--- + +# tdc fs-vault list-secrets + +Lists secrets visible to the active owner or delegated credential. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-vault list-secrets + [--file-system-name ] + [--fs-token ] + [--help] + [--vault-token ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-vault list-secrets +tdc fs-vault list-secrets --vault-token "$TDC_VAULT_TOKEN" --output text +``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md new file mode 100644 index 0000000000000..cf923a1180792 --- /dev/null +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md @@ -0,0 +1,41 @@ +--- +title: tdc fs-vault mount-vault +summary: Mount a read-only Filesystem Vault view. +--- + +# tdc fs-vault mount-vault + +Mounts readable vault fields as a local read-only FUSE filesystem. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-vault mount-vault + --mount-path + [--dry-run] + [--file-system-name ] + [--foreground] + [--fs-token ] + [--help] + [--ready-timeout ] + [--vault-token ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-vault mount-vault --mount-path ./vault --vault-token "$TDC_VAULT_TOKEN" +tdc fs-vault mount-vault --mount-path ./vault --foreground --ready-timeout 60s +``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md new file mode 100644 index 0000000000000..23136e997a7ae --- /dev/null +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md @@ -0,0 +1,40 @@ +--- +title: tdc fs-vault read-secret +summary: Read a secret from Filesystem Vault. +--- + +# tdc fs-vault read-secret + +Reads a complete secret or one field using an owner or delegated credential. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-vault read-secret + --secret-name + [--field ] + [--file-system-name ] + [--format ] + [--fs-token ] + [--help] + [--vault-token ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-vault read-secret --secret-name db-prod --field PASSWORD --format raw +tdc fs-vault read-secret --secret-name db-prod --field DB_URL --format env +``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md new file mode 100644 index 0000000000000..8f90d734c8aa6 --- /dev/null +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md @@ -0,0 +1,39 @@ +--- +title: tdc fs-vault replace-secret +summary: Replace all fields in a Filesystem Vault secret. +--- + +# tdc fs-vault replace-secret + +Replaces all fields in one secret from files in a local directory. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-vault replace-secret + --from-directory + --secret-path + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-vault replace-secret --secret-path /n/vault/db-prod --from-directory ./secret-fields +tdc fs-vault replace-secret --secret-path /n/vault/db-prod --from-directory ./secret-fields --dry-run +``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md new file mode 100644 index 0000000000000..ca024f6c9d439 --- /dev/null +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md @@ -0,0 +1,38 @@ +--- +title: tdc fs-vault run-with-secret +summary: Run a process with a Filesystem Vault secret. +--- + +# tdc fs-vault run-with-secret + +Runs a command with one secret injected into its environment. Arguments after `--` are passed to the child command. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-vault run-with-secret + --secret-path + [--file-system-name ] + [--fs-token ] + [--help] + [--vault-token ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-vault run-with-secret --secret-path /n/vault/db-prod -- env +tdc fs-vault run-with-secret --secret-path /n/vault/db-prod -- sh -c 'test -n "$DB_URL"' +``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md new file mode 100644 index 0000000000000..861147d65de43 --- /dev/null +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md @@ -0,0 +1,39 @@ +--- +title: tdc fs-vault unmount-vault +summary: Unmount a Filesystem Vault view. +--- + +# tdc fs-vault unmount-vault + +Unmounts a local Filesystem Vault filesystem. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs-vault unmount-vault + --mount-path + [--dry-run] + [--force] + [--help] + [--ignore-absent] + [--timeout ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs-vault unmount-vault --mount-path ./vault +tdc fs-vault unmount-vault --mount-path ./vault --ignore-absent +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md new file mode 100644 index 0000000000000..c7b50b55b157a --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md @@ -0,0 +1,36 @@ +--- +title: tdc fs check-file-system +summary: Check TiDB Cloud Filesystem connectivity. +--- + +# tdc fs check-file-system + +Checks Filesystem selection, endpoint resolution, credentials, and companion access. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs check-file-system + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs check-file-system --file-system-name workspace +tdc fs check-file-system --file-system-name workspace --output text +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md b/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md new file mode 100644 index 0000000000000..3345fbd7ec06f --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md @@ -0,0 +1,39 @@ +--- +title: tdc fs chmod-file +summary: Change file permissions in a TiDB Cloud Filesystem. +--- + +# tdc fs chmod-file + +Changes POSIX mode metadata for a remote path. The command alias is `tdc fs chmod`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs chmod-file + --mode + --path + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs chmod-file --path /reports/final.md --mode 0600 +tdc fs chmod --path /reports/final.md --mode 0644 --dry-run +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md new file mode 100644 index 0000000000000..9f41c6d77c742 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md @@ -0,0 +1,38 @@ +--- +title: tdc fs commit-layer +summary: Commit a TiDB Cloud Filesystem layer. +--- + +# tdc fs commit-layer + +Applies one layer to its base Filesystem. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs commit-layer + --layer-id + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs commit-layer --layer-id "" --dry-run +tdc fs commit-layer --layer-id "" +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md b/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md new file mode 100644 index 0000000000000..cb299db53e136 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md @@ -0,0 +1,51 @@ +--- +title: tdc fs copy-file +summary: Copy files to, from, or within a TiDB Cloud Filesystem. +--- + +# tdc fs copy-file + +Copies files between local paths, remote paths, stdin, and stdout. The command alias is `tdc fs cp`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs copy-file + [--append] + [--create-parents] + [--description ] + [--dry-run] + [--file-system-name ] + [--from-local ] + [--from-remote ] + [--from-stdin] + [--fs-token ] + [--help] + [--layer-id ] + [--overwrite] + [--recursive] + [--resume] + [--tag ] + [--to-local ] + [--to-remote ] + [--to-stdout] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs copy-file --from-local ./report.md --to-remote /reports/report.md +tdc fs copy-file --from-remote /reports/report.md --to-local ./report.copy.md --create-parents +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md b/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md new file mode 100644 index 0000000000000..8258208b1b3a4 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md @@ -0,0 +1,39 @@ +--- +title: tdc fs create-directory +summary: Create a directory in a TiDB Cloud Filesystem. +--- + +# tdc fs create-directory + +Creates a remote directory. The command alias is `tdc fs mkdir`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs create-directory + --path + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--mode ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs create-directory --path /reports/archive --mode 0755 +tdc fs mkdir --path /reports/review --dry-run +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md new file mode 100644 index 0000000000000..a582352c9bd63 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md @@ -0,0 +1,38 @@ +--- +title: tdc fs create-file-system +summary: Create a TiDB Cloud Filesystem. +--- + +# tdc fs create-file-system + +Creates a Filesystem. `--wait` waits until data-plane access is ready. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs create-file-system + --file-system-name + [--dry-run] + [--help] + [--set-default] + [--version] + [--wait] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs create-file-system --file-system-name workspace --set-default --wait +tdc fs create-file-system --file-system-name workspace --dry-run +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md b/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md new file mode 100644 index 0000000000000..afb7c82c1241c --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md @@ -0,0 +1,39 @@ +--- +title: tdc fs create-hardlink +summary: Create a hard link in a TiDB Cloud Filesystem. +--- + +# tdc fs create-hardlink + +Creates a hard link to an existing remote path. The command alias is `tdc fs hardlink`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs create-hardlink + --link-path + --source-path + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs create-hardlink --source-path /reports/final.md --link-path /reports/final-copy.md +tdc fs hardlink --source-path /reports/final.md --link-path /reports/backup.md --dry-run +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md b/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md new file mode 100644 index 0000000000000..cc4eefe0e19e8 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md @@ -0,0 +1,40 @@ +--- +title: tdc fs create-layer-checkpoint +summary: Create a checkpoint in a TiDB Cloud Filesystem layer. +--- + +# tdc fs create-layer-checkpoint + +Creates a checkpoint in one layer. If `--checkpoint-id` is omitted, the service generates one. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs create-layer-checkpoint + --layer-id + [--checkpoint-id ] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--label ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs create-layer-checkpoint --layer-id "" --checkpoint-id before-review +tdc fs create-layer-checkpoint --layer-id "" --label "before review" --dry-run +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md new file mode 100644 index 0000000000000..580a11f7230ca --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md @@ -0,0 +1,43 @@ +--- +title: tdc fs create-layer +summary: Create a layer in a TiDB Cloud Filesystem. +--- + +# tdc fs create-layer + +Creates an isolated change layer over a base root. If `--layer-id` is omitted, the service generates one. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs create-layer + --base-root-path + [--actor-id ] + [--dry-run] + [--durability-mode ] + [--file-system-name ] + [--fs-token ] + [--help] + [--layer-id ] + [--layer-name ] + [--tag ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs create-layer --base-root-path /workspace --layer-name agent-task +tdc fs create-layer --base-root-path /workspace --durability-mode restore-safe --tag task=review --dry-run +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md b/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md new file mode 100644 index 0000000000000..609dd684e21f0 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md @@ -0,0 +1,39 @@ +--- +title: tdc fs create-symlink +summary: Create a symbolic link in a TiDB Cloud Filesystem. +--- + +# tdc fs create-symlink + +Creates a symbolic link. The command alias is `tdc fs symlink`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs create-symlink + --link-path + --target + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs create-symlink --target final.md --link-path /reports/latest.md +tdc fs symlink --target archive/report.md --link-path /reports/archive-link --dry-run +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md new file mode 100644 index 0000000000000..758d153d43aaf --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md @@ -0,0 +1,37 @@ +--- +title: tdc fs delete-file-system +summary: Delete a TiDB Cloud Filesystem. +--- + +# tdc fs delete-file-system + +Requests asynchronous Filesystem deletion and removes its local registration. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs delete-file-system + --file-system-name + [--dry-run] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs delete-file-system --file-system-name workspace --dry-run +tdc fs delete-file-system --file-system-name workspace +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md b/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md new file mode 100644 index 0000000000000..113e262ac950b --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md @@ -0,0 +1,39 @@ +--- +title: tdc fs delete-file +summary: Delete a file from a TiDB Cloud Filesystem. +--- + +# tdc fs delete-file + +Deletes a remote file or directory. The command alias is `tdc fs rm`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs delete-file + --path + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--recursive] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs delete-file --path /reports/obsolete.md +tdc fs delete-file --path /scratch --recursive --dry-run +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md new file mode 100644 index 0000000000000..080cbf4f7b9e8 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md @@ -0,0 +1,35 @@ +--- +title: tdc fs describe-file-system +summary: Describe a locally registered TiDB Cloud Filesystem. +--- + +# tdc fs describe-file-system + +Describes one locally registered Filesystem. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs describe-file-system + --file-system-name + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs describe-file-system --file-system-name workspace +tdc fs describe-file-system --file-system-name workspace --output text +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md new file mode 100644 index 0000000000000..06e871ca8bfaf --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md @@ -0,0 +1,37 @@ +--- +title: tdc fs describe-file +summary: Describe a file in a TiDB Cloud Filesystem. +--- + +# tdc fs describe-file + +Describes metadata for one remote path. The command alias is `tdc fs stat`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs describe-file + --path + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs describe-file --path /reports/report.md +tdc fs stat --path /reports/report.md --output text +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md new file mode 100644 index 0000000000000..eade16d846b94 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md @@ -0,0 +1,37 @@ +--- +title: tdc fs describe-layer +summary: Describe a layer in a TiDB Cloud Filesystem. +--- + +# tdc fs describe-layer + +Describes one Filesystem layer. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs describe-layer + --layer-id + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs describe-layer --layer-id "" +tdc fs describe-layer --layer-id "" --output text +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md new file mode 100644 index 0000000000000..033da4606080e --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md @@ -0,0 +1,38 @@ +--- +title: tdc fs diff-layer +summary: Show changes in a TiDB Cloud Filesystem layer. +--- + +# tdc fs diff-layer + +Lists changes in one layer, optionally up to a sequence number. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs diff-layer + --layer-id + [--file-system-name ] + [--fs-token ] + [--help] + [--max-seq ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs diff-layer --layer-id "" +tdc fs diff-layer --layer-id "" --max-seq 100 +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md new file mode 100644 index 0000000000000..d166ff6512034 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md @@ -0,0 +1,37 @@ +--- +title: tdc fs drain-file-system +summary: Drain a mounted TiDB Cloud Filesystem. +--- + +# tdc fs drain-file-system + +Flushes dirty FUSE state while leaving the mount online. The command alias is `tdc fs drain`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs drain-file-system + --mount-path + [--dry-run] + [--help] + [--timeout ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs drain-file-system --mount-path /path/to/workspace +tdc fs drain --mount-path /path/to/workspace --timeout 30s +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-find-files.md b/ai/tdc/reference/commands/fs/tdc-fs-find-files.md new file mode 100644 index 0000000000000..54a638cab2cdf --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-find-files.md @@ -0,0 +1,46 @@ +--- +title: tdc fs find-files +summary: Find files in a TiDB Cloud Filesystem. +--- + +# tdc fs find-files + +Finds remote paths by name, type, tag, size, or modification time. The command alias is `tdc fs find`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs find-files + [--file-name-pattern ] + [--file-system-name ] + [--fs-token ] + [--help] + [--layer-id ] + [--limit ] + [--max-size-bytes ] + [--min-size-bytes ] + [--newer ] + [--older ] + [--path ] + [--resource-type ] + [--tag ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs find-files --path /workspace --file-name-pattern "*.md" +tdc fs find --path /workspace --tag stage=review --min-size-bytes 1024 +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md b/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md new file mode 100644 index 0000000000000..15036a1dcbae3 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md @@ -0,0 +1,34 @@ +--- +title: tdc fs list-file-systems +summary: List locally registered TiDB Cloud Filesystems. +--- + +# tdc fs list-file-systems + +Lists Filesystems registered in the selected local profile. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs list-file-systems + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs list-file-systems --output text +tdc fs list-file-systems --query 'file_systems[].file_system_name' +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-files.md b/ai/tdc/reference/commands/fs/tdc-fs-list-files.md new file mode 100644 index 0000000000000..37c8f1b293b56 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-files.md @@ -0,0 +1,37 @@ +--- +title: tdc fs list-files +summary: List files in a TiDB Cloud Filesystem. +--- + +# tdc fs list-files + +Lists entries below a remote path. The command alias is `tdc fs ls`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs list-files + [--file-system-name ] + [--fs-token ] + [--help] + [--path ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs list-files --path /reports +tdc fs list-files --path /reports --output text +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md b/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md new file mode 100644 index 0000000000000..0061e0474f5d4 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md @@ -0,0 +1,36 @@ +--- +title: tdc fs list-layers +summary: List layers in a TiDB Cloud Filesystem. +--- + +# tdc fs list-layers + +Lists layers for the selected Filesystem. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs list-layers + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs list-layers +tdc fs list-layers --output text +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md new file mode 100644 index 0000000000000..f30cfb2954734 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md @@ -0,0 +1,53 @@ +--- +title: tdc fs mount-file-system +summary: Mount a TiDB Cloud Filesystem. +--- + +# tdc fs mount-file-system + +Mounts a Filesystem through automatic, FUSE, or WebDAV mode. The command alias is `tdc fs mount`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs mount-file-system + --mount-path + [--cache-dir ] + [--driver ] + [--dry-run] + [--file-system-name ] + [--foreground] + [--fs-token ] + [--help] + [--local-root ] + [--mount-profile ] + [--no-auto-unpack] + [--pack-path ] + [--read-cache-max-file-mb ] + [--read-cache-size-mb ] + [--read-cache-ttl ] + [--read-only] + [--ready-timeout ] + [--remote-path ] + [--unpack-archive-path ] + [--version] + [--write-back-cache] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace +tdc fs mount --mount-path /path/to/workspace --driver fuse --read-only +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-move-file.md b/ai/tdc/reference/commands/fs/tdc-fs-move-file.md new file mode 100644 index 0000000000000..c3b4a2a87db37 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-move-file.md @@ -0,0 +1,40 @@ +--- +title: tdc fs move-file +summary: Move a file in a TiDB Cloud Filesystem. +--- + +# tdc fs move-file + +Moves or renames a remote path. The command alias is `tdc fs mv`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs move-file + --from-remote + --to-remote + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--overwrite] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs move-file --from-remote /draft.md --to-remote /reports/final.md +tdc fs mv --from-remote /draft.md --to-remote /reports/final.md --dry-run +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md new file mode 100644 index 0000000000000..54eceebd89712 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md @@ -0,0 +1,43 @@ +--- +title: tdc fs pack-file-system +summary: Pack local Filesystem overlay state. +--- + +# tdc fs pack-file-system + +Packs selected local overlay state into a remote archive. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs pack-file-system + [--archive-path ] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--local-root ] + [--mount-path ] + [--mount-profile ] + [--path ] + [--remote-root ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs pack-file-system --mount-path /path/to/workspace +tdc fs pack-file-system --local-root ./overlay --remote-root /workspace --mount-profile portable +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-read-file.md b/ai/tdc/reference/commands/fs/tdc-fs-read-file.md new file mode 100644 index 0000000000000..0f63315ce3d7c --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-read-file.md @@ -0,0 +1,39 @@ +--- +title: tdc fs read-file +summary: Read a file from a TiDB Cloud Filesystem. +--- + +# tdc fs read-file + +Writes a remote file or byte range to stdout. The command alias is `tdc fs cat`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs read-file + --path + [--file-system-name ] + [--fs-token ] + [--help] + [--length ] + [--offset ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs read-file --path /reports/report.md +tdc fs read-file --path /archives/large.bin --offset 1024 --length 4096 +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md new file mode 100644 index 0000000000000..782cdd4de0ddd --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md @@ -0,0 +1,38 @@ +--- +title: tdc fs rollback-layer +summary: Roll back a TiDB Cloud Filesystem layer. +--- + +# tdc fs rollback-layer + +Rolls back changes in one layer without committing them to the base. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs rollback-layer + --layer-id + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs rollback-layer --layer-id "" --dry-run +tdc fs rollback-layer --layer-id "" +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md b/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md new file mode 100644 index 0000000000000..e6c4e0acfb22b --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md @@ -0,0 +1,40 @@ +--- +title: tdc fs search-file-content +summary: Search file content in a TiDB Cloud Filesystem. +--- + +# tdc fs search-file-content + +Searches remote file content, optionally in a layer. The command alias is `tdc fs grep`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs search-file-content + --pattern + [--file-system-name ] + [--fs-token ] + [--help] + [--layer-id ] + [--limit ] + [--path ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs search-file-content --path /workspace --pattern "TODO" --limit 50 +tdc fs grep --path /workspace --pattern "deprecated" --layer-id "" +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-set-default-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-set-default-file-system.md new file mode 100644 index 0000000000000..05ad25528484b --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-set-default-file-system.md @@ -0,0 +1,36 @@ +--- +title: tdc fs set-default-file-system +summary: Set the default Filesystem for a tdc profile. +--- + +# tdc fs set-default-file-system + +Sets the default Filesystem for the selected profile. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs set-default-file-system + --file-system-name + [--dry-run] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs set-default-file-system --file-system-name workspace +tdc fs set-default-file-system --file-system-name workspace --dry-run +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md new file mode 100644 index 0000000000000..fdd0d40feeafe --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md @@ -0,0 +1,41 @@ +--- +title: tdc fs unmount-file-system +summary: Unmount a TiDB Cloud Filesystem. +--- + +# tdc fs unmount-file-system + +Gracefully flushes and unmounts a background mount. The command alias is `tdc fs umount`. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs unmount-file-system + --mount-path + [--dry-run] + [--force] + [--help] + [--ignore-absent] + [--no-auto-pack] + [--pack-archive-path ] + [--timeout ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs unmount-file-system --mount-path /path/to/workspace +tdc fs umount --mount-path /path/to/workspace --ignore-absent +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md new file mode 100644 index 0000000000000..2e93a90ad79c3 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md @@ -0,0 +1,43 @@ +--- +title: tdc fs unpack-file-system +summary: Restore local Filesystem overlay state. +--- + +# tdc fs unpack-file-system + +Restores local overlay state from a remote archive. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs unpack-file-system + [--archive-path ] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--local-root ] + [--mount-path ] + [--mount-profile ] + [--no-replace] + [--remote-root ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs unpack-file-system --mount-path /path/to/workspace +tdc fs unpack-file-system --local-root ./overlay --remote-root /workspace --mount-profile portable --no-replace +``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-unset-default-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-unset-default-file-system.md new file mode 100644 index 0000000000000..67e057a8b8fd9 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-unset-default-file-system.md @@ -0,0 +1,35 @@ +--- +title: tdc fs unset-default-file-system +summary: Clear the default Filesystem for a tdc profile. +--- + +# tdc fs unset-default-file-system + +Clears the profile default without deleting a Filesystem. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc fs unset-default-file-system + [--dry-run] + [--help] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc fs unset-default-file-system +tdc fs unset-default-file-system --dry-run +``` diff --git a/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md b/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md new file mode 100644 index 0000000000000..49d5f124d8c69 --- /dev/null +++ b/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md @@ -0,0 +1,36 @@ +--- +title: tdc organization list-projects +summary: List TiDB Cloud projects accessible to the configured API key. +--- + +# tdc organization list-projects + +Lists projects accessible to the configured TiDB Cloud API key, with optional pagination. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc organization list-projects + [--help] + [--page-size ] + [--page-token ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc organization list-projects --page-size 50 --output text +tdc organization list-projects --query 'projects[?type == `tidbx_virtual`].id' --output text +``` diff --git a/ai/tdc/reference/commands/tdc/tdc-configure.md b/ai/tdc/reference/commands/tdc/tdc-configure.md new file mode 100644 index 0000000000000..d3ab958b5b37f --- /dev/null +++ b/ai/tdc/reference/commands/tdc/tdc-configure.md @@ -0,0 +1,38 @@ +--- +title: tdc configure +summary: Configure a local tdc profile interactively or non-interactively. +--- + +# tdc configure + +Configures a local tdc profile. Without flags, this is the only interactive tdc command. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc configure + [--help] + [--non-interactive] + [--region-code ] + [--tdc-private-key ] + [--tdc-public-key ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc configure +TDC_PRIVATE_KEY="" tdc configure --profile ci --non-interactive --region-code aws-us-east-1 --tdc-public-key "" +``` diff --git a/ai/tdc/reference/commands/tdc/tdc-update.md b/ai/tdc/reference/commands/tdc/tdc-update.md new file mode 100644 index 0000000000000..a305bfdaac4e9 --- /dev/null +++ b/ai/tdc/reference/commands/tdc/tdc-update.md @@ -0,0 +1,38 @@ +--- +title: tdc update +summary: Check for or install a tdc release update. +--- + +# tdc update + +Checks for or installs a tdc release update. This command does not read or modify profiles and credentials. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text + tdc update + [--check] + [--dry-run] + [--fail-if-update-available] + [--help] + [--target-version ] + [--version] + [--debug] + [--output ] + [--profile ] + [--query ] + [--region ] +``` + +For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). + +## Examples + +```shell +tdc update --check +tdc update --target-version v0.1.4 +``` diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md index 2e7c847f4a707..5e2a7dd091b81 100644 --- a/ai/tdc/reference/tdc-cli-reference.md +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -97,7 +97,7 @@ tdc └── unmount-vault ``` -For each command's inputs and examples, see the family references linked in [Command families](#command-families). +Every operation has a dedicated command page with syntax and examples. Expand **Command Reference** in the documentation navigation and select a command under `tdc`, `organization`, `db`, `fs`, `fs-git`, `fs-journal`, or `fs-vault`. Required flags appear before optional flags in generated usage. Optional flags are enclosed in brackets: @@ -214,18 +214,19 @@ Errors are written to stderr and successful command output is written to stdout. `--debug` can show redacted request and resolution context. It must not show API keys, FS tokens, DB passwords, SQL text, file contents, or connection strings. -## Command families +## Feature guides -| Command | Purpose | +The following task-oriented guides explain how commands work together. They are separate from the per-command reference pages. + +| Guide | Purpose | | --- | --- | -| [`tdc configure`](/ai/tdc/reference/tdc-install-configure-update.md) | Configure a local profile | -| [`tdc update`](/ai/tdc/reference/tdc-install-configure-update.md) | Check or apply release updates | -| [`tdc organization`](/ai/tdc/reference/tdc-organization.md) | Inspect projects | -| [`tdc db`](/ai/tdc/reference/tdc-starter-database.md) | Manage Starter clusters, branches, and SQL | -| [`tdc fs`](/ai/tdc/reference/tdc-filesystem.md) | Manage Filesystems, files, layers, packs, and mounts | -| [`tdc fs-git`](/ai/tdc/reference/tdc-filesystem-git.md) | Manage Git workspaces on mounted Filesystems | -| [`tdc fs-journal`](/ai/tdc/reference/tdc-filesystem-journal.md) | Manage verifiable journals | -| [`tdc fs-vault`](/ai/tdc/reference/tdc-filesystem-vault.md) | Manage secrets and delegated access | +| [Install, Configure, and Update](/ai/tdc/reference/tdc-install-configure-update.md) | Install releases, configure profiles, update, and uninstall tdc | +| [Organization and Projects](/ai/tdc/reference/tdc-organization.md) | Inspect projects and understand virtual-project selection | +| [Starter Databases and SQL](/ai/tdc/reference/tdc-starter-database.md) | Manage Starter clusters, branches, and SQL | +| [Filesystem](/ai/tdc/reference/tdc-filesystem.md) | Manage Filesystems, files, layers, packs, and mounts | +| [Filesystem Git Workspaces](/ai/tdc/reference/tdc-filesystem-git.md) | Manage Git workspaces on mounted Filesystems | +| [Filesystem Journals](/ai/tdc/reference/tdc-filesystem-journal.md) | Manage verifiable journals | +| [Filesystem Vault](/ai/tdc/reference/tdc-filesystem-vault.md) | Manage secrets and delegated access | For complete commands and flags, run: From 2db53d03a29fc15a5a555fe6a2ff20fd59e875d2 Mon Sep 17 00:00:00 2001 From: Cheese Date: Wed, 22 Jul 2026 22:43:55 +0800 Subject: [PATCH 13/29] docs: clarify ticloud remains for Essential --- TOC-tidb-cloud-essential.md | 4 ++-- ai/tdc/tdc-overview.md | 8 ++++---- ai/tdc/tdc-quick-start.md | 2 +- tidb-cloud/cli-reference.md | 6 +++--- tidb-cloud/get-started-with-cli.md | 6 +++--- 5 files changed, 13 insertions(+), 13 deletions(-) diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index 130ec98cb10a7..dad61cf3a3d30 100644 --- a/TOC-tidb-cloud-essential.md +++ b/TOC-tidb-cloud-essential.md @@ -12,7 +12,7 @@ - Get Started - [Try Out TiDB Cloud](/tidb-cloud/tidb-cloud-quickstart.md) - [Try Out HTAP](/tidb-cloud/tidb-cloud-htap-quickstart.md) - - [Try Out TiDB Cloud CLI (ticloud, Legacy)](/tidb-cloud/get-started-with-cli.md) + - [Try Out TiDB Cloud CLI (ticloud)](/tidb-cloud/get-started-with-cli.md) - Key Concepts - [Overview](/tidb-cloud/key-concepts.md) - [Architecture](/tidb-cloud/architecture-concepts.md) @@ -457,7 +457,7 @@ - [`schema_unused_indexes`](/sys-schema/sys-schema-unused-indexes.md) - [Metadata Lock](/metadata-lock.md) - [TiDB Accelerated Table Creation](/accelerated-table-creation.md) -- TiDB Cloud CLI (ticloud, Legacy) Reference ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) +- TiDB Cloud CLI (ticloud) Reference ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png) - [Overview](/tidb-cloud/cli-reference.md) - auth - [login](/tidb-cloud/ticloud-auth-login.md) diff --git a/ai/tdc/tdc-overview.md b/ai/tdc/tdc-overview.md index c47d0257c8412..0f05cb99050c8 100644 --- a/ai/tdc/tdc-overview.md +++ b/ai/tdc/tdc-overview.md @@ -22,19 +22,19 @@ Use tdc when a workflow needs to manage TiDB Cloud from a terminal, script, CI j - **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 legacy CLI operations that tdc does not yet provide, continue to use `ticloud` during the transition. +For a visual, interactive workflow, use the TiDB Cloud console instead. For TiDB Cloud Essential or CLI operations that tdc does not provide, use `ticloud`. ## tdc, ticloud, and the TiDB Cloud console -TiDB Cloud currently has two command-line interfaces. `tdc` is the new CLI and `ticloud` is the legacy CLI that is being gradually replaced. +TiDB Cloud currently has two command-line interfaces with different product scopes. `tdc` is the new CLI for Starter and TiDB Cloud Filesystem. `ticloud` remains the CLI for Essential and also supports existing Starter workflows. | Interface | Use it for | Interaction model | | --- | --- | --- | | `tdc` (Preview) | New TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows | Predictable commands, JSON output by default, and non-interactive operation except for `tdc configure` | -| `ticloud` (legacy) | TiDB Cloud Essential and operations not yet available in tdc, such as import, export, and audit-log commands | Traditional CLI workflows with interactive and non-interactive modes | +| `ticloud` | TiDB Cloud Essential and operations not available in tdc, such as import, export, and audit-log commands | Traditional CLI workflows with interactive and non-interactive modes | | TiDB Cloud console | Visual resource inspection, guided setup, and manual operations | Browser-based and interactive | -New Starter and Filesystem automation should use tdc. During the transition, keep `ticloud` for Essential and any command that has no tdc equivalent. The legacy `ticloud` CLI will be gradually retired as its supported workflows move to tdc. +New Starter and Filesystem automation should use tdc. Use `ticloud` for Essential and any command that has no tdc equivalent. tdc replaces `ticloud` only for the Starter workflows that tdc supports; it does not replace `ticloud` for Essential. ## What tdc manages diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index c7d246dea7fb1..80a30653ec992 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -13,7 +13,7 @@ This quick start installs tdc, configures one profile, and gets a successful res ## When to use this quick start -Use this quick start when you want to automate a new Starter database or create a persistent workspace for a user, script, or AI agent. It follows the new tdc workflow. If you manage TiDB Cloud Essential or need a legacy operation that tdc does not yet provide, use the [`ticloud` CLI documentation](/tidb-cloud/get-started-with-cli.md) during the transition. +Use this quick start when you want to automate a new Starter database or create a persistent workspace for a user, script, or AI agent. It follows the tdc workflow. If you manage TiDB Cloud Essential or need an operation that tdc does not provide, use the [`ticloud` CLI documentation](/tidb-cloud/get-started-with-cli.md). ## Prerequisites diff --git a/tidb-cloud/cli-reference.md b/tidb-cloud/cli-reference.md index a250ad713c13a..f7f63a4262b6e 100644 --- a/tidb-cloud/cli-reference.md +++ b/tidb-cloud/cli-reference.md @@ -1,6 +1,6 @@ --- title: TiDB Cloud CLI (ticloud) Reference (PREVIEW) -summary: Provides an overview of the legacy ticloud CLI for TiDB Cloud Starter and Essential. +summary: Provides an overview of the ticloud CLI for TiDB Cloud Starter and Essential. --- # TiDB Cloud CLI (ticloud) Reference (PREVIEW) @@ -11,9 +11,9 @@ summary: Provides an overview of the legacy ticloud CLI for TiDB Cloud Starter a > **Note:** > -> `ticloud` is the legacy TiDB Cloud CLI and is being gradually replaced by the new [`tdc` CLI](/ai/tdc/tdc-overview.md). For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use tdc. During the transition, continue to use `ticloud` for TiDB Cloud Essential and operations that tdc does not yet provide, such as import, export, and audit-log commands. +> `ticloud` is the TiDB Cloud CLI for Essential. tdc does not replace `ticloud` for Essential. For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use the [`tdc` CLI](/ai/tdc/tdc-overview.md). Continue to use `ticloud` for Essential and for operations that tdc does not provide, such as import, export, and audit-log commands. -The legacy `ticloud` CLI is a command-line interface that lets you operate TiDB Cloud from your terminal. It manages {{{ .starter }}} and Essential instances, imports and exports data, and supports other legacy CLI workflows. +The `ticloud` CLI is a command-line interface that lets you operate TiDB Cloud from your terminal. It manages {{{ .starter }}} and Essential instances, imports and exports data, and supports other CLI workflows. ## Before you begin diff --git a/tidb-cloud/get-started-with-cli.md b/tidb-cloud/get-started-with-cli.md index c111180e8ae31..affe2208a89a8 100644 --- a/tidb-cloud/get-started-with-cli.md +++ b/tidb-cloud/get-started-with-cli.md @@ -1,15 +1,15 @@ --- title: TiDB Cloud CLI (ticloud) Quick Start -summary: Learn how to manage {{{ .starter }}} and Essential instances through the legacy ticloud CLI. +summary: Learn how to manage {{{ .starter }}} and Essential instances through the ticloud CLI. --- # TiDB Cloud CLI (ticloud) Quick Start > **Note:** > -> `ticloud` is the legacy TiDB Cloud CLI and is being gradually replaced by the new [`tdc` CLI](/ai/tdc/tdc-overview.md). For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use tdc. During the transition, continue to use `ticloud` for TiDB Cloud Essential and operations that tdc does not yet provide, such as import, export, and audit-log commands. +> `ticloud` is the TiDB Cloud CLI for Essential. tdc does not replace `ticloud` for Essential. For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use the [`tdc` CLI](/ai/tdc/tdc-overview.md). Continue to use `ticloud` for Essential and for operations that tdc does not provide, such as import, export, and audit-log commands. -TiDB Cloud provides the legacy command-line interface (CLI) [`ticloud`](https://github.com/tidbcloud/tidbcloud-cli) for you to interact with TiDB Cloud Starter and Essential from your terminal with a few lines of commands. For example, you can perform the following operations using `ticloud`: +TiDB Cloud provides the command-line interface (CLI) [`ticloud`](https://github.com/tidbcloud/tidbcloud-cli) for you to interact with TiDB Cloud Starter and Essential from your terminal with a few lines of commands. For example, you can perform the following operations using `ticloud`: - Create, delete, and list your {{{ .starter }}} or Essential instances. - Import data to your {{{ .starter }}} or Essential instances. From 662f5b6f6dc09411db9e1a61ef2000cccbc68919 Mon Sep 17 00:00:00 2001 From: Cheese Date: Mon, 27 Jul 2026 15:27:28 +0800 Subject: [PATCH 14/29] docs: require explicit filesystem selection --- TOC-ai.md | 2 -- .../commands/fs/tdc-fs-create-file-system.md | 3 +- .../fs/tdc-fs-set-default-file-system.md | 36 ------------------- .../fs/tdc-fs-unset-default-file-system.md | 35 ------------------ ai/tdc/reference/tdc-cli-reference.md | 2 -- .../tdc-configuration-and-credentials.md | 9 +++-- .../reference/tdc-daily-workflow-example.md | 11 +++--- ai/tdc/reference/tdc-filesystem.md | 21 ++++------- .../tdc-parallel-agent-dataset-example.md | 3 +- ai/tdc/reference/tdc-troubleshooting.md | 8 ++--- ai/tdc/tdc-quick-start.md | 8 +++-- 11 files changed, 30 insertions(+), 108 deletions(-) delete mode 100644 ai/tdc/reference/commands/fs/tdc-fs-set-default-file-system.md delete mode 100644 ai/tdc/reference/commands/fs/tdc-fs-unset-default-file-system.md diff --git a/TOC-ai.md b/TOC-ai.md index 5d9a208c466ed..b58b1aabc24fd 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -110,8 +110,6 @@ - [create-file-system](/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md) - [list-file-systems](/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md) - [describe-file-system](/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md) - - [set-default-file-system](/ai/tdc/reference/commands/fs/tdc-fs-set-default-file-system.md) - - [unset-default-file-system](/ai/tdc/reference/commands/fs/tdc-fs-unset-default-file-system.md) - [check-file-system](/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md) - [delete-file-system](/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md) - [copy-file](/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md index a582352c9bd63..3ff33fc90bc6e 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md @@ -18,7 +18,6 @@ Creates a Filesystem. `--wait` waits until data-plane access is ready. --file-system-name [--dry-run] [--help] - [--set-default] [--version] [--wait] [--debug] @@ -33,6 +32,6 @@ Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAM ## Examples ```shell -tdc fs create-file-system --file-system-name workspace --set-default --wait +tdc fs create-file-system --file-system-name workspace --wait tdc fs create-file-system --file-system-name workspace --dry-run ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-set-default-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-set-default-file-system.md deleted file mode 100644 index 05ad25528484b..0000000000000 --- a/ai/tdc/reference/commands/fs/tdc-fs-set-default-file-system.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: tdc fs set-default-file-system -summary: Set the default Filesystem for a tdc profile. ---- - -# tdc fs set-default-file-system - -Sets the default Filesystem for the selected profile. - -> **Note:** -> -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. - -## Syntax - -```text - tdc fs set-default-file-system - --file-system-name - [--dry-run] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] -``` - -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). - -## Examples - -```shell -tdc fs set-default-file-system --file-system-name workspace -tdc fs set-default-file-system --file-system-name workspace --dry-run -``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-unset-default-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-unset-default-file-system.md deleted file mode 100644 index 67e057a8b8fd9..0000000000000 --- a/ai/tdc/reference/commands/fs/tdc-fs-unset-default-file-system.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: tdc fs unset-default-file-system -summary: Clear the default Filesystem for a tdc profile. ---- - -# tdc fs unset-default-file-system - -Clears the profile default without deleting a Filesystem. - -> **Note:** -> -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. - -## Syntax - -```text - tdc fs unset-default-file-system - [--dry-run] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] -``` - -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). - -## Examples - -```shell -tdc fs unset-default-file-system -tdc fs unset-default-file-system --dry-run -``` diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md index 5e2a7dd091b81..71dca0df40f45 100644 --- a/ai/tdc/reference/tdc-cli-reference.md +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -44,8 +44,6 @@ tdc │ ├── create-file-system │ ├── list-file-systems │ ├── describe-file-system -│ ├── set-default-file-system -│ ├── unset-default-file-system │ ├── check-file-system │ ├── delete-file-system │ ├── copy-file diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md index 71d4ebc520c52..17099f2f0dda0 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -18,7 +18,6 @@ tdc stores all product-owned local state under `~/.tdc/` and separates non-sensi [default] region_code = "aws-us-east-1" project_id = "..." -fs_default_file_system_name = "workspace" [logging] enabled = true @@ -74,7 +73,7 @@ Other DB commands identify resources by cluster or branch ID and do not use `pro ## Filesystem resource registry -One profile can register multiple Filesystems. The main config stores only the optional default name. Resource state is isolated: +One profile can register multiple Filesystems. Resource state is isolated from the main profile configuration: ```text ~/.tdc/fs_resources///config @@ -87,9 +86,9 @@ Resource selection is: 1. explicit `--file-system-name`; 2. `TDC_FS_FILE_SYSTEM_NAME`; -3. profile `fs_default_file_system_name`; -4. the only registered resource; -5. fail as missing or ambiguous. +3. fail with `fs.missing_file_system_name`. + +tdc never infers a Filesystem from a saved default or from the number of registered resources. Use `--file-system-name` for one command or `TDC_FS_FILE_SYSTEM_NAME` for a shell, sandbox, or automation environment. FS owner credential selection for remote `fs`, `fs-git`, `fs-journal`, and owner `fs-vault` operations is: diff --git a/ai/tdc/reference/tdc-daily-workflow-example.md b/ai/tdc/reference/tdc-daily-workflow-example.md index be9e51d41c2bc..397b7607a6cf8 100644 --- a/ai/tdc/reference/tdc-daily-workflow-example.md +++ b/ai/tdc/reference/tdc-daily-workflow-example.md @@ -59,17 +59,20 @@ tdc db execute-sql-statement \ ```bash tdc fs create-file-system \ - --file-system-name daily-workspace \ - --set-default + --file-system-name daily-workspace printf 'daily workflow\n' | tdc fs copy-file \ + --file-system-name daily-workspace \ --from-stdin \ --to-remote /notes/today.txt -tdc fs list-files --path /notes --output text +tdc fs list-files \ + --file-system-name daily-workspace \ + --path /notes \ + --output text ``` -The file in `/notes/today.txt` verifies that the selected default resource is usable. +The file in `/notes/today.txt` verifies that the explicitly selected resource is usable. ## Step 5. Check for updates diff --git a/ai/tdc/reference/tdc-filesystem.md b/ai/tdc/reference/tdc-filesystem.md index 811993a7cdcd6..a65e743cfd02f 100644 --- a/ai/tdc/reference/tdc-filesystem.md +++ b/ai/tdc/reference/tdc-filesystem.md @@ -18,8 +18,6 @@ tdc fs ├── create-file-system ├── list-file-systems ├── describe-file-system -├── set-default-file-system -├── unset-default-file-system ├── check-file-system ├── delete-file-system ├── copy-file @@ -54,11 +52,9 @@ tdc fs | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `create-file-system` | Provisions a Filesystem. Requires `--file-system-name`; `--set-default` selects it and `--wait` waits until data-plane access is ready. | `tdc fs create-file-system --file-system-name workspace --set-default --wait` | +| `create-file-system` | Provisions a Filesystem. Requires `--file-system-name`; `--wait` waits until data-plane access is ready. | `tdc fs create-file-system --file-system-name workspace --wait` | | `list-file-systems` | Lists resources registered in the selected local profile. | `tdc fs list-file-systems --output text` | | `describe-file-system` | Reads one locally registered resource by name. | `tdc fs describe-file-system --file-system-name workspace` | -| `set-default-file-system` | Sets the default resource used when no name is supplied. | `tdc fs set-default-file-system --file-system-name workspace` | -| `unset-default-file-system` | Clears the profile's default resource without deleting it. | `tdc fs unset-default-file-system` | | `check-file-system` | Verifies resource selection, endpoint resolution, credentials, and companion access. | `tdc fs check-file-system --file-system-name workspace` | | `delete-file-system` | Requests asynchronous deletion and removes its local registration. Requires TiDB Cloud credentials and the owner resource credential. | `tdc fs delete-file-system --file-system-name workspace` | @@ -97,7 +93,7 @@ tdc fs | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `mount-file-system` | Mounts a resource through automatic, FUSE, or WebDAV mode. Requires `--mount-path`; resource selection can come from a flag, environment, or profile. | `tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace` | +| `mount-file-system` | Mounts a resource through automatic, FUSE, or WebDAV mode. Requires `--mount-path`; select the resource with a flag or environment variable. | `tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace` | | `drain-file-system` | Flushes pending FUSE work while leaving the mount online. | `tdc fs drain-file-system --mount-path /path/to/workspace --timeout 30s` | | `unmount-file-system` | Gracefully flushes and unmounts a background FUSE or WebDAV mount. | `tdc fs unmount-file-system --mount-path /path/to/workspace` | @@ -111,12 +107,11 @@ Data-plane commands can instead use an existing Filesystem with `TDC_FS_TOKEN`, ## Manage Filesystem resources -Create a resource and make it the profile default: +Create a resource and wait until data-plane access is ready: ```bash tdc fs create-file-system \ --file-system-name workspace \ - --set-default \ --wait ``` @@ -139,11 +134,10 @@ tdc fs list-file-systems tdc fs describe-file-system --file-system-name workspace ``` -Set or clear a profile default: +Select a resource for subsequent commands in the current shell: ```bash -tdc fs set-default-file-system --file-system-name workspace -tdc fs unset-default-file-system +export TDC_FS_FILE_SYSTEM_NAME="workspace" ``` Check the selected resource and companion: @@ -167,10 +161,9 @@ One profile can own multiple resources. Selection precedence is: 1. `--file-system-name`; 2. `TDC_FS_FILE_SYSTEM_NAME`; -3. the profile default; -4. the only registered resource. +3. fail with `fs.missing_file_system_name`. -When selection is ambiguous, tdc fails. It never chooses an arbitrary Filesystem. +tdc does not infer a resource from the profile registry, even when only one resource is registered. This makes scripts deterministic when resources are added or removed. ## Copy and read data diff --git a/ai/tdc/reference/tdc-parallel-agent-dataset-example.md b/ai/tdc/reference/tdc-parallel-agent-dataset-example.md index b8cfeaa158cbd..1a8a483256f44 100644 --- a/ai/tdc/reference/tdc-parallel-agent-dataset-example.md +++ b/ai/tdc/reference/tdc-parallel-agent-dataset-example.md @@ -26,15 +26,16 @@ On a trusted machine: ```bash tdc fs create-file-system \ --file-system-name shared-corpus \ - --set-default \ --wait tdc fs copy-file \ + --file-system-name shared-corpus \ --from-local ./corpus \ --to-remote /datasets/corpus \ --recursive tdc fs find-files \ + --file-system-name shared-corpus \ --path /datasets/corpus \ --file-name-pattern "*.pdf" \ --output text diff --git a/ai/tdc/reference/tdc-troubleshooting.md b/ai/tdc/reference/tdc-troubleshooting.md index 346b697d03708..4963179ba8317 100644 --- a/ai/tdc/reference/tdc-troubleshooting.md +++ b/ai/tdc/reference/tdc-troubleshooting.md @@ -55,7 +55,7 @@ tdc fs check-file-system The FS token is not the TiDB Cloud API private key. -## Filesystem selection is ambiguous +## Filesystem selection is missing List registered resources and select one explicitly: @@ -64,13 +64,13 @@ tdc fs list-file-systems --output text tdc fs list-files --file-system-name workspace --path / ``` -Or set a default: +Or select the Filesystem for subsequent commands in the current shell: ```bash -tdc fs set-default-file-system --file-system-name workspace +export TDC_FS_FILE_SYSTEM_NAME="workspace" ``` -tdc intentionally does not guess among multiple resources. +tdc intentionally does not infer a Filesystem from the local registry, including when only one resource is registered. ## Filesystem region is unsupported diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index 80a30653ec992..515d12baf6510 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -75,12 +75,11 @@ Complete either the Filesystem workflow or the Starter database workflow. ### Option A: Write and read a file -Create a Filesystem and make it the default: +Create a Filesystem and wait until it is ready: ```bash tdc fs create-file-system \ --file-system-name quickstart-fs \ - --set-default \ --wait \ --output text ``` @@ -89,10 +88,13 @@ tdc stores the Filesystem credential locally. Write and read a file directly: ```bash printf 'hello from tdc\n' | tdc fs copy-file \ + --file-system-name quickstart-fs \ --from-stdin \ --to-remote /hello.txt -tdc fs read-file --path /hello.txt +tdc fs read-file \ + --file-system-name quickstart-fs \ + --path /hello.txt ``` Expected output: From 3a3733005e457ac4ab395013f8eb06ea6e93982e Mon Sep 17 00:00:00 2001 From: Cheese Date: Mon, 27 Jul 2026 15:50:55 +0800 Subject: [PATCH 15/29] docs: fix tdc navigation validation --- TOC-ai.md | 8 ++++++++ ai/tdc/reference/tdc-agent-sandbox-example.md | 4 ++-- ai/tdc/reference/tdc-configuration-and-credentials.md | 2 +- ai/tdc/reference/tdc-filesystem.md | 2 +- ai/tdc/reference/tdc-git-workspace-for-agents-example.md | 4 ++-- ai/tdc/reference/tdc-journal-agent-workflow-example.md | 2 +- ai/tdc/reference/tdc-query-sql-with-roles-example.md | 2 +- .../tdc-share-filesystem-across-machines-example.md | 2 +- ai/tdc/reference/tdc-vault-agent-secrets-example.md | 4 ++-- 9 files changed, 19 insertions(+), 11 deletions(-) diff --git a/TOC-ai.md b/TOC-ai.md index 89a194bc1e0b7..f720cb8ffe740 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -86,6 +86,14 @@ - [Vector Search Limitations](/ai/reference/vector-search-limitations.md) - TiDB Cloud CLI (tdc) - [Overview](/ai/tdc/tdc-overview.md) + - Guides + - [Install, Configure, and Update](/ai/tdc/reference/tdc-install-configure-update.md) + - [Organization and Projects](/ai/tdc/reference/tdc-organization.md) + - [Starter Databases and SQL](/ai/tdc/reference/tdc-starter-database.md) + - [Filesystem](/ai/tdc/reference/tdc-filesystem.md) + - [Filesystem Git Workspaces](/ai/tdc/reference/tdc-filesystem-git.md) + - [Filesystem Journals](/ai/tdc/reference/tdc-filesystem-journal.md) + - [Filesystem Vault](/ai/tdc/reference/tdc-filesystem-vault.md) - Command Reference - [CLI Syntax and Global Behavior](/ai/tdc/reference/tdc-cli-reference.md) - [configure](/ai/tdc/reference/commands/tdc/tdc-configure.md) diff --git a/ai/tdc/reference/tdc-agent-sandbox-example.md b/ai/tdc/reference/tdc-agent-sandbox-example.md index fb2a9a64e1515..4c316c211b471 100644 --- a/ai/tdc/reference/tdc-agent-sandbox-example.md +++ b/ai/tdc/reference/tdc-agent-sandbox-example.md @@ -15,9 +15,9 @@ This example gives an ephemeral coding agent a durable workspace without copying Coding agents often start in clean, short-lived sandboxes. The local disk disappears when the sandbox is replaced, but the agent still needs previous artifacts, repository state, and files produced by other workers. Rebuilding that state wastes task time, while copying `~/.tdc/` or injecting TiDB Cloud API keys gives the sandbox control-plane credentials it does not need. -## Why local storage and full cloud credentials are not enough +## Limitations of local storage and full cloud credentials -A sandbox-local directory is fast but not durable or shared. Generic object-storage APIs require application-specific download and upload logic instead of ordinary file operations. Giving every sandbox the user's complete cloud credentials solves access at the cost of a much broader security boundary. +A sandbox-local directory is fast but not durable or shared. Generic object-storage APIs require application-specific download and upload logic instead of ordinary file operations. Giving every sandbox the user's complete cloud credentials solves access at the cost of a broader security boundary. ## How tdc changes the workflow diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md index 17099f2f0dda0..4bda5c77fe2e7 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -150,7 +150,7 @@ A successful background FS or vault mount writes a non-secret locator: ~/.tdc/mounts/.locator.json ``` -The locator records enough placement and companion-home information for drain and unmount from the same `HOME`. It does not contain the FS token. Successful unmount removes it. +The locator records the placement and companion-home information required for drain and unmount from the same `HOME`. It does not contain the FS token. Successful unmount removes it. ## Operation logs diff --git a/ai/tdc/reference/tdc-filesystem.md b/ai/tdc/reference/tdc-filesystem.md index a65e743cfd02f..0ceb839d62528 100644 --- a/ai/tdc/reference/tdc-filesystem.md +++ b/ai/tdc/reference/tdc-filesystem.md @@ -305,7 +305,7 @@ The default `--driver auto` is platform-specific. `--remote-path` exposes a subt ### Mount in Docker and Docker Compose -Installing FUSE3 inside an image is not sufficient by itself. The Docker host must provide `/dev/fuse`, and the container must receive permission to perform the mount. The following Dockerfile installs the required Ubuntu package and tdc without storing any cloud or Filesystem credentials in the image: +Installing FUSE3 inside an image does not enable mounts by itself. The Docker host must provide `/dev/fuse`, and the container must receive permission to perform the mount. The following Dockerfile installs the required Ubuntu package and tdc without storing any cloud or Filesystem credentials in the image: ```dockerfile FROM ubuntu:24.04 diff --git a/ai/tdc/reference/tdc-git-workspace-for-agents-example.md b/ai/tdc/reference/tdc-git-workspace-for-agents-example.md index 8a9be1ac7c684..e6e9b67099152 100644 --- a/ai/tdc/reference/tdc-git-workspace-for-agents-example.md +++ b/ai/tdc/reference/tdc-git-workspace-for-agents-example.md @@ -15,9 +15,9 @@ This example removes a large repository clone from the critical path of starting An ephemeral agent normally waits for `git clone` and checkout to download a repository before it can inspect the tree or begin work. For a large monorepo, that startup delay is paid again for every replacement sandbox. The agent appears idle even when its first task needs only a small part of the repository. -## Why a normal clone or partial clone is not enough +## Limitations of a normal clone or partial clone -A normal clone blocks until the initial object transfer and checkout finish. A native blobless partial clone reduces the first transfer, but later Git commands and file reads can still trigger many on-demand fetches on the agent's critical path. Neither approach by itself provides a shared Filesystem workspace that can be restored across agent runtimes. +A normal clone blocks until the initial object transfer and checkout finish. A native blobless partial clone reduces the first transfer, but later Git commands and file reads can still trigger repeated on-demand fetches on the agent's critical path. Neither approach by itself provides a shared Filesystem workspace that can be restored across agent runtimes. ## How tdc changes the workflow diff --git a/ai/tdc/reference/tdc-journal-agent-workflow-example.md b/ai/tdc/reference/tdc-journal-agent-workflow-example.md index e5db1e3e377a5..54d8098c5c318 100644 --- a/ai/tdc/reference/tdc-journal-agent-workflow-example.md +++ b/ai/tdc/reference/tdc-journal-agent-workflow-example.md @@ -15,7 +15,7 @@ This example records an agent task as a structured, ordered, and verifiable even An agent task can span planning, tool calls, tests, retries, and handoffs between workers. When the task fails, operators need to know which events happened and in what order. Plain console output is often scattered across processes, while a mutable status file shows only the latest state. -## Why appending to a normal file is not enough +## Limitations of appending to a normal file A text file can be edited or truncated after an event is written, has no intrinsic sequence or hash chain, and requires every producer to invent parsing and concurrency rules. Retrying an append can also create duplicate events unless the application builds its own idempotency layer. diff --git a/ai/tdc/reference/tdc-query-sql-with-roles-example.md b/ai/tdc/reference/tdc-query-sql-with-roles-example.md index 8d574a21d8fe6..d4e8c259395ed 100644 --- a/ai/tdc/reference/tdc-query-sql-with-roles-example.md +++ b/ai/tdc/reference/tdc-query-sql-with-roles-example.md @@ -15,7 +15,7 @@ This example lets an agent perform schema, data, and verification work while mak An agent that can inspect data often also needs to apply a migration or update a row. Giving it one administrator connection for the complete task is convenient, but a mistaken statement during an inspection step then has the authority to change or delete data. Giving it only a read-only connection prevents legitimate write and schema work. -## Why one native database connection is not enough +## Limitations of one native database connection TiDB supports SQL privileges, but a conventional client session uses the privileges of the one credential used to connect. Users must create, store, and switch among credentials themselves, and an agent can silently keep using an overly privileged connection across task phases. diff --git a/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md b/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md index f291f36946632..d16c195413d2e 100644 --- a/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md +++ b/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md @@ -15,7 +15,7 @@ This example gives agents or users on two machines one shared workspace without An agent can prepare source files or artifacts on machine A and continue the task on machine B, but each machine normally sees only its own disk. Copying a snapshot before every handoff adds latency, and changes made after the copy are invisible to the other machine. Concurrent handoffs can also create conflicting copies with no clear source of truth. -## Why native local disks and manual synchronization are not enough +## Limitations of native local disks and manual synchronization Local disks do not provide a shared namespace. Commands such as `scp` and archive upload transfer point-in-time copies rather than live state, while object storage does not by itself behave like the mounted directory expected by editors, build tools, and agents. diff --git a/ai/tdc/reference/tdc-vault-agent-secrets-example.md b/ai/tdc/reference/tdc-vault-agent-secrets-example.md index 543da0688e721..b9bff1b6f0008 100644 --- a/ai/tdc/reference/tdc-vault-agent-secrets-example.md +++ b/ai/tdc/reference/tdc-vault-agent-secrets-example.md @@ -13,9 +13,9 @@ This example gives an agent temporary access to one secret field without sharing ## The agent problem -An agent might need one API endpoint or token to complete a short task. Putting the complete secret in a prompt, `.env` file, or sandbox image exposes it beyond the process and lifetime that need it. Sharing the Filesystem owner token also grants much more access than one secret field requires. +An agent might need one API endpoint or token to complete a short task. Putting the complete secret in a prompt, `.env` file, or sandbox image exposes it beyond the process and lifetime that need it. Sharing the Filesystem owner token also grants broader access than one secret field requires. -## Why ordinary environment variables and files are not enough +## Limitations of ordinary environment variables and files Environment variables and files can deliver a secret, but they do not create a scoped, expiring delegation or an access audit trail. A separate cloud secret manager can provide those controls, but it requires another identity, policy, and integration path for every sandbox. From 73cf02194f0ca5c5fc5ca788c53f582f22f61c85 Mon Sep 17 00:00:00 2001 From: Cheese Date: Mon, 27 Jul 2026 17:24:07 +0800 Subject: [PATCH 16/29] docs: refine tdc command references --- .../db/tdc-db-create-db-cluster-branch.md | 39 ++++++--- .../commands/db/tdc-db-create-db-cluster.md | 45 ++++++---- .../commands/db/tdc-db-create-db-sql-users.md | 33 ++++--- .../db/tdc-db-delete-db-cluster-branch.md | 36 +++++--- .../commands/db/tdc-db-delete-db-cluster.md | 36 +++++--- .../db/tdc-db-describe-db-cluster-branch.md | 36 +++++--- .../commands/db/tdc-db-describe-db-cluster.md | 33 ++++--- .../db/tdc-db-execute-sql-statement.md | 48 +++++++---- .../db/tdc-db-format-db-connection-string.md | 54 ++++++++---- .../db/tdc-db-list-db-cluster-branches.md | 36 +++++--- .../commands/db/tdc-db-list-db-clusters.md | 42 +++++---- .../commands/db/tdc-db-update-db-cluster.md | 39 ++++++--- .../fs-git/tdc-fs-git-add-git-worktree.md | 61 ++++++++----- .../fs-git/tdc-fs-git-clone-git-workspace.md | 52 +++++++---- .../tdc-fs-git-hydrate-git-workspace.md | 43 ++++++---- .../fs-git/tdc-fs-git-remove-git-worktree.md | 46 ++++++---- .../tdc-fs-journal-append-journal-entries.md | 61 ++++++++----- .../tdc-fs-journal-create-journal.md | 55 +++++++----- .../tdc-fs-journal-read-journal-entries.md | 46 ++++++---- .../tdc-fs-journal-search-journal-entries.md | 70 +++++++++------ .../tdc-fs-journal-verify-journal.md | 40 +++++---- .../fs-vault/tdc-fs-vault-create-grant.md | 58 ++++++++----- .../fs-vault/tdc-fs-vault-create-secret.md | 46 ++++++---- .../fs-vault/tdc-fs-vault-delete-grant.md | 49 +++++++---- .../fs-vault/tdc-fs-vault-delete-secret.md | 43 ++++++---- .../tdc-fs-vault-list-audit-events.md | 49 +++++++---- .../fs-vault/tdc-fs-vault-list-secrets.md | 40 +++++---- .../fs-vault/tdc-fs-vault-mount-vault.md | 52 +++++++---- .../fs-vault/tdc-fs-vault-read-secret.md | 49 +++++++---- .../fs-vault/tdc-fs-vault-replace-secret.md | 46 ++++++---- .../fs-vault/tdc-fs-vault-run-with-secret.md | 43 ++++++---- .../fs-vault/tdc-fs-vault-unmount-vault.md | 42 +++++---- .../commands/fs/tdc-fs-check-file-system.md | 33 ++++--- .../commands/fs/tdc-fs-chmod-file.md | 46 ++++++---- .../commands/fs/tdc-fs-commit-layer.md | 43 ++++++---- .../reference/commands/fs/tdc-fs-copy-file.md | 82 +++++++++++------- .../commands/fs/tdc-fs-create-directory.md | 46 ++++++---- .../commands/fs/tdc-fs-create-file-system.md | 36 +++++--- .../commands/fs/tdc-fs-create-hardlink.md | 46 ++++++---- .../fs/tdc-fs-create-layer-checkpoint.md | 49 +++++++---- .../commands/fs/tdc-fs-create-layer.md | 58 ++++++++----- .../commands/fs/tdc-fs-create-symlink.md | 46 ++++++---- .../commands/fs/tdc-fs-delete-file-system.md | 36 +++++--- .../commands/fs/tdc-fs-delete-file.md | 46 ++++++---- .../fs/tdc-fs-describe-file-system.md | 30 ++++--- .../commands/fs/tdc-fs-describe-file.md | 40 +++++---- .../commands/fs/tdc-fs-describe-layer.md | 40 +++++---- .../commands/fs/tdc-fs-diff-layer.md | 43 ++++++---- .../commands/fs/tdc-fs-drain-file-system.md | 36 +++++--- .../commands/fs/tdc-fs-find-files.md | 67 +++++++++------ .../commands/fs/tdc-fs-list-file-systems.md | 27 +++--- .../commands/fs/tdc-fs-list-files.md | 40 +++++---- .../commands/fs/tdc-fs-list-layers.md | 37 +++++--- .../commands/fs/tdc-fs-mount-file-system.md | 86 ++++++++++++------- .../reference/commands/fs/tdc-fs-move-file.md | 49 +++++++---- .../commands/fs/tdc-fs-pack-file-system.md | 58 ++++++++----- .../reference/commands/fs/tdc-fs-read-file.md | 46 ++++++---- .../commands/fs/tdc-fs-rollback-layer.md | 43 ++++++---- .../commands/fs/tdc-fs-search-file-content.md | 49 +++++++---- .../commands/fs/tdc-fs-unmount-file-system.md | 48 +++++++---- .../commands/fs/tdc-fs-unpack-file-system.md | 58 ++++++++----- .../tdc-organization-list-projects.md | 33 ++++--- .../reference/commands/tdc/tdc-configure.md | 44 ++++++---- ai/tdc/reference/commands/tdc/tdc-update.md | 41 +++++---- ai/tdc/reference/tdc-cli-reference.md | 28 +++--- 65 files changed, 1889 insertions(+), 1089 deletions(-) diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md index 4fb1af326db08..64a38dee93129 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md @@ -14,25 +14,36 @@ Creates a branch for one Starter cluster. `--wait` waits for the branch to becom ## Syntax ```text - tdc db create-db-cluster-branch - --db-cluster-branch-name - --db-cluster-id - [--dry-run] - [--help] - [--version] - [--wait] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db create-db-cluster-branch + --db-cluster-branch-name + --db-cluster-id + [--dry-run] + [--help] + [--version] + [--wait] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--db-cluster-branch-name `: Starter DB cluster branch display name. \[required] +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--version`: Display tdc version information. +- `--wait`: Wait until the created branch becomes `ACTIVE` before returning. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Create a branch and wait until it is active + +```bash tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name dev --wait +``` + +### Preview branch creation + +```bash tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name preview --dry-run ``` diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md index 2e790ddfe5798..fd01feaa356a8 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md @@ -14,27 +14,40 @@ Creates a Starter cluster. `--db-cluster-type` defaults to `starter`, and `--wai ## Syntax ```text - tdc db create-db-cluster - --db-cluster-name - [--db-cluster-type ] - [--dry-run] - [--help] - [--monthly-spending-limit-usd-cents ] - [--project-id ] - [--version] - [--wait] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db create-db-cluster + --db-cluster-name + [--db-cluster-type ] + [--dry-run] + [--help] + [--monthly-spending-limit-usd-cents ] + [--project-id ] + [--version] + [--wait] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--db-cluster-name `: Starter DB cluster display name. \[required] +- `--db-cluster-type `: DB cluster type; must be `starter`. \[default: starter] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--monthly-spending-limit-usd-cents `: Monthly spending limit in USD cents; omit to use the API default. +- `--project-id `: TiDB Cloud project ID. +- `--version`: Display tdc version information. +- `--wait`: Wait until the created cluster becomes `ACTIVE` before returning. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Create a cluster and wait until it is active + +```bash tdc db create-db-cluster --db-cluster-name app-db --wait +``` + +### Preview cluster creation + +```bash tdc db create-db-cluster --db-cluster-name app-db --dry-run ``` diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md b/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md index d2d06f8c46064..73f26288dfe7b 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md @@ -14,23 +14,32 @@ Idempotently creates or repairs the read-only, read-write, and admin SQL users m ## Syntax ```text - tdc db create-db-sql-users - --db-cluster-id - [--dry-run] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db create-db-sql-users + --db-cluster-id + [--dry-run] + [--help] + [--version] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Preview SQL user creation + +```bash tdc db create-db-sql-users --db-cluster-id "" --dry-run +``` + +### Create read-only, read-write, and admin SQL users + +```bash tdc db create-db-sql-users --db-cluster-id "" ``` diff --git a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md index e665abe498fde..a1db8a5627dd6 100644 --- a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md +++ b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md @@ -14,24 +14,34 @@ Deletes one branch from a Starter cluster. ## Syntax ```text - tdc db delete-db-cluster-branch - --db-cluster-branch-id - --db-cluster-id - [--dry-run] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db delete-db-cluster-branch + --db-cluster-branch-id + --db-cluster-id + [--dry-run] + [--help] + [--version] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--db-cluster-branch-id `: Starter DB cluster branch ID. \[required] +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Preview branch deletion + +```bash tdc db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" --dry-run +``` + +### Delete a branch + +```bash tdc db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" ``` diff --git a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md index f3c2f5790ea30..d9bff4f86d5af 100644 --- a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md @@ -14,24 +14,34 @@ Deletes one Starter cluster. `--wait` waits until deletion is observable. ## Syntax ```text - tdc db delete-db-cluster - --db-cluster-id - [--dry-run] - [--help] - [--version] - [--wait] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db delete-db-cluster + --db-cluster-id + [--dry-run] + [--help] + [--version] + [--wait] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--version`: Display tdc version information. +- `--wait`: Wait until the deleted cluster reaches `DELETED` or is no longer accessible. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Preview cluster deletion + +```bash tdc db delete-db-cluster --db-cluster-id "" --dry-run +``` + +### Delete a cluster and wait for completion + +```bash tdc db delete-db-cluster --db-cluster-id "" --wait ``` diff --git a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md index 11eb4aaff881f..e8797367afc66 100644 --- a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md +++ b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md @@ -14,24 +14,34 @@ Describes one branch by cluster ID and branch ID. ## Syntax ```text - tdc db describe-db-cluster-branch - --db-cluster-branch-id - --db-cluster-id - [--help] - [--version] - [--view ] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db describe-db-cluster-branch + --db-cluster-branch-id + --db-cluster-id + [--help] + [--version] + [--view ] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--db-cluster-branch-id `: Starter DB cluster branch ID. \[required] +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--help`: Display help information. +- `--version`: Display tdc version information. +- `--view `: Detail level: `BASIC` or `FULL`. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Describe a branch + +```bash tdc db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" +``` + +### Show full branch details + +```bash tdc db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" --view FULL ``` diff --git a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md index 76d51fbaf40b5..75c7a3e8a2628 100644 --- a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md @@ -14,23 +14,32 @@ Describes one Starter cluster. Use `--view FULL` to request expanded fields. ## Syntax ```text - tdc db describe-db-cluster - --db-cluster-id - [--help] - [--version] - [--view ] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db describe-db-cluster + --db-cluster-id + [--help] + [--version] + [--view ] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--help`: Display help information. +- `--version`: Display tdc version information. +- `--view `: Detail level: `BASIC` or `FULL`. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Describe a cluster + +```bash tdc db describe-db-cluster --db-cluster-id "" +``` + +### Show full cluster details + +```bash tdc db describe-db-cluster --db-cluster-id "" --view FULL ``` diff --git a/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md b/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md index 440b32a11eb50..76bcc82620691 100644 --- a/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md +++ b/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md @@ -14,28 +14,42 @@ Executes exactly one SQL statement. Read-write is the default role; explicit rol ## Syntax ```text - tdc db execute-sql-statement - --db-cluster-id - --sql - [--admin] - [--database ] - [--help] - [--read-only] - [--read-write] - [--transport ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db execute-sql-statement + --db-cluster-id + --sql + [--admin] + [--database ] + [--help] + [--read-only] + [--read-write] + [--transport ] + [--version] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--sql `: One SQL statement to execute. \[required] +- `--admin`: Use prepared admin DB SQL credentials. +- `--database `: Database/default schema name. +- `--help`: Display help information. +- `--read-only`: Use prepared `read_only` DB SQL credentials. +- `--read-write`: Use prepared `read_write` DB SQL credentials. +- `--transport `: SQL execution transport: `https` or `mysql`. \[default: https] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Run a read-only query + +```bash tdc db execute-sql-statement --db-cluster-id "" --read-only --sql "SELECT 1" --output text +``` + +### Run an administrative statement + +```bash tdc db execute-sql-statement --db-cluster-id "" --admin --sql "CREATE DATABASE IF NOT EXISTS app" ``` diff --git a/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md b/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md index cc223b6abd8db..da88705ebc356 100644 --- a/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md +++ b/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md @@ -14,30 +14,46 @@ Formats stored SQL credentials for read-write, read-only, or admin access. ## Syntax ```text - tdc db format-db-connection-string - --db-cluster-id - [--admin] - [--database ] - [--env-database-url-name ] - [--env-include-database-url] - [--env-prefix ] - [--format ] - [--help] - [--read-only] - [--read-write] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db format-db-connection-string + --db-cluster-id + [--admin] + [--database ] + [--env-database-url-name ] + [--env-include-database-url] + [--env-prefix ] + [--format ] + [--help] + [--read-only] + [--read-write] + [--version] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--admin`: Use prepared admin DB SQL credentials. +- `--database `: Database/default schema name. +- `--env-database-url-name `: Database URL variable name for `--format env`. \[default: DATABASE_URL] +- `--env-include-database-url`: Include a database URL variable with `--format env`. +- `--env-prefix `: Dotenv variable prefix for `--format env`. \[default: TIDB_] +- `--format `: Connection string format: `mysql-uri`, `jdbc`, `go-sql-driver`, `sqlalchemy`, or `env`. \[default: mysql-uri] +- `--help`: Display help information. +- `--read-only`: Use prepared `read_only` DB SQL credentials. +- `--read-write`: Use prepared `read_write` DB SQL credentials. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Format a read-write MySQL URI + +```bash tdc db format-db-connection-string --db-cluster-id "" --read-write --format mysql-uri +``` + +### Format read-only dotenv variables + +```bash tdc db format-db-connection-string --db-cluster-id "" --read-only --format env --env-prefix TIDB_ ``` diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md b/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md index 03f63fd887339..e841e23a5863b 100644 --- a/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md +++ b/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md @@ -14,24 +14,34 @@ Lists branches for one Starter cluster, with optional pagination. ## Syntax ```text - tdc db list-db-cluster-branches - --db-cluster-id - [--help] - [--page-size ] - [--page-token ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db list-db-cluster-branches + --db-cluster-id + [--help] + [--page-size ] + [--page-token ] + [--version] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--help`: Display help information. +- `--page-size `: Number of branches to request; 0 uses the API default. +- `--page-token `: Page token returned by a previous list-db-cluster-branches call. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### List branches as text + +```bash tdc db list-db-cluster-branches --db-cluster-id "" --output text +``` + +### Return branch IDs + +```bash tdc db list-db-cluster-branches --db-cluster-id "" --query 'branches[].id' ``` diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md index 614988ccf8304..81dd1d745dee1 100644 --- a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md +++ b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md @@ -14,26 +14,38 @@ Lists Starter clusters with optional pagination, filtering, ordering, and JMESPa ## Syntax ```text - tdc db list-db-clusters - [--filter ] - [--help] - [--order-by ] - [--page-size ] - [--page-token ] - [--skip ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db list-db-clusters + [--filter ] + [--help] + [--order-by ] + [--page-size ] + [--page-token ] + [--skip ] + [--version] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--filter `: Starter API filter expression. +- `--help`: Display help information. +- `--order-by `: Starter API orderBy expression. +- `--page-size `: Number of clusters to request; 0 uses the API default. +- `--page-token `: Page token returned by a previous list-db-clusters call. +- `--skip `: Number of clusters to skip. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### List clusters as text + +```bash tdc db list-db-clusters --output text +``` + +### Return selected cluster fields + +```bash tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name,state:state}' ``` diff --git a/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md index 1ef8bf2b21b06..79cef640933db 100644 --- a/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md @@ -14,25 +14,36 @@ Updates the display name or monthly spending limit of one Starter cluster. ## Syntax ```text - tdc db update-db-cluster - --db-cluster-id - [--db-cluster-name ] - [--dry-run] - [--help] - [--monthly-spending-limit-usd-cents ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc db update-db-cluster + --db-cluster-id + [--db-cluster-name ] + [--dry-run] + [--help] + [--monthly-spending-limit-usd-cents ] + [--version] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--db-cluster-name `: New Starter DB cluster display name. +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--monthly-spending-limit-usd-cents `: Monthly spending limit in USD cents; omit to leave unchanged. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Rename a cluster + +```bash tdc db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2 +``` + +### Preview a spending-limit update + +```bash tdc db update-db-cluster --db-cluster-id "" --monthly-spending-limit-usd-cents 1000 --dry-run ``` diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md index df61065804850..02888f2c5f60e 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md @@ -14,31 +14,48 @@ Adds a linked Git worktree from a base workspace. ## Syntax ```text - tdc fs-git add-git-worktree - --base-path - --worktree-path - [--blobless] - [--branch-name ] - [--commit-ish ] - [--detach] - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--hydrate ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-git add-git-worktree + --base-path + --worktree-path + [--blobless] + [--branch-name ] + [--commit-ish ] + [--detach] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--hydrate ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--base-path `: The mounted file system path of the base Git workspace. \[required] +- `--worktree-path `: The mounted file system path for the linked worktree. \[required] +- `--blobless`: Require the base workspace to use blobless Git storage. +- `--branch-name `: Create a branch for the linked worktree. +- `--commit-ish `: Optional commit-ish for the linked worktree. +- `--detach`: Create a detached linked worktree. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--hydrate `: Blobless hydrate mode: `auto`, `background`, `sync`, or `off`. \[default: auto] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-git add-git-worktree --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-feature --branch-name feature-x -tdc fs-git add-git-worktree --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-review --commit-ish origin/main --detach +### Create a worktree on a new branch + +```bash +tdc fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-feature --branch-name feature-x +``` + +### Create a detached worktree + +```bash +tdc fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-review --commit-ish origin/main --detach ``` diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md index 07abc4d976467..06897e9075894 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md @@ -14,28 +14,42 @@ Clones a repository into a mounted Filesystem path. Hydration can run synchronou ## Syntax ```text - tdc fs-git clone-git-workspace - --repo-url - --target-path - [--blobless] - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--hydrate ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-git clone-git-workspace + --repo-url + --target-path + [--blobless] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--hydrate ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--repo-url `: Git repository URL. \[required] +- `--target-path `: The mounted file system path to clone into. \[required] +- `--blobless`: Create a blobless partial local `.git` and hydrate clean blobs separately. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--hydrate `: Blobless hydrate mode: `auto`, `background`, `sync`, or `off`. \[default: auto] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-git clone-git-workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb -tdc fs-git clone-git-workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate background +### Clone a repository + +```bash +tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb +``` + +### Clone a blobless repository and hydrate in the background + +```bash +tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate background ``` diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md index 27d9e30e32bfe..ed9a79ea948d0 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md @@ -14,25 +14,36 @@ Hydrates clean Git objects for an existing tdc Git workspace. ## Syntax ```text - tdc fs-git hydrate-git-workspace - --target-path - [--file-system-name ] - [--fs-token ] - [--help] - [--timeout ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-git hydrate-git-workspace + --target-path + [--file-system-name ] + [--fs-token ] + [--help] + [--timeout ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--target-path `: Mounted tdc fs workspace path. \[required] +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--timeout `: Maximum hydrate duration. \[default: `30m0s`] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-git hydrate-git-workspace --target-path /path/to/workspace/tidb -tdc fs-git hydrate-git-workspace --target-path /path/to/workspace/tidb --timeout 30m +### Hydrate a Git workspace + +```bash +tdc fs-git hydrate-git-workspace --file-system-name workspace --target-path /path/to/workspace/tidb +``` + +### Hydrate with an explicit timeout + +```bash +tdc fs-git hydrate-git-workspace --file-system-name workspace --target-path /path/to/workspace/tidb --timeout 30m ``` diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md index 3fcfd41b16002..deee7092dbef9 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md @@ -14,26 +14,38 @@ Removes a linked worktree without recursively deleting shared clean-tree data. ## Syntax ```text - tdc fs-git remove-git-worktree - --worktree-path - [--dry-run] - [--file-system-name ] - [--force] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-git remove-git-worktree + --worktree-path + [--dry-run] + [--file-system-name ] + [--force] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--worktree-path `: Mounted tdc fs path of the linked worktree. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--force`: Remove even when the linked worktree has local changes. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-git remove-git-worktree --worktree-path /path/to/workspace/tidb-feature --dry-run -tdc fs-git remove-git-worktree --worktree-path /path/to/workspace/tidb-feature --force +### Preview worktree removal + +```bash +tdc fs-git remove-git-worktree --file-system-name workspace --worktree-path /path/to/workspace/tidb-feature --dry-run +``` + +### Force worktree removal + +```bash +tdc fs-git remove-git-worktree --file-system-name workspace --worktree-path /path/to/workspace/tidb-feature --force ``` diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md index 0a98c792c4cac..b0ff45bb0e941 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md @@ -14,31 +14,48 @@ Appends one JSON event or a JSON array to a journal. ## Syntax ```text - tdc fs-journal append-journal-entries - --journal-id - [--dry-run] - [--entry-json ] - [--entry-type ] - [--file-system-name ] - [--fs-token ] - [--help] - [--idempotency-key ] - [--json-array] - [--source ] - [--subject ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-journal append-journal-entries + --journal-id + [--dry-run] + [--entry-json ] + [--entry-type ] + [--file-system-name ] + [--fs-token ] + [--help] + [--idempotency-key ] + [--json-array] + [--source ] + [--subject ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--journal-id `: Journal ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--entry-json `: One JSON journal entry object; repeatable. +- `--entry-type `: Default entry type for entries missing type. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--idempotency-key `: Append idempotency key; generated when omitted. +- `--json-array`: Read a JSON array from stdin instead of JSONL. +- `--source `: Entry source. +- `--subject `: Entry subject; repeatable. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-journal append-journal-entries --journal-id jrn-demo --entry-json '{"type":"task.started"}' -tdc fs-journal append-journal-entries --journal-id jrn-demo --entry-type task.completed --subject issue-42 --idempotency-key issue-42-complete +### Append a JSON journal entry + +```bash +tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-json '{"type":"task.started"}' +``` + +### Append a typed idempotent entry + +```bash +tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-type task.completed --subject issue-42 --idempotency-key issue-42-complete ``` diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md index 735e214c6e63f..534587ae68083 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md @@ -14,29 +14,44 @@ Creates a journal. If `--journal-id` is omitted, the service generates one. ## Syntax ```text - tdc fs-journal create-journal - [--actor ] - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--journal-id ] - [--journal-kind ] - [--label ] - [--title ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-journal create-journal + [--actor ] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--journal-id ] + [--journal-kind ] + [--label ] + [--title ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--actor `: Actor in the form `type:id`. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--journal-id `: Journal ID; generated when omitted. +- `--journal-kind `: Journal kind. \[default: agent] +- `--label `: Journal label `key=value`; repeatable. +- `--title `: Journal title. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-journal create-journal --journal-id jrn-demo --journal-kind agent --title "demo task" -tdc fs-journal create-journal --journal-kind deployment --actor agent:tdc --label env=dev --dry-run +### Create an agent journal + +```bash +tdc fs-journal create-journal --file-system-name workspace --journal-id jrn-demo --journal-kind agent --title "demo task" +``` + +### Preview creation of a labeled deployment journal + +```bash +tdc fs-journal create-journal --file-system-name workspace --journal-kind deployment --actor agent:tdc --label env=dev --dry-run ``` diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md index 03b8a171f1822..0892d40712fb3 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md @@ -14,26 +14,38 @@ Reads entries from one journal in sequence order. ## Syntax ```text - tdc fs-journal read-journal-entries - --journal-id - [--after-seq ] - [--file-system-name ] - [--fs-token ] - [--help] - [--limit ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-journal read-journal-entries + --journal-id + [--after-seq ] + [--file-system-name ] + [--fs-token ] + [--help] + [--limit ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--journal-id `: Journal ID. \[required] +- `--after-seq `: Read entries after this sequence. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--limit `: Maximum entries to read. \[default: 100] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-journal read-journal-entries --journal-id jrn-demo -tdc fs-journal read-journal-entries --journal-id jrn-demo --after-seq 100 --limit 50 +### Read journal entries + +```bash +tdc fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo +``` + +### Read a page after a sequence number + +```bash +tdc fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo --after-seq 100 --limit 50 ``` diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md index a71b34887af2f..d7e7201e4556c 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md @@ -14,34 +14,54 @@ Searches journals and optionally returns matching entries. ## Syntax ```text - tdc fs-journal search-journal-entries - [--actor ] - [--cursor ] - [--entry-type ] - [--file-system-name ] - [--fs-token ] - [--help] - [--include-entries] - [--journal-kind ] - [--label ] - [--limit ] - [--since ] - [--status ] - [--subject ] - [--until ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-journal search-journal-entries + [--actor ] + [--cursor ] + [--entry-type ] + [--file-system-name ] + [--fs-token ] + [--help] + [--include-entries] + [--journal-kind ] + [--label ] + [--limit ] + [--since ] + [--status ] + [--subject ] + [--until ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--actor `: Actor in the form `type:id`. +- `--cursor `: Pagination cursor. +- `--entry-type `: Entry type filter. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--include-entries`: Include full entry payloads in matches. +- `--journal-kind `: Journal kind filter. +- `--label `: Label filter `key=value`; repeatable. +- `--limit `: Maximum matches to read. \[default: 100] +- `--since `: Relative duration or RFC3339 lower time bound. +- `--status `: Entry status filter. +- `--subject `: Subject filter; repeatable. +- `--until `: RFC3339 upper time bound. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-journal search-journal-entries --entry-type task.started --include-entries -tdc fs-journal search-journal-entries --label env=dev --since 2026-07-01T00:00:00Z --limit 100 +### Search by entry type + +```bash +tdc fs-journal search-journal-entries --file-system-name workspace --entry-type task.started --include-entries +``` + +### Search recent entries by label + +```bash +tdc fs-journal search-journal-entries --file-system-name workspace --label env=dev --since 2026-07-01T00:00:00Z --limit 100 ``` diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md index 812d76bebbe22..564aba725032f 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md @@ -14,24 +14,34 @@ Verifies the integrity of one journal hash chain. ## Syntax ```text - tdc fs-journal verify-journal - --journal-id - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-journal verify-journal + --journal-id + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--journal-id `: Journal ID. \[required] +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-journal verify-journal --journal-id jrn-demo -tdc fs-journal verify-journal --journal-id jrn-demo --output text +### Verify a journal + +```bash +tdc fs-journal verify-journal --file-system-name workspace --journal-id jrn-demo +``` + +### Render verification results as text + +```bash +tdc fs-journal verify-journal --file-system-name workspace --journal-id jrn-demo --output text ``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md index 43a5954847bde..c29a1dccdb972 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md @@ -14,30 +14,46 @@ Creates a time-limited delegated grant for one agent and scope. ## Syntax ```text - tdc fs-vault create-grant - --agent-id - --permission - --scope - --ttl - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--label-hint ] - [--token-only] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-vault create-grant + --agent-id + --permission + --scope + --ttl + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--label-hint ] + [--token-only] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--agent-id `: Agent ID for the delegated grant. \[required] +- `--permission `: Grant permission: `read` or `write`. \[required] +- `--scope `: Vault scope such as secret or secret/field; repeatable. \[required] +- `--ttl `: Grant time to live, for example, `1h`. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--label-hint `: Optional grant label hint. +- `--token-only`: Print only the delegated bearer token. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-vault create-grant --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m -tdc fs-vault create-grant --agent-id ci-agent --scope api-dev/TOKEN --permission read --ttl 5m --token-only +### Create a read grant + +```bash +tdc fs-vault create-grant --file-system-name workspace --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m +``` + +### Create a token-only grant for CI + +```bash +tdc fs-vault create-grant --file-system-name workspace --agent-id ci-agent --scope api-dev/TOKEN --permission read --ttl 5m --token-only ``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md index 7ebd4d4b96633..a4e45818581ee 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md @@ -14,26 +14,38 @@ Creates a secret from one or more `NAME=value` or `NAME=@file` fields. ## Syntax ```text - tdc fs-vault create-secret - --field - --secret-name - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-vault create-secret + --field + --secret-name + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--field `: Secret field assignment `key=value`, `key=@file`, or `key=-`; repeatable. \[required] +- `--secret-name `: Vault secret name. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-vault create-secret --secret-name db-prod --field DB_URL=mysql://example --field PASSWORD=@./password.txt -tdc fs-vault create-secret --secret-name api-dev --field TOKEN=@./token.txt --dry-run +### Create a secret from values and a file + +```bash +tdc fs-vault create-secret --file-system-name workspace --secret-name db-prod --field DB_URL=mysql://example --field PASSWORD=@./password.txt +``` + +### Preview secret creation + +```bash +tdc fs-vault create-secret --file-system-name workspace --secret-name api-dev --field TOKEN=@./token.txt --dry-run ``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md index 904511239cf81..9b7469151d339 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md @@ -14,27 +14,40 @@ Revokes one delegated Filesystem Vault grant. ## Syntax ```text - tdc fs-vault delete-grant - --grant-id - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--reason ] - [--revoked-by ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-vault delete-grant + --grant-id + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--reason ] + [--revoked-by ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--grant-id `: Vault grant ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--reason `: Optional revoke reason. +- `--revoked-by `: Actor label for the revoke audit entry. \[default: tdc] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-vault delete-grant --grant-id "" --reason rotated -tdc fs-vault delete-grant --grant-id "" --revoked-by operator --dry-run +### Revoke a grant with a reason + +```bash +tdc fs-vault delete-grant --file-system-name workspace --grant-id "" --reason rotated +``` + +### Preview grant revocation + +```bash +tdc fs-vault delete-grant --file-system-name workspace --grant-id "" --revoked-by operator --dry-run ``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md index 8b08a5d90b123..a099b879a80ae 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md @@ -14,25 +14,36 @@ Deletes one Filesystem Vault secret. ## Syntax ```text - tdc fs-vault delete-secret - --secret-name - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-vault delete-secret + --secret-name + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--secret-name `: Vault secret name. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-vault delete-secret --secret-name db-prod --dry-run -tdc fs-vault delete-secret --secret-name db-prod +### Preview secret deletion + +```bash +tdc fs-vault delete-secret --file-system-name workspace --secret-name db-prod --dry-run +``` + +### Delete a secret + +```bash +tdc fs-vault delete-secret --file-system-name workspace --secret-name db-prod ``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md index af53d7431cb84..dafe06406f548 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md @@ -14,27 +14,40 @@ Lists vault audit events with optional agent, secret, and time filters. ## Syntax ```text - tdc fs-vault list-audit-events - [--agent-id ] - [--file-system-name ] - [--fs-token ] - [--help] - [--limit ] - [--secret-name ] - [--since ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-vault list-audit-events + [--agent-id ] + [--file-system-name ] + [--fs-token ] + [--help] + [--limit ] + [--secret-name ] + [--since ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--agent-id `: Filter by agent ID. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--limit `: Maximum events to return. \[default: 100] +- `--secret-name `: Filter by Vault secret name. +- `--since `: Client-side relative time filter, for example, `24h`. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-vault list-audit-events --secret-name db-prod --limit 20 -tdc fs-vault list-audit-events --agent-id deploy-agent --since 24h --output text +### List audit events for a secret + +```bash +tdc fs-vault list-audit-events --file-system-name workspace --secret-name db-prod --limit 20 +``` + +### List recent events for an agent + +```bash +tdc fs-vault list-audit-events --file-system-name workspace --agent-id deploy-agent --since 24h --output text ``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md index 2e58565973398..4d6dc47f52f44 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md @@ -14,24 +14,34 @@ Lists secrets visible to the active owner or delegated credential. ## Syntax ```text - tdc fs-vault list-secrets - [--file-system-name ] - [--fs-token ] - [--help] - [--vault-token ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-vault list-secrets + [--file-system-name ] + [--fs-token ] + [--help] + [--vault-token ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--vault-token `: Delegated tdc fs-vault token; prefer `TDC_VAULT_TOKEN`. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-vault list-secrets -tdc fs-vault list-secrets --vault-token "$TDC_VAULT_TOKEN" --output text +### List secrets + +```bash +tdc fs-vault list-secrets --file-system-name workspace +``` + +### List secrets with a delegated Vault token + +```bash +tdc fs-vault list-secrets --file-system-name workspace --vault-token "$TDC_VAULT_TOKEN" --output text ``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md index cf923a1180792..8451ea76908d0 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md @@ -14,28 +14,42 @@ Mounts readable vault fields as a local read-only FUSE filesystem. ## Syntax ```text - tdc fs-vault mount-vault - --mount-path - [--dry-run] - [--file-system-name ] - [--foreground] - [--fs-token ] - [--help] - [--ready-timeout ] - [--vault-token ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-vault mount-vault + --mount-path + [--dry-run] + [--file-system-name ] + [--foreground] + [--fs-token ] + [--help] + [--ready-timeout ] + [--vault-token ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--mount-path `: Local mount path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--foreground`: Run mount runtime in the foreground until interrupted. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--ready-timeout `: Time to wait for a background mount to become ready. \[default: `30s`] +- `--vault-token `: Delegated tdc fs-vault token; prefer `TDC_VAULT_TOKEN`. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-vault mount-vault --mount-path ./vault --vault-token "$TDC_VAULT_TOKEN" -tdc fs-vault mount-vault --mount-path ./vault --foreground --ready-timeout 60s +### Mount a Vault view with a delegated token + +```bash +tdc fs-vault mount-vault --file-system-name workspace --mount-path ./vault --vault-token "$TDC_VAULT_TOKEN" +``` + +### Run a Vault mount in the foreground + +```bash +tdc fs-vault mount-vault --file-system-name workspace --mount-path ./vault --foreground --ready-timeout 60s ``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md index 23136e997a7ae..8503ec8ae586b 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md @@ -14,27 +14,40 @@ Reads a complete secret or one field using an owner or delegated credential. ## Syntax ```text - tdc fs-vault read-secret - --secret-name - [--field ] - [--file-system-name ] - [--format ] - [--fs-token ] - [--help] - [--vault-token ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-vault read-secret + --secret-name + [--field ] + [--file-system-name ] + [--format ] + [--fs-token ] + [--help] + [--vault-token ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--secret-name `: Vault secret name. \[required] +- `--field `: Optional field name to read. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--format `: Read output format: `json`, `raw`, or `env`. \[default: json] +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--vault-token `: Delegated tdc fs-vault token; prefer `TDC_VAULT_TOKEN`. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-vault read-secret --secret-name db-prod --field PASSWORD --format raw -tdc fs-vault read-secret --secret-name db-prod --field DB_URL --format env +### Read one secret field + +```bash +tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field PASSWORD --format raw +``` + +### Format a secret field as an environment variable + +```bash +tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field DB_URL --format env ``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md index 8f90d734c8aa6..b38e308c5d218 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md @@ -14,26 +14,38 @@ Replaces all fields in one secret from files in a local directory. ## Syntax ```text - tdc fs-vault replace-secret - --from-directory - --secret-path - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-vault replace-secret + --from-directory + --secret-path + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--from-directory `: Directory whose files become secret fields. \[required] +- `--secret-path `: Vault path in the form `/n/vault/`. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-vault replace-secret --secret-path /n/vault/db-prod --from-directory ./secret-fields -tdc fs-vault replace-secret --secret-path /n/vault/db-prod --from-directory ./secret-fields --dry-run +### Replace a secret from a directory + +```bash +tdc fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields +``` + +### Preview secret replacement + +```bash +tdc fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields --dry-run ``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md index ca024f6c9d439..2c12cbfc88b55 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md @@ -14,25 +14,36 @@ Runs a command with one secret injected into its environment. Arguments after `- ## Syntax ```text - tdc fs-vault run-with-secret - --secret-path - [--file-system-name ] - [--fs-token ] - [--help] - [--vault-token ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-vault run-with-secret + --secret-path + [--file-system-name ] + [--fs-token ] + [--help] + [--vault-token ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--secret-path `: Vault path in the form `/n/vault/`. \[required] +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--vault-token `: Delegated tdc fs-vault token; prefer `TDC_VAULT_TOKEN`. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs-vault run-with-secret --secret-path /n/vault/db-prod -- env -tdc fs-vault run-with-secret --secret-path /n/vault/db-prod -- sh -c 'test -n "$DB_URL"' +### Run a command with secret fields + +```bash +tdc fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- env +``` + +### Use an injected secret in a shell command + +```bash +tdc fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- sh -c 'test -n "$DB_URL"' ``` diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md index 861147d65de43..33f5d3803c8d8 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md @@ -14,26 +14,38 @@ Unmounts a local Filesystem Vault filesystem. ## Syntax ```text - tdc fs-vault unmount-vault - --mount-path - [--dry-run] - [--force] - [--help] - [--ignore-absent] - [--timeout ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs-vault unmount-vault + --mount-path + [--dry-run] + [--force] + [--help] + [--ignore-absent] + [--timeout ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--mount-path `: Local mount path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--force`: Force-kill the mount process if graceful unmount times out. +- `--help`: Display help information. +- `--ignore-absent`: Return success when no tdc fs-vault mount state exists for the path. +- `--timeout `: Time to wait for the mount process to exit. \[default: `30s`] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Unmount a Vault view + +```bash tdc fs-vault unmount-vault --mount-path ./vault +``` + +### Ignore an absent Vault mount + +```bash tdc fs-vault unmount-vault --mount-path ./vault --ignore-absent ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md index c7b50b55b157a..1d06d3f6089ed 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md @@ -14,23 +14,32 @@ Checks Filesystem selection, endpoint resolution, credentials, and companion acc ## Syntax ```text - tdc fs check-file-system - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs check-file-system + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Check file system connectivity + +```bash tdc fs check-file-system --file-system-name workspace +``` + +### Render the check result as text + +```bash tdc fs check-file-system --file-system-name workspace --output text ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md b/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md index 3345fbd7ec06f..5e42a03cd0e93 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md @@ -14,26 +14,38 @@ Changes POSIX mode metadata for a remote path. The command alias is `tdc fs chmo ## Syntax ```text - tdc fs chmod-file - --mode - --path - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs chmod-file + --mode + --path + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--mode `: The permission mode as an octal value such as 0644. \[required] +- `--path `: File or directory path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs chmod-file --path /reports/final.md --mode 0600 -tdc fs chmod --path /reports/final.md --mode 0644 --dry-run +### Change file permissions + +```bash +tdc fs chmod-file --file-system-name workspace --path /reports/final.md --mode 0600 +``` + +### Preview a permission change with the alias + +```bash +tdc fs chmod --file-system-name workspace --path /reports/final.md --mode 0644 --dry-run ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md index 9f41c6d77c742..eb500ff492b28 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md @@ -14,25 +14,36 @@ Applies one layer to its base Filesystem. ## Syntax ```text - tdc fs commit-layer - --layer-id - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs commit-layer + --layer-id + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--layer-id `: Layer ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs commit-layer --layer-id "" --dry-run -tdc fs commit-layer --layer-id "" +### Preview a layer commit + +```bash +tdc fs commit-layer --file-system-name workspace --layer-id "" --dry-run +``` + +### Commit a layer + +```bash +tdc fs commit-layer --file-system-name workspace --layer-id "" ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md b/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md index cb299db53e136..400d63e41ddbc 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md @@ -14,38 +14,62 @@ Copies files between local paths, remote paths, stdin, and stdout. The command a ## Syntax ```text - tdc fs copy-file - [--append] - [--create-parents] - [--description ] - [--dry-run] - [--file-system-name ] - [--from-local ] - [--from-remote ] - [--from-stdin] - [--fs-token ] - [--help] - [--layer-id ] - [--overwrite] - [--recursive] - [--resume] - [--tag ] - [--to-local ] - [--to-remote ] - [--to-stdout] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs copy-file + [--append] + [--create-parents] + [--description ] + [--dry-run] + [--file-system-name ] + [--from-local ] + [--from-remote ] + [--from-stdin] + [--fs-token ] + [--help] + [--layer-id ] + [--overwrite] + [--recursive] + [--resume] + [--tag ] + [--to-local ] + [--to-remote ] + [--to-stdout] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--append`: Append the contents of a local file to a file in the TiDB Cloud file system. +- `--create-parents`: Create missing local parent directories when copying from a TiDB Cloud file system. +- `--description `: The file description for `--to-remote` operation. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--from-local `: The local source path. +- `--from-remote `: The source path in the TiDB Cloud file system. +- `--from-stdin`: Read from stdin and write to `--to-remote`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--layer-id `: Write the copied file content into a file system layer instead of the base file system. +- `--overwrite`: Replace an existing destination file. +- `--recursive`: Copy directory structure recursively. +- `--resume`: Resume an active copy operation. +- `--tag `: Create tags `key=value` for `--to-remote` operation; repeatable. +- `--to-local `: The local destination path. +- `--to-remote `: The destination path in the TiDB Cloud file system. +- `--to-stdout`: Write `--from-remote` to stdout. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs copy-file --from-local ./report.md --to-remote /reports/report.md -tdc fs copy-file --from-remote /reports/report.md --to-local ./report.copy.md --create-parents +### Upload a local file + +```bash +tdc fs copy-file --file-system-name workspace --from-local ./report.md --to-remote /reports/report.md +``` + +### Download a remote file + +```bash +tdc fs copy-file --file-system-name workspace --from-remote /reports/report.md --to-local ./report.copy.md --create-parents ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md b/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md index 8258208b1b3a4..ea4970a760826 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md @@ -14,26 +14,38 @@ Creates a remote directory. The command alias is `tdc fs mkdir`. ## Syntax ```text - tdc fs create-directory - --path - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--mode ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs create-directory + --path + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--mode ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--path `: The file system path of the directory to create. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--mode `: The directory mode as an octal value such as 0755. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs create-directory --path /reports/archive --mode 0755 -tdc fs mkdir --path /reports/review --dry-run +### Create a directory + +```bash +tdc fs create-directory --file-system-name workspace --path /reports/archive --mode 0755 +``` + +### Preview directory creation with the alias + +```bash +tdc fs mkdir --file-system-name workspace --path /reports/review --dry-run ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md index 3ff33fc90bc6e..bee862bf1eade 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md @@ -14,24 +14,34 @@ Creates a Filesystem. `--wait` waits until data-plane access is ready. ## Syntax ```text - tdc fs create-file-system - --file-system-name - [--dry-run] - [--help] - [--version] - [--wait] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs create-file-system + --file-system-name + [--dry-run] + [--help] + [--version] + [--wait] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--file-system-name `: Set the file system name. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--version`: Display tdc version information. +- `--wait`: Wait until the created file system is active. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Create a file system and wait until it is ready + +```bash tdc fs create-file-system --file-system-name workspace --wait +``` + +### Preview file system creation + +```bash tdc fs create-file-system --file-system-name workspace --dry-run ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md b/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md index afb7c82c1241c..e5762a6cdad81 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md @@ -14,26 +14,38 @@ Creates a hard link to an existing remote path. The command alias is `tdc fs har ## Syntax ```text - tdc fs create-hardlink - --link-path - --source-path - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs create-hardlink + --link-path + --source-path + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--link-path `: The file path for the hard link being created in the TiDB Cloud file system. \[required] +- `--source-path `: The existing file path in the TiDB Cloud file system. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs create-hardlink --source-path /reports/final.md --link-path /reports/final-copy.md -tdc fs hardlink --source-path /reports/final.md --link-path /reports/backup.md --dry-run +### Create a hard link + +```bash +tdc fs create-hardlink --file-system-name workspace --source-path /reports/final.md --link-path /reports/final-copy.md +``` + +### Preview hard-link creation with the alias + +```bash +tdc fs hardlink --file-system-name workspace --source-path /reports/final.md --link-path /reports/backup.md --dry-run ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md b/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md index cc4eefe0e19e8..2eaed1bf1cd27 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md @@ -14,27 +14,40 @@ Creates a checkpoint in one layer. If `--checkpoint-id` is omitted, the service ## Syntax ```text - tdc fs create-layer-checkpoint - --layer-id - [--checkpoint-id ] - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--label ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs create-layer-checkpoint + --layer-id + [--checkpoint-id ] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--label ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--layer-id `: The layer ID identifying the layer. \[required] +- `--checkpoint-id `: Checkpoint ID. Normally it is generated by the service automatically. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--label `: The checkpoint label. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs create-layer-checkpoint --layer-id "" --checkpoint-id before-review -tdc fs create-layer-checkpoint --layer-id "" --label "before review" --dry-run +### Create a checkpoint with an explicit ID + +```bash +tdc fs create-layer-checkpoint --file-system-name workspace --layer-id "" --checkpoint-id before-review +``` + +### Preview an automatically identified checkpoint + +```bash +tdc fs create-layer-checkpoint --file-system-name workspace --layer-id "" --label "before review" --dry-run ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md index 580a11f7230ca..0f18a37802fd7 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md @@ -14,30 +14,46 @@ Creates an isolated change layer over a base root. If `--layer-id` is omitted, t ## Syntax ```text - tdc fs create-layer - --base-root-path - [--actor-id ] - [--dry-run] - [--durability-mode ] - [--file-system-name ] - [--fs-token ] - [--help] - [--layer-id ] - [--layer-name ] - [--tag ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs create-layer + --base-root-path + [--actor-id ] + [--dry-run] + [--durability-mode ] + [--file-system-name ] + [--fs-token ] + [--help] + [--layer-id ] + [--layer-name ] + [--tag ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--base-root-path `: Base root path in the TiDB Cloud file system. \[required] +- `--actor-id `: Actor ID identifying the layer owner (for example, the agent name). +- `--dry-run`: Validate the request without applying changes. +- `--durability-mode `: Layer durability mode; must be `restore-safe`. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--layer-id `: The layer ID. Normally it is generated by the service automatically. +- `--layer-name `: The name of the layer. +- `--tag `: Tags for the layer, `key=value`; repeatable. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs create-layer --base-root-path /workspace --layer-name agent-task -tdc fs create-layer --base-root-path /workspace --durability-mode restore-safe --tag task=review --dry-run +### Create a layer + +```bash +tdc fs create-layer --file-system-name workspace --base-root-path /workspace --layer-name agent-task +``` + +### Preview a restore-safe layer + +```bash +tdc fs create-layer --file-system-name workspace --base-root-path /workspace --durability-mode restore-safe --tag task=review --dry-run ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md b/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md index 609dd684e21f0..398481f493191 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md @@ -14,26 +14,38 @@ Creates a symbolic link. The command alias is `tdc fs symlink`. ## Syntax ```text - tdc fs create-symlink - --link-path - --target - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs create-symlink + --link-path + --target + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--link-path `: The file path for the created symbolic link. \[required] +- `--target `: The actual file path being linked to. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs create-symlink --target final.md --link-path /reports/latest.md -tdc fs symlink --target archive/report.md --link-path /reports/archive-link --dry-run +### Create a symbolic link + +```bash +tdc fs create-symlink --file-system-name workspace --target final.md --link-path /reports/latest.md +``` + +### Preview symbolic-link creation with the alias + +```bash +tdc fs symlink --file-system-name workspace --target archive/report.md --link-path /reports/archive-link --dry-run ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md index 758d153d43aaf..5915594593e32 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md @@ -14,24 +14,34 @@ Requests asynchronous Filesystem deletion and removes its local registration. ## Syntax ```text - tdc fs delete-file-system - --file-system-name - [--dry-run] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs delete-file-system + --file-system-name + [--dry-run] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--file-system-name `: Set the file system name. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Preview file system deletion + +```bash tdc fs delete-file-system --file-system-name workspace --dry-run +``` + +### Delete a file system + +```bash tdc fs delete-file-system --file-system-name workspace ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md b/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md index 113e262ac950b..95d0861056296 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md @@ -14,26 +14,38 @@ Deletes a remote file or directory. The command alias is `tdc fs rm`. ## Syntax ```text - tdc fs delete-file - --path - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--recursive] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs delete-file + --path + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--recursive] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--path `: File or directory path in the TiDB Cloud file system. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--recursive`: Delete a directory recursively. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs delete-file --path /reports/obsolete.md -tdc fs delete-file --path /scratch --recursive --dry-run +### Delete a file + +```bash +tdc fs delete-file --file-system-name workspace --path /reports/obsolete.md +``` + +### Preview recursive directory deletion + +```bash +tdc fs delete-file --file-system-name workspace --path /scratch --recursive --dry-run ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md index 080cbf4f7b9e8..6bde39e86386e 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md @@ -14,22 +14,30 @@ Describes one locally registered Filesystem. ## Syntax ```text - tdc fs describe-file-system - --file-system-name - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs describe-file-system + --file-system-name + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--file-system-name `: Set the file system name. \[required] +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Describe a file system + +```bash tdc fs describe-file-system --file-system-name workspace +``` + +### Render file system details as text + +```bash tdc fs describe-file-system --file-system-name workspace --output text ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md index 06e871ca8bfaf..02bc1c2aa0579 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md @@ -14,24 +14,34 @@ Describes metadata for one remote path. The command alias is `tdc fs stat`. ## Syntax ```text - tdc fs describe-file - --path - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs describe-file + --path + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--path `: File or directory path in the TiDB Cloud file system. \[required] +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs describe-file --path /reports/report.md -tdc fs stat --path /reports/report.md --output text +### Describe a file + +```bash +tdc fs describe-file --file-system-name workspace --path /reports/report.md +``` + +### Use the stat alias with text output + +```bash +tdc fs stat --file-system-name workspace --path /reports/report.md --output text ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md index eade16d846b94..a3def67899089 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md @@ -14,24 +14,34 @@ Describes one Filesystem layer. ## Syntax ```text - tdc fs describe-layer - --layer-id - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs describe-layer + --layer-id + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--layer-id `: The ID of the specified file system layer. \[required] +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs describe-layer --layer-id "" -tdc fs describe-layer --layer-id "" --output text +### Describe a layer + +```bash +tdc fs describe-layer --file-system-name workspace --layer-id "" +``` + +### Render layer details as text + +```bash +tdc fs describe-layer --file-system-name workspace --layer-id "" --output text ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md index 033da4606080e..3d0d3bc2053c8 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md @@ -14,25 +14,36 @@ Lists changes in one layer, optionally up to a sequence number. ## Syntax ```text - tdc fs diff-layer - --layer-id - [--file-system-name ] - [--fs-token ] - [--help] - [--max-seq ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs diff-layer + --layer-id + [--file-system-name ] + [--fs-token ] + [--help] + [--max-seq ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--layer-id `: The ID of the layer. \[required] +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--max-seq `: The highest layer sequence to include; 0 includes all layers. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs diff-layer --layer-id "" -tdc fs diff-layer --layer-id "" --max-seq 100 +### Show all layer changes + +```bash +tdc fs diff-layer --file-system-name workspace --layer-id "" +``` + +### Show changes through a sequence number + +```bash +tdc fs diff-layer --file-system-name workspace --layer-id "" --max-seq 100 ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md index d166ff6512034..507ee92bf4bf8 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md @@ -14,24 +14,34 @@ Flushes dirty FUSE state while leaving the mount online. The command alias is `t ## Syntax ```text - tdc fs drain-file-system - --mount-path - [--dry-run] - [--help] - [--timeout ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs drain-file-system + --mount-path + [--dry-run] + [--help] + [--timeout ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--mount-path `: Local FUSE mount path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--timeout `: The time to wait for dirty handles and pending writes to drain. \[default: `30s`] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Drain pending writes + +```bash tdc fs drain-file-system --mount-path /path/to/workspace +``` + +### Drain with the alias and an explicit timeout + +```bash tdc fs drain --mount-path /path/to/workspace --timeout 30s ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-find-files.md b/ai/tdc/reference/commands/fs/tdc-fs-find-files.md index 54a638cab2cdf..58f8344c5e38b 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-find-files.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-find-files.md @@ -14,33 +14,52 @@ Finds remote paths by name, type, tag, size, or modification time. The command a ## Syntax ```text - tdc fs find-files - [--file-name-pattern ] - [--file-system-name ] - [--fs-token ] - [--help] - [--layer-id ] - [--limit ] - [--max-size-bytes ] - [--min-size-bytes ] - [--newer ] - [--older ] - [--path ] - [--resource-type ] - [--tag ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs find-files + [--file-name-pattern ] + [--file-system-name ] + [--fs-token ] + [--help] + [--layer-id ] + [--limit ] + [--max-size-bytes ] + [--min-size-bytes ] + [--newer ] + [--older ] + [--path ] + [--resource-type ] + [--tag ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--file-name-pattern `: File name pattern filter, such as `*.md`. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--layer-id `: Search files and directories within a specific file system layer. +- `--limit `: Maximum number of results; 0 uses the service default. +- `--max-size-bytes `: Maximum file size in bytes. +- `--min-size-bytes `: Minimum file size in bytes. +- `--newer `: Only return files newer than the filter. +- `--older `: Only return files older than the filter. +- `--path `: File path prefix. \[default: /] +- `--resource-type `: Resource type filter: `file` or `directory`. +- `--tag `: Tag filter. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs find-files --path /workspace --file-name-pattern "*.md" -tdc fs find --path /workspace --tag stage=review --min-size-bytes 1024 +### Find files by name + +```bash +tdc fs find-files --file-system-name workspace --path /workspace --file-name-pattern "*.md" +``` + +### Find tagged files with the alias + +```bash +tdc fs find --file-system-name workspace --path /workspace --tag stage=review --min-size-bytes 1024 ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md b/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md index 15036a1dcbae3..469f00f789652 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md @@ -14,21 +14,28 @@ Lists Filesystems registered in the selected local profile. ## Syntax ```text - tdc fs list-file-systems - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs list-file-systems + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### List registered file systems as text + +```bash tdc fs list-file-systems --output text +``` + +### Return registered file system names + +```bash tdc fs list-file-systems --query 'file_systems[].file_system_name' ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-files.md b/ai/tdc/reference/commands/fs/tdc-fs-list-files.md index 37c8f1b293b56..b1be753ee324f 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-files.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-files.md @@ -14,24 +14,34 @@ Lists entries below a remote path. The command alias is `tdc fs ls`. ## Syntax ```text - tdc fs list-files - [--file-system-name ] - [--fs-token ] - [--help] - [--path ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs list-files + [--file-system-name ] + [--fs-token ] + [--help] + [--path ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--path `: File system directory path. \[default: /] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs list-files --path /reports -tdc fs list-files --path /reports --output text +### List files + +```bash +tdc fs list-files --file-system-name workspace --path /reports +``` + +### List files as text + +```bash +tdc fs list-files --file-system-name workspace --path /reports --output text ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md b/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md index 0061e0474f5d4..a41e115d6c5a1 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md @@ -14,23 +14,32 @@ Lists layers for the selected Filesystem. ## Syntax ```text - tdc fs list-layers - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs list-layers + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs list-layers -tdc fs list-layers --output text +### List layers + +```bash +tdc fs list-layers --file-system-name workspace +``` + +### List layers as text + +```bash +tdc fs list-layers --file-system-name workspace --output text ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md index f30cfb2954734..aa69bf45cfa15 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md @@ -14,40 +14,66 @@ Mounts a Filesystem through automatic, FUSE, or WebDAV mode. The command alias i ## Syntax ```text - tdc fs mount-file-system - --mount-path - [--cache-dir ] - [--driver ] - [--dry-run] - [--file-system-name ] - [--foreground] - [--fs-token ] - [--help] - [--local-root ] - [--mount-profile ] - [--no-auto-unpack] - [--pack-path ] - [--read-cache-max-file-mb ] - [--read-cache-size-mb ] - [--read-cache-ttl ] - [--read-only] - [--ready-timeout ] - [--remote-path ] - [--unpack-archive-path ] - [--version] - [--write-back-cache] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs mount-file-system + --mount-path + [--cache-dir ] + [--driver ] + [--dry-run] + [--file-system-name ] + [--foreground] + [--fs-token ] + [--help] + [--local-root ] + [--mount-profile ] + [--no-auto-unpack] + [--pack-path ] + [--read-cache-max-file-mb ] + [--read-cache-size-mb ] + [--read-cache-ttl ] + [--read-only] + [--ready-timeout ] + [--remote-path ] + [--unpack-archive-path ] + [--version] + [--write-back-cache] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--mount-path `: Local mount path. \[required] +- `--cache-dir `: Local FUSE cache directory. If omitted, uses `~/.tdc/cache/mounts/`. +- `--driver `: Mount driver: `auto`, `fuse`, or `webdav`. \[default: auto] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--foreground`: Run the mount runtime in the foreground until interrupted. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--local-root `: Local overlay root. If omitted, uses `~/.tdc/local/fs/`. +- `--mount-profile `: Mount profile: `coding-agent`, `portable`, or `none`. If omitted, uses `none`. +- `--no-auto-unpack`: Skip default auto-unpack for portable mount profile before mounting. +- `--pack-path `: Local overlay path included by automatic or manual pack. Repeatable. +- `--read-cache-max-file-mb `: Maximum file size admitted to the FUSE read cache in MiB. 0 uses the default. \[default: 4] +- `--read-cache-size-mb `: FUSE read cache size in MiB. 0 uses the default. \[default: 128] +- `--read-cache-ttl `: FUSE read cache time to live. \[default: `30s`] +- `--read-only`: Read-only mount mode. +- `--ready-timeout `: Time to wait for a background mount to become ready. \[default: `30s`] +- `--remote-path `: The TiDB Cloud file system root path to mount. \[default: /] +- `--unpack-archive-path `: Restore the pack archive before mounting. +- `--version`: Display tdc version information. +- `--write-back-cache`: Persist FUSE writes locally before writing them to the file system on flush. \[default: true] + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Mount a file system + +```bash tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace -tdc fs mount --mount-path /path/to/workspace --driver fuse --read-only +``` + +### Create a read-only FUSE mount with the alias + +```bash +tdc fs mount --file-system-name workspace --mount-path /path/to/workspace --driver fuse --read-only ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-move-file.md b/ai/tdc/reference/commands/fs/tdc-fs-move-file.md index c3b4a2a87db37..b9bbe821a48bd 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-move-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-move-file.md @@ -14,27 +14,40 @@ Moves or renames a remote path. The command alias is `tdc fs mv`. ## Syntax ```text - tdc fs move-file - --from-remote - --to-remote - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--overwrite] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs move-file + --from-remote + --to-remote + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--overwrite] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--from-remote `: Source file path. \[required] +- `--to-remote `: Destination file path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--overwrite`: Replace an existing destination file. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs move-file --from-remote /draft.md --to-remote /reports/final.md -tdc fs mv --from-remote /draft.md --to-remote /reports/final.md --dry-run +### Move a remote file + +```bash +tdc fs move-file --file-system-name workspace --from-remote /draft.md --to-remote /reports/final.md +``` + +### Preview a move with the alias + +```bash +tdc fs mv --file-system-name workspace --from-remote /draft.md --to-remote /reports/final.md --dry-run ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md index 54eceebd89712..401bb2ba2452b 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md @@ -14,30 +14,46 @@ Packs selected local overlay state into a remote archive. ## Syntax ```text - tdc fs pack-file-system - [--archive-path ] - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--local-root ] - [--mount-path ] - [--mount-profile ] - [--path ] - [--remote-root ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs pack-file-system + [--archive-path ] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--local-root ] + [--mount-path ] + [--mount-profile ] + [--path ] + [--remote-root ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--archive-path `: The path for the packed archive. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--local-root `: Local overlay root containing the overlay directory. +- `--mount-path `: The local mounted path. +- `--mount-profile `: The mount profile: `coding-agent`, `portable`, or `none`. If omitted, uses `none`. +- `--path `: Local overlay path for packing; repeatable. +- `--remote-root `: The TiDB Cloud file system root represented by the local overlay. \[default: /] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs pack-file-system --mount-path /path/to/workspace -tdc fs pack-file-system --local-root ./overlay --remote-root /workspace --mount-profile portable +### Pack a mounted workspace + +```bash +tdc fs pack-file-system --file-system-name workspace --mount-path /path/to/workspace +``` + +### Pack explicit local and remote roots + +```bash +tdc fs pack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-read-file.md b/ai/tdc/reference/commands/fs/tdc-fs-read-file.md index 0f63315ce3d7c..14627f0fa9425 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-read-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-read-file.md @@ -14,26 +14,38 @@ Writes a remote file or byte range to stdout. The command alias is `tdc fs cat`. ## Syntax ```text - tdc fs read-file - --path - [--file-system-name ] - [--fs-token ] - [--help] - [--length ] - [--offset ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs read-file + --path + [--file-system-name ] + [--fs-token ] + [--help] + [--length ] + [--offset ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--path `: File path in the selected file system. \[required] +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--length `: Byte length for a ranged read. +- `--offset `: Zero-based byte offset for a ranged read. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs read-file --path /reports/report.md -tdc fs read-file --path /archives/large.bin --offset 1024 --length 4096 +### Read a file + +```bash +tdc fs read-file --file-system-name workspace --path /reports/report.md +``` + +### Read a byte range + +```bash +tdc fs read-file --file-system-name workspace --path /archives/large.bin --offset 1024 --length 4096 ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md index 782cdd4de0ddd..53b9704a60aa3 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md @@ -14,25 +14,36 @@ Rolls back changes in one layer without committing them to the base. ## Syntax ```text - tdc fs rollback-layer - --layer-id - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs rollback-layer + --layer-id + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--layer-id `: The ID of the layer. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs rollback-layer --layer-id "" --dry-run -tdc fs rollback-layer --layer-id "" +### Preview a layer rollback + +```bash +tdc fs rollback-layer --file-system-name workspace --layer-id "" --dry-run +``` + +### Roll back a layer + +```bash +tdc fs rollback-layer --file-system-name workspace --layer-id "" ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md b/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md index e6c4e0acfb22b..1b95c114d80a8 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md @@ -14,27 +14,40 @@ Searches remote file content, optionally in a layer. The command alias is `tdc f ## Syntax ```text - tdc fs search-file-content - --pattern - [--file-system-name ] - [--fs-token ] - [--help] - [--layer-id ] - [--limit ] - [--path ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs search-file-content + --pattern + [--file-system-name ] + [--fs-token ] + [--help] + [--layer-id ] + [--limit ] + [--path ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--pattern `: Content search matching pattern. \[required] +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--layer-id `: Search within a file system layer. +- `--limit `: Maximum number of search results; 0 uses the service default. +- `--path `: File path prefix to be searched. \[default: /] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs search-file-content --path /workspace --pattern "TODO" --limit 50 -tdc fs grep --path /workspace --pattern "deprecated" --layer-id "" +### Search file content + +```bash +tdc fs search-file-content --file-system-name workspace --path /workspace --pattern "TODO" --limit 50 +``` + +### Search a layer with the grep alias + +```bash +tdc fs grep --file-system-name workspace --path /workspace --pattern "deprecated" --layer-id "" ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md index fdd0d40feeafe..7291569d402e8 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md @@ -14,28 +14,42 @@ Gracefully flushes and unmounts a background mount. The command alias is `tdc fs ## Syntax ```text - tdc fs unmount-file-system - --mount-path - [--dry-run] - [--force] - [--help] - [--ignore-absent] - [--no-auto-pack] - [--pack-archive-path ] - [--timeout ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs unmount-file-system + --mount-path + [--dry-run] + [--force] + [--help] + [--ignore-absent] + [--no-auto-pack] + [--pack-archive-path ] + [--timeout ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--mount-path `: The local mounted path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--force`: Kill the mount process if graceful unmount times out. +- `--help`: Display help information. +- `--ignore-absent`: Return success when no file system mount state exists for the specified path. +- `--no-auto-pack`: Skip the portable mount profile's default auto-pack action. +- `--pack-archive-path `: Pack archive to write after unmount. +- `--timeout `: Time to wait for the mount process to exit. \[default: `30s`] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Unmount a file system + +```bash tdc fs unmount-file-system --mount-path /path/to/workspace +``` + +### Ignore an absent mount with the alias + +```bash tdc fs umount --mount-path /path/to/workspace --ignore-absent ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md index 2e93a90ad79c3..02a74ee7b1b24 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md @@ -14,30 +14,46 @@ Restores local overlay state from a remote archive. ## Syntax ```text - tdc fs unpack-file-system - [--archive-path ] - [--dry-run] - [--file-system-name ] - [--fs-token ] - [--help] - [--local-root ] - [--mount-path ] - [--mount-profile ] - [--no-replace] - [--remote-root ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc fs unpack-file-system + [--archive-path ] + [--dry-run] + [--file-system-name ] + [--fs-token ] + [--help] + [--local-root ] + [--mount-path ] + [--mount-profile ] + [--no-replace] + [--remote-root ] + [--version] ``` -Filesystem selection can come from `--file-system-name`, `TDC_FS_FILE_SYSTEM_NAME`, or the selected profile. For shared global flags, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--archive-path `: The path for the packed archive. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--help`: Display help information. +- `--local-root `: The local overlay root to restore into. +- `--mount-path `: The local mounted path. +- `--mount-profile `: Mount profile: `coding-agent`, `portable`, or `none`. If omitted, uses `none`. +- `--no-replace`: Merge archive entries instead of replacing them. +- `--remote-root `: Find the packed archive under the specified root path when `--archive-path` is omitted. \[default: /] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell -tdc fs unpack-file-system --mount-path /path/to/workspace -tdc fs unpack-file-system --local-root ./overlay --remote-root /workspace --mount-profile portable --no-replace +### Unpack into a mounted workspace + +```bash +tdc fs unpack-file-system --file-system-name workspace --mount-path /path/to/workspace +``` + +### Unpack explicit roots without replacing files + +```bash +tdc fs unpack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable --no-replace ``` diff --git a/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md b/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md index 49d5f124d8c69..3296a518e65b9 100644 --- a/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md +++ b/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md @@ -14,23 +14,32 @@ Lists projects accessible to the configured TiDB Cloud API key, with optional pa ## Syntax ```text - tdc organization list-projects - [--help] - [--page-size ] - [--page-token ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc organization list-projects + [--help] + [--page-size ] + [--page-token ] + [--version] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--help`: Display help information. +- `--page-size `: Number of projects to request; 0 uses the API default. +- `--page-token `: Page token returned by a previous list-projects call. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### List projects as text + +```bash tdc organization list-projects --page-size 50 --output text +``` + +### Return virtual project IDs + +```bash tdc organization list-projects --query 'projects[?type == `tidbx_virtual`].id' --output text ``` diff --git a/ai/tdc/reference/commands/tdc/tdc-configure.md b/ai/tdc/reference/commands/tdc/tdc-configure.md index d3ab958b5b37f..99608892413f6 100644 --- a/ai/tdc/reference/commands/tdc/tdc-configure.md +++ b/ai/tdc/reference/commands/tdc/tdc-configure.md @@ -14,25 +14,39 @@ Configures a local tdc profile. Without flags, this is the only interactive tdc ## Syntax ```text - tdc configure - [--help] - [--non-interactive] - [--region-code ] - [--tdc-private-key ] - [--tdc-public-key ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc configure + [--help] + [--non-interactive] + [--region-code ] + [--tdc-private-key ] + [--tdc-public-key ] + [--version] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--help`: Display help information. +- `--non-interactive`: Use this option to avoid being prompted for configuration values. You must provide at least three configuration values (`--tdc-public-key`, `--tdc-private-key`, and `--region-code`) when using this option. This is useful when running tdc in a script or automated environment. +- `--region-code `: Default region code, for example `aws-us-east-1` or `aws-ap-southeast-1`. +- `--tdc-private-key `: TiDB Cloud API private key. +- `--tdc-public-key `: TiDB Cloud API public key. +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Configure tdc interactively + +```bash tdc configure -TDC_PRIVATE_KEY="" tdc configure --profile ci --non-interactive --region-code aws-us-east-1 --tdc-public-key "" +``` + +### Configure tdc for automation + +```bash +TDC_REGION_CODE="aws-us-east-1" \ +TDC_PUBLIC_KEY="" \ +TDC_PRIVATE_KEY="" \ +tdc configure --profile ci --non-interactive ``` diff --git a/ai/tdc/reference/commands/tdc/tdc-update.md b/ai/tdc/reference/commands/tdc/tdc-update.md index a305bfdaac4e9..35017e040925f 100644 --- a/ai/tdc/reference/commands/tdc/tdc-update.md +++ b/ai/tdc/reference/commands/tdc/tdc-update.md @@ -14,25 +14,36 @@ Checks for or installs a tdc release update. This command does not read or modif ## Syntax ```text - tdc update - [--check] - [--dry-run] - [--fail-if-update-available] - [--help] - [--target-version ] - [--version] - [--debug] - [--output ] - [--profile ] - [--query ] - [--region ] +tdc update + [--check] + [--dry-run] + [--fail-if-update-available] + [--help] + [--target-version ] + [--version] ``` -For global flags such as `--profile`, `--region`, `--output`, and `--query`, see [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md). +## Options + +- `--check`: Check whether a newer tdc release is available without updating. +- `--dry-run`: Show the update plan without changing the local binary. +- `--fail-if-update-available`: With `--check`, exit with code 1 when an update is available. +- `--help`: Display help information. +- `--target-version `: Target tdc version, such as `latest` or `vX.Y.Z`. \[default: latest] +- `--version`: Display tdc version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -```shell +### Check for an update + +```bash tdc update --check -tdc update --target-version v0.1.4 +``` + +### Install a specific version + +```bash +tdc update --target-version ``` diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md index 71dca0df40f45..db97c0b3fa83f 100644 --- a/ai/tdc/reference/tdc-cli-reference.md +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -1,6 +1,6 @@ --- title: tdc CLI Reference -summary: Reference global flags, output and query behavior, dry-run rules, help forms, errors, command families, and Filesystem aliases. +summary: Reference global options, output and query behavior, dry-run rules, help forms, errors, command families, and Filesystem aliases. --- # tdc CLI Reference @@ -14,7 +14,7 @@ This reference describes behavior shared across the tdc command surface. ## Syntax ```text -tdc [subcommand] [required flags] [optional flags] [global flags] +tdc [subcommand] [required options] [optional options] [global options] ``` tdc accepts long flags only. A one-letter flag such as `-p` is rejected. @@ -97,7 +97,7 @@ tdc Every operation has a dedicated command page with syntax and examples. Expand **Command Reference** in the documentation navigation and select a command under `tdc`, `organization`, `db`, `fs`, `fs-git`, `fs-journal`, or `fs-vault`. -Required flags appear before optional flags in generated usage. Optional flags are enclosed in brackets: +Required options appear before optional options in generated usage. Optional options are enclosed in brackets: ```text tdc db describe-db-cluster @@ -106,24 +106,22 @@ tdc db describe-db-cluster [--view ] ``` -In the generated `Flags` and `Global Flags` sections, value types are enclosed in angle brackets and required flags include `(required)` after the flag name and type: +In command help, value types are enclosed in angle brackets and required options include `(required)` after the option name and type: ```text --db-cluster-name (required) Starter DB cluster display name --project-id TiDB Cloud project ID ``` -## Global flags +## Global options -| Flag | Description | -| --- | --- | -| `--profile ` | Select a local profile; defaults to `default` | -| `--region ` | Override canonical placement for this command | -| `--output ` | Render `json` or `text`; default is `json` | -| `--query ` | Apply a JMESPath expression before rendering | -| `--debug` | Print redacted debug diagnostics | -| `--help` | Display help | -| `--version` | Display tdc version information | +- `--debug`: Enable redacted debug output. +- `--output `: Set the output format to `json` or `text`. \[default: json] +- `--profile `: Select a local profile. \[default: default] +- `--query `: Apply a JMESPath expression before rendering the output. +- `--region `: Override the profile's canonical region code for the current command, for example, `aws-us-east-1`. + +Command pages document `--help`, `--version`, and all command-specific options separately. ## Output @@ -226,7 +224,7 @@ The following task-oriented guides explain how commands work together. They are | [Filesystem Journals](/ai/tdc/reference/tdc-filesystem-journal.md) | Manage verifiable journals | | [Filesystem Vault](/ai/tdc/reference/tdc-filesystem-vault.md) | Manage secrets and delegated access | -For complete commands and flags, run: +For complete commands and options, run: ```bash tdc help From e7e9fe70ee53e70d4b7f8335e7b6e254ae2eaea4 Mon Sep 17 00:00:00 2001 From: Cheese Date: Mon, 27 Jul 2026 21:29:27 +0800 Subject: [PATCH 17/29] docs: polish tdc command reference --- TOC-ai.md | 48 +++++++------- ai/_index.md | 22 +++---- .../db/tdc-db-create-db-cluster-branch.md | 26 +++++--- .../commands/db/tdc-db-create-db-cluster.md | 47 +++++++++++--- .../commands/db/tdc-db-create-db-sql-users.md | 30 +++++---- .../db/tdc-db-delete-db-cluster-branch.md | 19 +++--- .../commands/db/tdc-db-delete-db-cluster.md | 26 +++++--- .../db/tdc-db-describe-db-cluster-branch.md | 19 +++--- .../commands/db/tdc-db-describe-db-cluster.md | 19 +++--- .../db/tdc-db-execute-sql-statement.md | 40 +++++++++--- .../db/tdc-db-format-db-connection-string.md | 42 +++++++++---- .../db/tdc-db-list-db-cluster-branches.md | 19 +++--- .../commands/db/tdc-db-list-db-clusters.md | 26 +++++--- .../commands/db/tdc-db-update-db-cluster.md | 26 +++++--- .../fs-git/tdc-fs-git-add-git-worktree.md | 26 +++++--- .../fs-git/tdc-fs-git-clone-git-workspace.md | 33 +++++++--- .../tdc-fs-git-hydrate-git-workspace.md | 25 ++++---- .../fs-git/tdc-fs-git-remove-git-worktree.md | 21 +++---- .../tdc-fs-journal-append-journal-entries.md | 33 +++++++--- .../tdc-fs-journal-create-journal.md | 26 +++++--- .../tdc-fs-journal-read-journal-entries.md | 26 +++++--- .../tdc-fs-journal-search-journal-entries.md | 33 +++++++--- .../tdc-fs-journal-verify-journal.md | 19 +++--- .../fs-vault/tdc-fs-vault-create-grant.md | 26 +++++--- .../fs-vault/tdc-fs-vault-create-secret.md | 33 +++++++--- .../fs-vault/tdc-fs-vault-delete-grant.md | 21 +++---- .../fs-vault/tdc-fs-vault-delete-secret.md | 19 +++--- .../tdc-fs-vault-list-audit-events.md | 26 +++++--- .../fs-vault/tdc-fs-vault-list-secrets.md | 28 +++++---- .../fs-vault/tdc-fs-vault-mount-vault.md | 28 +++++---- .../fs-vault/tdc-fs-vault-read-secret.md | 35 +++++++---- .../fs-vault/tdc-fs-vault-replace-secret.md | 26 +++++--- .../fs-vault/tdc-fs-vault-run-with-secret.md | 28 +++++---- .../fs-vault/tdc-fs-vault-unmount-vault.md | 21 +++---- .../commands/fs/tdc-fs-check-file-system.md | 19 +++--- .../commands/fs/tdc-fs-chmod-file.md | 19 +++--- .../commands/fs/tdc-fs-commit-layer.md | 19 +++--- .../reference/commands/fs/tdc-fs-copy-file.md | 54 +++++++++++++--- .../commands/fs/tdc-fs-create-directory.md | 19 +++--- .../commands/fs/tdc-fs-create-file-system.md | 33 +++++++--- .../commands/fs/tdc-fs-create-hardlink.md | 19 +++--- .../fs/tdc-fs-create-layer-checkpoint.md | 26 +++++--- .../commands/fs/tdc-fs-create-layer.md | 26 +++++--- .../commands/fs/tdc-fs-create-symlink.md | 19 +++--- .../commands/fs/tdc-fs-delete-file-system.md | 26 +++++--- .../commands/fs/tdc-fs-delete-file.md | 26 +++++--- .../fs/tdc-fs-describe-file-system.md | 19 +++--- .../commands/fs/tdc-fs-describe-file.md | 19 +++--- .../commands/fs/tdc-fs-describe-layer.md | 19 +++--- .../commands/fs/tdc-fs-diff-layer.md | 26 +++++--- .../commands/fs/tdc-fs-drain-file-system.md | 19 +++--- .../commands/fs/tdc-fs-find-files.md | 26 +++++--- .../commands/fs/tdc-fs-list-file-systems.md | 19 +++--- .../commands/fs/tdc-fs-list-files.md | 19 +++--- .../commands/fs/tdc-fs-list-layers.md | 19 +++--- .../commands/fs/tdc-fs-mount-file-system.md | 40 +++++++++--- .../reference/commands/fs/tdc-fs-move-file.md | 19 +++--- .../commands/fs/tdc-fs-pack-file-system.md | 26 +++++--- .../reference/commands/fs/tdc-fs-read-file.md | 26 +++++--- .../commands/fs/tdc-fs-rollback-layer.md | 19 +++--- .../commands/fs/tdc-fs-search-file-content.md | 26 +++++--- .../commands/fs/tdc-fs-unmount-file-system.md | 19 +++--- .../commands/fs/tdc-fs-unpack-file-system.md | 26 +++++--- .../tdc-organization-list-projects.md | 26 +++++--- .../reference/commands/tdc/tdc-configure.md | 38 ++++++----- ai/tdc/reference/commands/tdc/tdc-update.md | 41 +++++++----- ai/tdc/reference/tdc-agent-sandbox-example.md | 14 ++--- .../tdc-ci-artifact-handoff-example.md | 16 ++--- ai/tdc/reference/tdc-cli-reference.md | 16 ++--- .../tdc-configuration-and-credentials.md | 24 +++---- .../reference/tdc-daily-workflow-example.md | 16 ++--- ai/tdc/reference/tdc-filesystem-git.md | 10 +-- ai/tdc/reference/tdc-filesystem-journal.md | 12 ++-- ai/tdc/reference/tdc-filesystem-vault.md | 12 ++-- ai/tdc/reference/tdc-filesystem.md | 22 +++---- .../tdc-git-workspace-for-agents-example.md | 12 ++-- .../reference/tdc-install-configure-update.md | 36 +++++------ .../tdc-journal-agent-workflow-example.md | 12 ++-- ai/tdc/reference/tdc-organization.md | 12 ++-- .../tdc-parallel-agent-dataset-example.md | 12 ++-- .../tdc-persistent-agent-state-example.md | 14 ++--- .../tdc-query-sql-with-roles-example.md | 14 ++--- .../tdc-regions-security-and-limitations.md | 34 +++++----- ...hare-filesystem-across-machines-example.md | 10 +-- ai/tdc/reference/tdc-starter-database.md | 18 +++--- ai/tdc/reference/tdc-troubleshooting.md | 22 +++---- .../tdc-vault-agent-secrets-example.md | 12 ++-- ai/tdc/tdc-overview.md | 63 +++++++++---------- ai/tdc/tdc-quick-start.md | 32 +++++----- 89 files changed, 1262 insertions(+), 921 deletions(-) diff --git a/TOC-ai.md b/TOC-ai.md index f720cb8ffe740..9facffc93f500 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -7,7 +7,7 @@ - [Get Started with Vector Search via Python](/ai/quickstart-via-python.md) - [Get Started with Vector Search via SQL](/ai/quickstart-via-sql.md) -- [Get Started with TiDB Cloud CLI (tdc)](/ai/tdc/tdc-quick-start.md) +- [Get Started with TiDB Cloud CLI](/ai/tdc/tdc-quick-start.md) ## CONCEPTS @@ -84,18 +84,18 @@ - [Vector Search Index](/ai/reference/vector-search-index.md) - [Vector Search Performance Tuning](/ai/reference/vector-search-improve-performance.md) - [Vector Search Limitations](/ai/reference/vector-search-limitations.md) -- TiDB Cloud CLI (tdc) - - [Overview](/ai/tdc/tdc-overview.md) +- TiDB Cloud CLI + - [TiDB Cloud Command Line Interface Overview](/ai/tdc/tdc-overview.md) - Guides - - [Install, Configure, and Update](/ai/tdc/reference/tdc-install-configure-update.md) - - [Organization and Projects](/ai/tdc/reference/tdc-organization.md) - - [Starter Databases and SQL](/ai/tdc/reference/tdc-starter-database.md) - - [Filesystem](/ai/tdc/reference/tdc-filesystem.md) - - [Filesystem Git Workspaces](/ai/tdc/reference/tdc-filesystem-git.md) - - [Filesystem Journals](/ai/tdc/reference/tdc-filesystem-journal.md) - - [Filesystem Vault](/ai/tdc/reference/tdc-filesystem-vault.md) + - [Install, Configure, and Update TiDB Cloud CLI](/ai/tdc/reference/tdc-install-configure-update.md) + - [TiDB Cloud Organization CLI Command Reference](/ai/tdc/reference/tdc-organization.md) + - [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) + - [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) + - [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) + - [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) + - [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) - Command Reference - - [CLI Syntax and Global Behavior](/ai/tdc/reference/tdc-cli-reference.md) + - [TiDB Cloud CLI Command Reference](/ai/tdc/reference/tdc-cli-reference.md) - [configure](/ai/tdc/reference/commands/tdc/tdc-configure.md) - [update](/ai/tdc/reference/commands/tdc/tdc-update.md) - organization @@ -167,17 +167,17 @@ - [mount-vault](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md) - [unmount-vault](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md) - Scenarios for Users and Automation - - [Automate Daily Database Operations](/ai/tdc/reference/tdc-daily-workflow-example.md) - - [Run SQL Queries with Role-Based Access](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) - - [Share a Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) - - [Hand Off CI Artifacts Between Jobs](/ai/tdc/reference/tdc-ci-artifact-handoff-example.md) + - [Run a Daily TiDB Cloud CLI Workflow](/ai/tdc/reference/tdc-daily-workflow-example.md) + - [Query TiDB Cloud Starter with Explicit SQL Roles](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) + - [Share a TiDB Cloud Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) + - [Hand Off CI Artifacts Between Isolated Jobs with TiDB Cloud Filesystem](/ai/tdc/reference/tdc-ci-artifact-handoff-example.md) - Scenarios for AI Agents - - [Set Up an Agent Sandbox Environment](/ai/tdc/reference/tdc-agent-sandbox-example.md) - - [Persist Agent State Across Sandboxes](/ai/tdc/reference/tdc-persistent-agent-state-example.md) - - [Share a Read-Only Dataset Across Parallel Agents](/ai/tdc/reference/tdc-parallel-agent-dataset-example.md) - - [Set Up a Git Workspace for AI Agents](/ai/tdc/reference/tdc-git-workspace-for-agents-example.md) - - [Record Agent Workflows in a Journal](/ai/tdc/reference/tdc-journal-agent-workflow-example.md) - - [Delegate Secrets Securely to Agents](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) - - [Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) - - [Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) - - [Troubleshooting](/ai/tdc/reference/tdc-troubleshooting.md) + - [Use TiDB Cloud Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) + - [Persist Agent State Across Disposable Sandboxes with TiDB Cloud Filesystem](/ai/tdc/reference/tdc-persistent-agent-state-example.md) + - [Share a Read-Only Dataset Across Parallel Agents with TiDB Cloud Filesystem](/ai/tdc/reference/tdc-parallel-agent-dataset-example.md) + - [Prepare a Git Workspace for Agents on TiDB Cloud Filesystem](/ai/tdc/reference/tdc-git-workspace-for-agents-example.md) + - [Record an Agent Workflow in a TiDB Cloud Filesystem Journal](/ai/tdc/reference/tdc-journal-agent-workflow-example.md) + - [Delegate TiDB Cloud Filesystem Vault Secrets to an Agent](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) + - [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) + - [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) + - [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/_index.md b/ai/_index.md index 83b962a76b979..c334a8369d6cd 100644 --- a/ai/_index.md +++ b/ai/_index.md @@ -16,12 +16,12 @@ Get up and running quickly with TiDB's AI capabilities. | [Get Started with Python](/ai/quickstart-via-python.md) | Build your first AI application with TiDB in minutes using Python. | | [Get Started with SQL](/ai/quickstart-via-sql.md) | Quick start guide for vector search using SQL. | -### TiDB Cloud CLI (tdc) (Preview) +### TiDB Cloud CLI (Preview) | Document | Description | | --- | --- | -| [tdc Overview](/ai/tdc/tdc-overview.md) | Learn when to use tdc, how it differs from the legacy ticloud CLI and TiDB Cloud console, and which Starter and Filesystem workflows it supports. | -| [Get Started with tdc](/ai/tdc/tdc-quick-start.md) | Install and configure tdc, then complete a first database or Filesystem operation. | +| [TiDB Cloud Command Line Interface Overview](/ai/tdc/tdc-overview.md) | Learn when to use the TiDB Cloud CLI, how it differs from the `ticloud` CLI and TiDB Cloud console, and which Starter and Filesystem workflows it supports. | +| [Get Started with TiDB Cloud CLI](/ai/tdc/tdc-quick-start.md) | Install and configure the TiDB Cloud CLI, then complete a first database or Filesystem operation. | ## Concepts @@ -83,16 +83,16 @@ Technical reference documentation for TiDB's AI and vector search features. | [Performance Tuning](/ai/reference/vector-search-improve-performance.md) | Optimize vector search performance. | | [Limitations](/ai/reference/vector-search-limitations.md) | Current limitations and constraints. | -### TiDB Cloud CLI (tdc) (Preview) +### TiDB Cloud CLI (Preview) -The command reference follows the two-level tdc command tree. Every command has a dedicated page with its syntax and examples. Expand **Command Reference** in the documentation navigation to browse commands by family. +The command reference follows the two-level `tdc` command tree. Every command has a dedicated page with its syntax and examples. Expand **Command Reference** in the documentation navigation to browse commands by family. #### Command reference | Document | Description | | --- | --- | -| [tdc Overview](/ai/tdc/tdc-overview.md) | Decide when to use tdc and understand its scope relative to ticloud and the TiDB Cloud console. | -| [CLI Syntax and Global Behavior](/ai/tdc/reference/tdc-cli-reference.md) | Command tree, global flags, output, queries, dry-run, help, errors, aliases, and links to command pages. | +| [TiDB Cloud Command Line Interface Overview](/ai/tdc/tdc-overview.md) | Decide when to use the TiDB Cloud CLI and understand its scope relative to `ticloud` and the TiDB Cloud console. | +| [TiDB Cloud CLI Command Reference](/ai/tdc/reference/tdc-cli-reference.md) | Command tree, global flags, output, queries, dry-run, help, errors, aliases, and links to command pages. | | [`tdc configure`](/ai/tdc/reference/commands/tdc/tdc-configure.md) | Configure a local profile interactively or non-interactively. | | [`tdc update`](/ai/tdc/reference/commands/tdc/tdc-update.md) | Check for and install release updates. | | [`tdc organization list-projects`](/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md) | List accessible TiDB Cloud projects. | @@ -101,9 +101,9 @@ The command reference follows the two-level tdc command tree. Every command has | [`tdc fs-git clone-git-workspace`](/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md) | Start with the Filesystem Git command reference. | | [`tdc fs-journal create-journal`](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md) | Start with the Filesystem journal command reference. | | [`tdc fs-vault create-secret`](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md) | Start with the Filesystem Vault command reference. | -| [Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) | Profiles, precedence, local state, credentials, mount locators, and logs. | -| [Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) | Placement, authentication boundaries, platforms, durability, and Preview constraints. | -| [Troubleshooting](/ai/tdc/reference/tdc-troubleshooting.md) | Diagnose authentication, quota, SQL, companion, selection, and mount failures. | +| [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) | Profiles, precedence, local state, credentials, mount locators, and logs. | +| [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) | Placement, authentication boundaries, platforms, durability, and preview constraints. | +| [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) | Diagnose authentication, quota, SQL, companion, selection, and mount failures. | #### Scenarios for users and automation @@ -112,7 +112,7 @@ The command reference follows the two-level tdc command tree. Every command has | [Daily Workflow](/ai/tdc/reference/tdc-daily-workflow-example.md) | Manage one Starter cluster and Filesystem in a routine operator flow. | | [Query SQL with Roles](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) | Use explicit read-only, read-write, and admin SQL roles. | | [Share a Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) | Transfer an owner token securely and verify cross-machine visibility. | -| [Hand Off CI Artifacts Between Jobs](/ai/tdc/reference/tdc-ci-artifact-handoff-example.md) | Persist build output across isolated jobs without copying a complete tdc profile. | +| [Hand Off CI Artifacts Between Jobs](/ai/tdc/reference/tdc-ci-artifact-handoff-example.md) | Persist build output across isolated jobs without copying a complete TiDB Cloud CLI profile. | #### Scenarios for AI agents diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md index 64a38dee93129..f9818bc5758a3 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md @@ -9,7 +9,7 @@ Creates a branch for one Starter cluster. `--wait` waits for the branch to becom > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -29,21 +29,27 @@ tdc db create-db-cluster-branch - `--db-cluster-id `: Starter DB cluster ID. \[required] - `--dry-run`: Validate the request without applying changes. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. - `--wait`: Wait until the created branch becomes `ACTIVE` before returning. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create a branch and wait until it is active +- Create a branch and wait until it is active: -```bash -tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name dev --wait -``` + ```bash + # Wait until the new database branch can accept connections. + tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name dev --wait + ``` -### Preview branch creation +- Preview branch creation: -```bash -tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name preview --dry-run -``` + ```bash + # Validate the parent cluster and branch request without creating it. + tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name preview --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md index fd01feaa356a8..a875b2cdf4d59 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md @@ -9,7 +9,7 @@ Creates a Starter cluster. `--db-cluster-type` defaults to `starter`, and `--wai > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -33,21 +33,48 @@ tdc db create-db-cluster - `--help`: Display help information. - `--monthly-spending-limit-usd-cents `: Monthly spending limit in USD cents; omit to use the API default. - `--project-id `: TiDB Cloud project ID. -- `--version`: Display tdc version information. +- `--version`: Display version information. - `--wait`: Wait until the created cluster becomes `ACTIVE` before returning. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create a cluster and wait until it is active +- Create a cluster and wait until it is active: -```bash -tdc db create-db-cluster --db-cluster-name app-db --wait -``` + ```bash + # Wait until the new Starter cluster reaches the ACTIVE state. + tdc db create-db-cluster --db-cluster-name app-db --wait + ``` -### Preview cluster creation +- Create a cluster asynchronously: -```bash -tdc db create-db-cluster --db-cluster-name app-db --dry-run -``` + ```bash + # Return after TiDB Cloud accepts creation so another process can poll the cluster. + tdc db create-db-cluster --db-cluster-name background-db + ``` + +- Preview cluster creation: + + ```bash + # Validate the request and resolved defaults without creating a cluster. + tdc db create-db-cluster --db-cluster-name app-db --dry-run + ``` + +- Create a cluster in an explicit project: + + ```bash + # Override the configured virtual project for this cluster. + tdc db create-db-cluster --db-cluster-name project-db --project-id "" --wait + ``` + +- Set a monthly spending limit: + + ```bash + # Create a paid Starter cluster with a monthly limit expressed in US dollar cents. + tdc db create-db-cluster --db-cluster-name production-db --monthly-spending-limit-usd-cents 1000 --wait + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md b/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md index 73f26288dfe7b..c8ab8b983950e 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md @@ -1,15 +1,15 @@ --- title: tdc db create-db-sql-users -summary: Create tdc-managed SQL users for a Starter cluster. +summary: Create TiDB Cloud CLI-managed SQL users for a Starter cluster. --- # tdc db create-db-sql-users -Idempotently creates or repairs the read-only, read-write, and admin SQL users managed by tdc. +Idempotently creates or repairs the read-only, read-write, and admin SQL users managed by `tdc`. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -26,20 +26,26 @@ tdc db create-db-sql-users - `--db-cluster-id `: Starter DB cluster ID. \[required] - `--dry-run`: Validate the request without applying changes. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Preview SQL user creation +- Create the managed SQL users: -```bash -tdc db create-db-sql-users --db-cluster-id "" --dry-run -``` + ```bash + # Create or reconcile the read-only, read-write, and admin SQL users. + tdc db create-db-sql-users --db-cluster-id "" + ``` -### Create read-only, read-write, and admin SQL users +- Preview SQL user creation: -```bash -tdc db create-db-sql-users --db-cluster-id "" -``` + ```bash + # Show the three managed roles without changing SQL users or local credentials. + tdc db create-db-sql-users --db-cluster-id "" --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md index a1db8a5627dd6..8168b376faa03 100644 --- a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md +++ b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md @@ -9,7 +9,7 @@ Deletes one branch from a Starter cluster. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -28,20 +28,19 @@ tdc db delete-db-cluster-branch - `--db-cluster-id `: Starter DB cluster ID. \[required] - `--dry-run`: Validate the request without applying changes. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Preview branch deletion +- Delete a branch: -```bash -tdc db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" --dry-run -``` + ```bash + # Delete only the selected branch from its parent Starter cluster. + tdc db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" + ``` -### Delete a branch +## Related documentation -```bash -tdc db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" -``` +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md index d9bff4f86d5af..ea5a9a24f2f38 100644 --- a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md @@ -9,7 +9,7 @@ Deletes one Starter cluster. `--wait` waits until deletion is observable. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -27,21 +27,27 @@ tdc db delete-db-cluster - `--db-cluster-id `: Starter DB cluster ID. \[required] - `--dry-run`: Validate the request without applying changes. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. - `--wait`: Wait until the deleted cluster reaches `DELETED` or is no longer accessible. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Preview cluster deletion +- Delete a cluster and wait for completion: -```bash -tdc db delete-db-cluster --db-cluster-id "" --dry-run -``` + ```bash + # Wait until TiDB Cloud reports the cluster deleted or no longer accessible. + tdc db delete-db-cluster --db-cluster-id "" --wait + ``` -### Delete a cluster and wait for completion +- Delete a cluster asynchronously: -```bash -tdc db delete-db-cluster --db-cluster-id "" --wait -``` + ```bash + # Return after TiDB Cloud accepts deletion while cleanup continues remotely. + tdc db delete-db-cluster --db-cluster-id "" + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md index e8797367afc66..2b238b67d4645 100644 --- a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md +++ b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md @@ -9,7 +9,7 @@ Describes one branch by cluster ID and branch ID. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -27,21 +27,20 @@ tdc db describe-db-cluster-branch - `--db-cluster-branch-id `: Starter DB cluster branch ID. \[required] - `--db-cluster-id `: Starter DB cluster ID. \[required] - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. - `--view `: Detail level: `BASIC` or `FULL`. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Describe a branch +- Describe a branch: -```bash -tdc db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" -``` + ```bash + # Return full lifecycle and connection details for one branch. + tdc db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" --view FULL + ``` -### Show full branch details +## Related documentation -```bash -tdc db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" --view FULL -``` +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md index 75c7a3e8a2628..3cd01b8244c91 100644 --- a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md @@ -9,7 +9,7 @@ Describes one Starter cluster. Use `--view FULL` to request expanded fields. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -25,21 +25,20 @@ tdc db describe-db-cluster - `--db-cluster-id `: Starter DB cluster ID. \[required] - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. - `--view `: Detail level: `BASIC` or `FULL`. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Describe a cluster +- Describe a cluster: -```bash -tdc db describe-db-cluster --db-cluster-id "" -``` + ```bash + # Return the cluster state, placement, and connection metadata. + tdc db describe-db-cluster --db-cluster-id "" --view FULL + ``` -### Show full cluster details +## Related documentation -```bash -tdc db describe-db-cluster --db-cluster-id "" --view FULL -``` +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md b/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md index 76bcc82620691..15520e9ec7c16 100644 --- a/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md +++ b/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md @@ -9,7 +9,7 @@ Executes exactly one SQL statement. Read-write is the default role; explicit rol > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -36,20 +36,40 @@ tdc db execute-sql-statement - `--read-only`: Use prepared `read_only` DB SQL credentials. - `--read-write`: Use prepared `read_write` DB SQL credentials. - `--transport `: SQL execution transport: `https` or `mysql`. \[default: https] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Run a read-only query +- Run a statement with the default read-write role: -```bash -tdc db execute-sql-statement --db-cluster-id "" --read-only --sql "SELECT 1" --output text -``` + ```bash + # Use the default prepared role for normal application reads and writes. + tdc db execute-sql-statement --db-cluster-id "" --sql "INSERT INTO app.events(message) VALUES ('ready')" + ``` -### Run an administrative statement +- Run a read-only query: -```bash -tdc db execute-sql-statement --db-cluster-id "" --admin --sql "CREATE DATABASE IF NOT EXISTS app" -``` + ```bash + # Prevent the statement from using read-write or admin credentials. + tdc db execute-sql-statement --db-cluster-id "" --read-only --sql "SELECT 1 AS ready" --output text + ``` + +- Run an administrative statement: + + ```bash + # Use the admin role for schema creation or privilege management. + tdc db execute-sql-statement --db-cluster-id "" --admin --sql "CREATE DATABASE IF NOT EXISTS app" + ``` + +- Use the MySQL fallback transport: + + ```bash + # Open a one-shot MySQL connection when the HTTPS SQL API is unsuitable. + tdc db execute-sql-statement --db-cluster-id "" --transport mysql --sql "SELECT CURRENT_TIMESTAMP" + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md b/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md index da88705ebc356..24702c1bdbe49 100644 --- a/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md +++ b/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md @@ -1,6 +1,6 @@ --- title: tdc db format-db-connection-string -summary: Format a connection string for a tdc-managed SQL user. +summary: Format a connection string for a TiDB Cloud CLI-managed SQL user. --- # tdc db format-db-connection-string @@ -9,7 +9,7 @@ Formats stored SQL credentials for read-write, read-only, or admin access. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -40,20 +40,40 @@ tdc db format-db-connection-string - `--help`: Display help information. - `--read-only`: Use prepared `read_only` DB SQL credentials. - `--read-write`: Use prepared `read_write` DB SQL credentials. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Format a read-write MySQL URI +- Format a read-write MySQL URI: -```bash -tdc db format-db-connection-string --db-cluster-id "" --read-write --format mysql-uri -``` + ```bash + # Use the default application role in tools that accept a MySQL URI. + tdc db format-db-connection-string --db-cluster-id "" --read-write --format mysql-uri + ``` -### Format read-only dotenv variables +- Format read-only dotenv variables: -```bash -tdc db format-db-connection-string --db-cluster-id "" --read-only --format env --env-prefix TIDB_ -``` + ```bash + # Emit environment assignments for a workload that must not modify data. + tdc db format-db-connection-string --db-cluster-id "" --read-only --format env --env-prefix TIDB_ + ``` + +- Format an admin JDBC URL: + + ```bash + # Generate a JDBC connection value with the prepared admin credentials. + tdc db format-db-connection-string --db-cluster-id "" --admin --format jdbc --database app + ``` + +- Include DATABASE_URL in dotenv output: + + ```bash + # Emit both component variables and a conventional DATABASE_URL value. + tdc db format-db-connection-string --db-cluster-id "" --format env --env-include-database-url + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md b/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md index e841e23a5863b..fa3f5af52b22a 100644 --- a/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md +++ b/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md @@ -9,7 +9,7 @@ Lists branches for one Starter cluster, with optional pagination. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -28,20 +28,19 @@ tdc db list-db-cluster-branches - `--help`: Display help information. - `--page-size `: Number of branches to request; 0 uses the API default. - `--page-token `: Page token returned by a previous list-db-cluster-branches call. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### List branches as text +- List cluster branches: -```bash -tdc db list-db-cluster-branches --db-cluster-id "" --output text -``` + ```bash + # Return all branches that belong to the selected Starter cluster. + tdc db list-db-cluster-branches --db-cluster-id "" + ``` -### Return branch IDs +## Related documentation -```bash -tdc db list-db-cluster-branches --db-cluster-id "" --query 'branches[].id' -``` +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md index 81dd1d745dee1..6cc46e8c62c81 100644 --- a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md +++ b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md @@ -9,7 +9,7 @@ Lists Starter clusters with optional pagination, filtering, ordering, and JMESPa > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -32,20 +32,26 @@ tdc db list-db-clusters - `--page-size `: Number of clusters to request; 0 uses the API default. - `--page-token `: Page token returned by a previous list-db-clusters call. - `--skip `: Number of clusters to skip. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### List clusters as text +- List clusters: -```bash -tdc db list-db-clusters --output text -``` + ```bash + # Return all visible Starter clusters as structured JSON. + tdc db list-db-clusters + ``` -### Return selected cluster fields +- Select cluster fields: -```bash -tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name,state:state}' -``` + ```bash + # Reduce the result to IDs, names, and lifecycle states. + tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name,state:state}' + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md index 79cef640933db..c12fa5180c69a 100644 --- a/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md @@ -9,7 +9,7 @@ Updates the display name or monthly spending limit of one Starter cluster. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -30,20 +30,26 @@ tdc db update-db-cluster - `--dry-run`: Validate the request without applying changes. - `--help`: Display help information. - `--monthly-spending-limit-usd-cents `: Monthly spending limit in USD cents; omit to leave unchanged. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Rename a cluster +- Rename a cluster: -```bash -tdc db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2 -``` + ```bash + # Change the Starter cluster display name without recreating it. + tdc db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2 + ``` -### Preview a spending-limit update +- Preview a spending-limit update: -```bash -tdc db update-db-cluster --db-cluster-id "" --monthly-spending-limit-usd-cents 1000 --dry-run -``` + ```bash + # Validate a new monthly limit without applying the change. + tdc db update-db-cluster --db-cluster-id "" --monthly-spending-limit-usd-cents 1000 --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md index 02888f2c5f60e..c11706a3f1b5a 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md @@ -9,7 +9,7 @@ Adds a linked Git worktree from a base workspace. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -42,20 +42,26 @@ tdc fs-git add-git-worktree - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--hydrate `: Blobless hydrate mode: `auto`, `background`, `sync`, or `off`. \[default: auto] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create a worktree on a new branch +- Create a worktree on a new branch: -```bash -tdc fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-feature --branch-name feature-x -``` + ```bash + # Give an agent an isolated branch while sharing the base Git object store. + tdc fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-feature --branch-name feature-x + ``` -### Create a detached worktree +- Create a detached worktree: -```bash -tdc fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-review --commit-ish origin/main --detach -``` + ```bash + # Inspect a commit without creating or switching a branch. + tdc fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-review --commit-ish origin/main --detach + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md index 06897e9075894..1700d1d7a96b9 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md @@ -9,7 +9,7 @@ Clones a repository into a mounted Filesystem path. Hydration can run synchronou > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -36,20 +36,33 @@ tdc fs-git clone-git-workspace - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--hydrate `: Blobless hydrate mode: `auto`, `background`, `sync`, or `off`. \[default: auto] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Clone a repository +- Clone a repository normally: -```bash -tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb -``` + ```bash + # Create a complete Git checkout in the mounted Filesystem path. + tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb + ``` -### Clone a blobless repository and hydrate in the background +- Start a blobless workspace immediately: -```bash -tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate background -``` + ```bash + # Expose the repository tree while clean Git objects hydrate in the background. + tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate background + ``` + +- Wait for blobless hydration: + + ```bash + # Keep the clone command running until clean Git objects finish hydrating. + tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate sync + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md index ed9a79ea948d0..53299166bcb11 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md @@ -1,15 +1,15 @@ --- title: tdc fs-git hydrate-git-workspace -summary: Hydrate clean Git objects in a tdc Git workspace. +summary: Hydrate clean Git objects in a Filesystem Git workspace. --- # tdc fs-git hydrate-git-workspace -Hydrates clean Git objects for an existing tdc Git workspace. +Hydrates clean Git objects for an existing `tdc` Git workspace. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -25,25 +25,24 @@ tdc fs-git hydrate-git-workspace ## Options -- `--target-path `: Mounted tdc fs workspace path. \[required] +- `--target-path `: Mounted `tdc fs` workspace path. \[required] - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--timeout `: Maximum hydrate duration. \[default: `30m0s`] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Hydrate a Git workspace +- Finish hydrating a Git workspace: -```bash -tdc fs-git hydrate-git-workspace --file-system-name workspace --target-path /path/to/workspace/tidb -``` + ```bash + # Download missing clean Git objects for an existing blobless workspace. + tdc fs-git hydrate-git-workspace --file-system-name workspace --target-path /path/to/workspace/tidb --timeout 30m + ``` -### Hydrate with an explicit timeout +## Related documentation -```bash -tdc fs-git hydrate-git-workspace --file-system-name workspace --target-path /path/to/workspace/tidb --timeout 30m -``` +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md index deee7092dbef9..2a4e83c0eb141 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md @@ -9,7 +9,7 @@ Removes a linked worktree without recursively deleting shared clean-tree data. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -26,26 +26,25 @@ tdc fs-git remove-git-worktree ## Options -- `--worktree-path `: Mounted tdc fs path of the linked worktree. \[required] +- `--worktree-path `: Mounted `tdc fs` path of the linked worktree. \[required] - `--dry-run`: Validate the request without applying changes. - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--force`: Remove even when the linked worktree has local changes. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Preview worktree removal +- Remove a Git worktree: -```bash -tdc fs-git remove-git-worktree --file-system-name workspace --worktree-path /path/to/workspace/tidb-feature --dry-run -``` + ```bash + # Force removal when the isolated worktree still contains local changes. + tdc fs-git remove-git-worktree --file-system-name workspace --worktree-path /path/to/workspace/tidb-feature --force + ``` -### Force worktree removal +## Related documentation -```bash -tdc fs-git remove-git-worktree --file-system-name workspace --worktree-path /path/to/workspace/tidb-feature --force -``` +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md index b0ff45bb0e941..9b57cee986053 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md @@ -9,7 +9,7 @@ Appends one JSON event or a JSON array to a journal. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -42,20 +42,33 @@ tdc fs-journal append-journal-entries - `--json-array`: Read a JSON array from stdin instead of JSONL. - `--source `: Entry source. - `--subject `: Entry subject; repeatable. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Append a JSON journal entry +- Append one JSON entry: -```bash -tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-json '{"type":"task.started"}' -``` + ```bash + # Record an event object exactly as supplied on the command line. + tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-json '{"type":"task.started"}' + ``` -### Append a typed idempotent entry +- Append an idempotent typed entry: -```bash -tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-type task.completed --subject issue-42 --idempotency-key issue-42-complete -``` + ```bash + # Prevent retries from recording the same completion event twice. + tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-type task.completed --subject issue-42 --idempotency-key issue-42-complete + ``` + +- Append a JSON array from standard input: + + ```bash + # Batch multiple ordered events in a single append operation. + printf '[{"type":"step.started"},{"type":"step.completed"}]' | tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --json-array + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md index 534587ae68083..d6f9f1302e433 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md @@ -9,7 +9,7 @@ Creates a journal. If `--journal-id` is omitted, the service generates one. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -38,20 +38,26 @@ tdc fs-journal create-journal - `--journal-kind `: Journal kind. \[default: agent] - `--label `: Journal label `key=value`; repeatable. - `--title `: Journal title. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create an agent journal +- Create an agent journal: -```bash -tdc fs-journal create-journal --file-system-name workspace --journal-id jrn-demo --journal-kind agent --title "demo task" -``` + ```bash + # Create an append-only journal for one agent task. + tdc fs-journal create-journal --file-system-name workspace --journal-id jrn-demo --journal-kind agent --title "demo task" + ``` -### Preview creation of a labeled deployment journal +- Create a labeled deployment journal: -```bash -tdc fs-journal create-journal --file-system-name workspace --journal-kind deployment --actor agent:tdc --label env=dev --dry-run -``` + ```bash + # Attach actor and environment metadata for later searches. + tdc fs-journal create-journal --file-system-name workspace --journal-kind deployment --actor agent:tdc --label env=dev + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md index 0892d40712fb3..6bf6d26229332 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md @@ -9,7 +9,7 @@ Reads entries from one journal in sequence order. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -32,20 +32,26 @@ tdc fs-journal read-journal-entries - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--limit `: Maximum entries to read. \[default: 100] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Read journal entries +- Read journal entries: -```bash -tdc fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo -``` + ```bash + # Return the first page of ordered entries for a journal. + tdc fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo + ``` -### Read a page after a sequence number +- Continue after a sequence number: -```bash -tdc fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo --after-seq 100 --limit 50 -``` + ```bash + # Read the next page after the last sequence processed by a consumer. + tdc fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo --after-seq 100 --limit 50 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md index d7e7201e4556c..d07cef283431e 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md @@ -9,7 +9,7 @@ Searches journals and optionally returns matching entries. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -48,20 +48,33 @@ tdc fs-journal search-journal-entries - `--status `: Entry status filter. - `--subject `: Subject filter; repeatable. - `--until `: RFC3339 upper time bound. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Search by entry type +- Search by entry type: -```bash -tdc fs-journal search-journal-entries --file-system-name workspace --entry-type task.started --include-entries -``` + ```bash + # Find journals containing task-start events and include their payloads. + tdc fs-journal search-journal-entries --file-system-name workspace --entry-type task.started --include-entries + ``` -### Search recent entries by label +- Search by label and time: -```bash -tdc fs-journal search-journal-entries --file-system-name workspace --label env=dev --since 2026-07-01T00:00:00Z --limit 100 -``` + ```bash + # Limit deployment journal matches to one environment and time window. + tdc fs-journal search-journal-entries --file-system-name workspace --label env=dev --since 2026-07-01T00:00:00Z --limit 100 + ``` + +- Search by actor and subject: + + ```bash + # Find events produced by one agent for a specific task subject. + tdc fs-journal search-journal-entries --file-system-name workspace --actor agent:tdc --subject issue-42 --include-entries + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md index 564aba725032f..5ee9b41519449 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md @@ -9,7 +9,7 @@ Verifies the integrity of one journal hash chain. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -28,20 +28,19 @@ tdc fs-journal verify-journal - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Verify a journal +- Verify a journal: -```bash -tdc fs-journal verify-journal --file-system-name workspace --journal-id jrn-demo -``` + ```bash + # Validate the journal's ordered hash chain and integrity metadata. + tdc fs-journal verify-journal --file-system-name workspace --journal-id jrn-demo + ``` -### Render verification results as text +## Related documentation -```bash -tdc fs-journal verify-journal --file-system-name workspace --journal-id jrn-demo --output text -``` +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md index c29a1dccdb972..35fdacea52aff 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md @@ -9,7 +9,7 @@ Creates a time-limited delegated grant for one agent and scope. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -40,20 +40,26 @@ tdc fs-vault create-grant - `--help`: Display help information. - `--label-hint `: Optional grant label hint. - `--token-only`: Print only the delegated bearer token. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create a read grant +- Create a temporary read grant: -```bash -tdc fs-vault create-grant --file-system-name workspace --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m -``` + ```bash + # Limit an agent to one secret field for ten minutes. + tdc fs-vault create-grant --file-system-name workspace --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m + ``` -### Create a token-only grant for CI +- Return only the delegated token: -```bash -tdc fs-vault create-grant --file-system-name workspace --agent-id ci-agent --scope api-dev/TOKEN --permission read --ttl 5m --token-only -``` + ```bash + # Produce token-only output for injection into an isolated CI job. + tdc fs-vault create-grant --file-system-name workspace --agent-id ci-agent --scope api-dev/TOKEN --permission read --ttl 5m --token-only + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md index a4e45818581ee..d952eff72f9ed 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md @@ -9,7 +9,7 @@ Creates a secret from one or more `NAME=value` or `NAME=@file` fields. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -32,20 +32,33 @@ tdc fs-vault create-secret - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create a secret from values and a file +- Create a secret from values and a file: -```bash -tdc fs-vault create-secret --file-system-name workspace --secret-name db-prod --field DB_URL=mysql://example --field PASSWORD=@./password.txt -``` + ```bash + # Keep the password out of the command line by reading it from a local file. + tdc fs-vault create-secret --file-system-name workspace --secret-name db-prod --field DB_URL=mysql://example --field PASSWORD=@./password.txt + ``` -### Preview secret creation +- Read a secret field from standard input: -```bash -tdc fs-vault create-secret --file-system-name workspace --secret-name api-dev --field TOKEN=@./token.txt --dry-run -``` + ```bash + # Supply a sensitive token through a pipe instead of a process argument. + printf '%s' "$API_TOKEN" | tdc fs-vault create-secret --file-system-name workspace --secret-name api-dev --field TOKEN=- + ``` + +- Preview secret creation: + + ```bash + # Validate field assignments without storing secret material. + tdc fs-vault create-secret --file-system-name workspace --secret-name api-dev --field TOKEN=@./token.txt --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md index 9b7469151d339..9ac3163cf99ff 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md @@ -9,7 +9,7 @@ Revokes one delegated Filesystem Vault grant. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -33,21 +33,20 @@ tdc fs-vault delete-grant - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--reason `: Optional revoke reason. -- `--revoked-by `: Actor label for the revoke audit entry. \[default: tdc] -- `--version`: Display tdc version information. +- `--revoked-by `: Actor label for the revoke audit entry. \[default: `tdc`] +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Revoke a grant with a reason +- Revoke a grant: -```bash -tdc fs-vault delete-grant --file-system-name workspace --grant-id "" --reason rotated -``` + ```bash + # Invalidate the delegated token and record the revocation reason. + tdc fs-vault delete-grant --file-system-name workspace --grant-id "" --reason rotated + ``` -### Preview grant revocation +## Related documentation -```bash -tdc fs-vault delete-grant --file-system-name workspace --grant-id "" --revoked-by operator --dry-run -``` +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md index a099b879a80ae..af816d9a85c27 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md @@ -9,7 +9,7 @@ Deletes one Filesystem Vault secret. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -30,20 +30,19 @@ tdc fs-vault delete-secret - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Preview secret deletion +- Delete a secret: -```bash -tdc fs-vault delete-secret --file-system-name workspace --secret-name db-prod --dry-run -``` + ```bash + # Remove the selected secret and its fields from the Vault. + tdc fs-vault delete-secret --file-system-name workspace --secret-name db-prod + ``` -### Delete a secret +## Related documentation -```bash -tdc fs-vault delete-secret --file-system-name workspace --secret-name db-prod -``` +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md index dafe06406f548..22d58df25248a 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md @@ -9,7 +9,7 @@ Lists vault audit events with optional agent, secret, and time filters. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -34,20 +34,26 @@ tdc fs-vault list-audit-events - `--limit `: Maximum events to return. \[default: 100] - `--secret-name `: Filter by Vault secret name. - `--since `: Client-side relative time filter, for example, `24h`. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### List audit events for a secret +- List events for one secret: -```bash -tdc fs-vault list-audit-events --file-system-name workspace --secret-name db-prod --limit 20 -``` + ```bash + # Inspect recent access and mutation events for the selected secret. + tdc fs-vault list-audit-events --file-system-name workspace --secret-name db-prod --limit 20 + ``` -### List recent events for an agent +- List recent events for an agent: -```bash -tdc fs-vault list-audit-events --file-system-name workspace --agent-id deploy-agent --since 24h --output text -``` + ```bash + # Filter the audit trail to one delegated identity and time range. + tdc fs-vault list-audit-events --file-system-name workspace --agent-id deploy-agent --since 24h + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md index 4d6dc47f52f44..46ac7381cc82f 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md @@ -9,7 +9,7 @@ Lists secrets visible to the active owner or delegated credential. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -27,21 +27,27 @@ tdc fs-vault list-secrets - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--vault-token `: Delegated tdc fs-vault token; prefer `TDC_VAULT_TOKEN`. -- `--version`: Display tdc version information. +- `--vault-token `: Delegated `tdc fs-vault` token; prefer `TDC_VAULT_TOKEN`. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### List secrets +- List owner-visible secrets: -```bash -tdc fs-vault list-secrets --file-system-name workspace -``` + ```bash + # Return secret metadata without exposing field values. + tdc fs-vault list-secrets --file-system-name workspace + ``` -### List secrets with a delegated Vault token +- List secrets visible to a delegated token: -```bash -tdc fs-vault list-secrets --file-system-name workspace --vault-token "$TDC_VAULT_TOKEN" --output text -``` + ```bash + # Restrict the result to secrets within the token's granted scope. + tdc fs-vault list-secrets --file-system-name workspace --vault-token "$TDC_VAULT_TOKEN" + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md index 8451ea76908d0..dd865a22a85ff 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md @@ -9,7 +9,7 @@ Mounts readable vault fields as a local read-only FUSE filesystem. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -35,21 +35,27 @@ tdc fs-vault mount-vault - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--ready-timeout `: Time to wait for a background mount to become ready. \[default: `30s`] -- `--vault-token `: Delegated tdc fs-vault token; prefer `TDC_VAULT_TOKEN`. -- `--version`: Display tdc version information. +- `--vault-token `: Delegated `tdc fs-vault` token; prefer `TDC_VAULT_TOKEN`. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Mount a Vault view with a delegated token +- Mount a delegated Vault view: -```bash -tdc fs-vault mount-vault --file-system-name workspace --mount-path ./vault --vault-token "$TDC_VAULT_TOKEN" -``` + ```bash + # Expose only the paths allowed by the delegated Vault token. + tdc fs-vault mount-vault --file-system-name workspace --mount-path ./vault --vault-token "$TDC_VAULT_TOKEN" + ``` -### Run a Vault mount in the foreground +- Run the Vault mount in the foreground: -```bash -tdc fs-vault mount-vault --file-system-name workspace --mount-path ./vault --foreground --ready-timeout 60s -``` + ```bash + # Keep the runtime attached for containers or process supervisors. + tdc fs-vault mount-vault --file-system-name workspace --mount-path ./vault --foreground --ready-timeout 60s + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md index 8503ec8ae586b..e8d0624cea925 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md @@ -9,7 +9,7 @@ Reads a complete secret or one field using an owner or delegated credential. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -33,21 +33,34 @@ tdc fs-vault read-secret - `--format `: Read output format: `json`, `raw`, or `env`. \[default: json] - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--vault-token `: Delegated tdc fs-vault token; prefer `TDC_VAULT_TOKEN`. -- `--version`: Display tdc version information. +- `--vault-token `: Delegated `tdc fs-vault` token; prefer `TDC_VAULT_TOKEN`. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Read one secret field +- Read one secret field as raw text: -```bash -tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field PASSWORD --format raw -``` + ```bash + # Write only the selected field value for direct consumption by a process. + tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field PASSWORD --format raw + ``` -### Format a secret field as an environment variable +- Format a field as an environment assignment: -```bash -tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field DB_URL --format env -``` + ```bash + # Emit an exportable environment-variable representation of the field. + tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field DB_URL --format env + ``` + +- Read with a delegated Vault token: + + ```bash + # Access only the scope granted to an agent without using the owner token. + tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field DB_URL --vault-token "$TDC_VAULT_TOKEN" --format raw + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md index b38e308c5d218..d3dfcda169e7d 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md @@ -9,7 +9,7 @@ Replaces all fields in one secret from files in a local directory. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -32,20 +32,26 @@ tdc fs-vault replace-secret - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Replace a secret from a directory +- Replace a secret from a directory: -```bash -tdc fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields -``` + ```bash + # Replace all fields with files loaded from the selected directory. + tdc fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields + ``` -### Preview secret replacement +- Preview secret replacement: -```bash -tdc fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields --dry-run -``` + ```bash + # Validate the replacement source without changing the stored secret. + tdc fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md index 2c12cbfc88b55..13490d86a6ac2 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md @@ -9,7 +9,7 @@ Runs a command with one secret injected into its environment. Arguments after `- > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -29,21 +29,27 @@ tdc fs-vault run-with-secret - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--vault-token `: Delegated tdc fs-vault token; prefer `TDC_VAULT_TOKEN`. -- `--version`: Display tdc version information. +- `--vault-token `: Delegated `tdc fs-vault` token; prefer `TDC_VAULT_TOKEN`. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Run a command with secret fields +- Run a process with secret fields: -```bash -tdc fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- env -``` + ```bash + # Inject all fields into the child process environment without printing them. + tdc fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- env + ``` -### Use an injected secret in a shell command +- Use an injected field in a shell command: -```bash -tdc fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- sh -c 'test -n "$DB_URL"' -``` + ```bash + # Verify that the child process receives DB_URL without exposing its value. + tdc fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- sh -c 'test -n "$DB_URL"' + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md index 33f5d3803c8d8..084c13be7ba36 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md @@ -9,7 +9,7 @@ Unmounts a local Filesystem Vault filesystem. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -30,22 +30,21 @@ tdc fs-vault unmount-vault - `--dry-run`: Validate the request without applying changes. - `--force`: Force-kill the mount process if graceful unmount times out. - `--help`: Display help information. -- `--ignore-absent`: Return success when no tdc fs-vault mount state exists for the path. +- `--ignore-absent`: Return success when no `tdc fs-vault` mount state exists for the path. - `--timeout `: Time to wait for the mount process to exit. \[default: `30s`] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Unmount a Vault view +- Unmount a Vault view: -```bash -tdc fs-vault unmount-vault --mount-path ./vault -``` + ```bash + # Detach the local read-only Vault mount. + tdc fs-vault unmount-vault --mount-path ./vault + ``` -### Ignore an absent Vault mount +## Related documentation -```bash -tdc fs-vault unmount-vault --mount-path ./vault --ignore-absent -``` +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md index 1d06d3f6089ed..83e6b894d5722 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md @@ -9,7 +9,7 @@ Checks Filesystem selection, endpoint resolution, credentials, and companion acc > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -26,20 +26,19 @@ tdc fs check-file-system - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Check file system connectivity +- Check Filesystem connectivity: -```bash -tdc fs check-file-system --file-system-name workspace -``` + ```bash + # Verify that the selected token can reach and read the Filesystem root. + tdc fs check-file-system --file-system-name workspace + ``` -### Render the check result as text +## Related documentation -```bash -tdc fs check-file-system --file-system-name workspace --output text -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md b/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md index 5e42a03cd0e93..5da5399eaf6da 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md @@ -9,7 +9,7 @@ Changes POSIX mode metadata for a remote path. The command alias is `tdc fs chmo > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -32,20 +32,19 @@ tdc fs chmod-file - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Change file permissions +- Change remote permission metadata: -```bash -tdc fs chmod-file --file-system-name workspace --path /reports/final.md --mode 0600 -``` + ```bash + # Restrict the selected file to owner read and write access. + tdc fs chmod-file --file-system-name workspace --path /reports/final.md --mode 0600 + ``` -### Preview a permission change with the alias +## Related documentation -```bash -tdc fs chmod --file-system-name workspace --path /reports/final.md --mode 0644 --dry-run -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md index eb500ff492b28..25fc65687d622 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md @@ -9,7 +9,7 @@ Applies one layer to its base Filesystem. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -30,20 +30,19 @@ tdc fs commit-layer - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Preview a layer commit +- Commit a layer: -```bash -tdc fs commit-layer --file-system-name workspace --layer-id "" --dry-run -``` + ```bash + # Apply the selected layer's changes to its base Filesystem view. + tdc fs commit-layer --file-system-name workspace --layer-id "" + ``` -### Commit a layer +## Related documentation -```bash -tdc fs commit-layer --file-system-name workspace --layer-id "" -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md b/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md index 400d63e41ddbc..a70f1b54076fc 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md @@ -9,7 +9,7 @@ Copies files between local paths, remote paths, stdin, and stdout. The command a > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -56,20 +56,54 @@ tdc fs copy-file - `--to-local `: The local destination path. - `--to-remote `: The destination path in the TiDB Cloud file system. - `--to-stdout`: Write `--from-remote` to stdout. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Upload a local file +- Upload a local file: -```bash -tdc fs copy-file --file-system-name workspace --from-local ./report.md --to-remote /reports/report.md -``` + ```bash + # Copy a local report into the selected remote Filesystem. + tdc fs copy-file --file-system-name workspace --from-local ./report.md --to-remote /reports/report.md + ``` -### Download a remote file +- Download a remote file: -```bash -tdc fs copy-file --file-system-name workspace --from-remote /reports/report.md --to-local ./report.copy.md --create-parents -``` + ```bash + # Create missing local parent directories while downloading the file. + tdc fs copy-file --file-system-name workspace --from-remote /reports/report.md --to-local ./downloads/report.md --create-parents + ``` + +- Copy a remote directory: + + ```bash + # Duplicate a complete directory tree without downloading it locally. + tdc fs copy-file --file-system-name workspace --from-remote /reports --to-remote /archive/reports --recursive + ``` + +- Resume a large upload: + + ```bash + # Continue an interrupted local-to-remote transfer instead of restarting it. + tdc fs copy-file --file-system-name workspace --from-local ./large.bin --to-remote /artifacts/large.bin --resume + ``` + +- Append to a remote log: + + ```bash + # Add local log data to the existing remote object efficiently. + tdc fs copy-file --file-system-name workspace --from-local ./tail.log --to-remote /logs/app.log --append + ``` + +- Stream standard input to the Filesystem: + + ```bash + # Upload generated content without creating an intermediate local file. + printf 'ready\n' | tdc fs copy-file --file-system-name workspace --from-stdin --to-remote /status.txt --tag source=stdin --description "generated status" + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md b/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md index ea4970a760826..8d244602b2c82 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md @@ -9,7 +9,7 @@ Creates a remote directory. The command alias is `tdc fs mkdir`. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -32,20 +32,19 @@ tdc fs create-directory - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--mode `: The directory mode as an octal value such as 0755. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create a directory +- Create a remote directory: -```bash -tdc fs create-directory --file-system-name workspace --path /reports/archive --mode 0755 -``` + ```bash + # Create the directory with explicit POSIX permission metadata. + tdc fs create-directory --file-system-name workspace --path /reports/archive --mode 0755 + ``` -### Preview directory creation with the alias +## Related documentation -```bash -tdc fs mkdir --file-system-name workspace --path /reports/review --dry-run -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md index bee862bf1eade..359e882eaf35b 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md @@ -9,7 +9,7 @@ Creates a Filesystem. `--wait` waits until data-plane access is ready. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -27,21 +27,34 @@ tdc fs create-file-system - `--file-system-name `: Set the file system name. \[required] - `--dry-run`: Validate the request without applying changes. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. - `--wait`: Wait until the created file system is active. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create a file system and wait until it is ready +- Create a Filesystem and wait until it is ready: -```bash -tdc fs create-file-system --file-system-name workspace --wait -``` + ```bash + # Wait until the new Filesystem root is readable before returning. + tdc fs create-file-system --file-system-name workspace --wait + ``` -### Preview file system creation +- Create a Filesystem asynchronously: -```bash -tdc fs create-file-system --file-system-name workspace --dry-run -``` + ```bash + # Return after provisioning is accepted so work can continue in parallel. + tdc fs create-file-system --file-system-name scratch + ``` + +- Preview Filesystem creation: + + ```bash + # Validate credentials, placement, and the request without provisioning storage. + tdc fs create-file-system --file-system-name workspace --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md b/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md index e5762a6cdad81..02ea2cd74127d 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md @@ -9,7 +9,7 @@ Creates a hard link to an existing remote path. The command alias is `tdc fs har > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -32,20 +32,19 @@ tdc fs create-hardlink - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create a hard link +- Create a hard link: -```bash -tdc fs create-hardlink --file-system-name workspace --source-path /reports/final.md --link-path /reports/final-copy.md -``` + ```bash + # Expose the same remote file content at a second path. + tdc fs create-hardlink --file-system-name workspace --source-path /reports/final.md --link-path /reports/final-copy.md + ``` -### Preview hard-link creation with the alias +## Related documentation -```bash -tdc fs hardlink --file-system-name workspace --source-path /reports/final.md --link-path /reports/backup.md --dry-run -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md b/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md index 2eaed1bf1cd27..afc1543538f5b 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md @@ -9,7 +9,7 @@ Creates a checkpoint in one layer. If `--checkpoint-id` is omitted, the service > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -34,20 +34,26 @@ tdc fs create-layer-checkpoint - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--label `: The checkpoint label. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create a checkpoint with an explicit ID +- Create a named checkpoint: -```bash -tdc fs create-layer-checkpoint --file-system-name workspace --layer-id "" --checkpoint-id before-review -``` + ```bash + # Record the current layer state under a stable checkpoint ID. + tdc fs create-layer-checkpoint --file-system-name workspace --layer-id "" --checkpoint-id before-review + ``` -### Preview an automatically identified checkpoint +- Create an automatically identified checkpoint: -```bash -tdc fs create-layer-checkpoint --file-system-name workspace --layer-id "" --label "before review" --dry-run -``` + ```bash + # Let the service assign the checkpoint ID while retaining a human label. + tdc fs create-layer-checkpoint --file-system-name workspace --layer-id "" --label "before review" + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md index 0f18a37802fd7..45385251806f1 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md @@ -9,7 +9,7 @@ Creates an isolated change layer over a base root. If `--layer-id` is omitted, t > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -40,20 +40,26 @@ tdc fs create-layer - `--layer-id `: The layer ID. Normally it is generated by the service automatically. - `--layer-name `: The name of the layer. - `--tag `: Tags for the layer, `key=value`; repeatable. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create a layer +- Create a layer: -```bash -tdc fs create-layer --file-system-name workspace --base-root-path /workspace --layer-name agent-task -``` + ```bash + # Start an isolated writable view over the selected base root. + tdc fs create-layer --file-system-name workspace --base-root-path /workspace --layer-name agent-task + ``` -### Preview a restore-safe layer +- Create a restore-safe tagged layer: -```bash -tdc fs create-layer --file-system-name workspace --base-root-path /workspace --durability-mode restore-safe --tag task=review --dry-run -``` + ```bash + # Request durable layer behavior and attach task metadata. + tdc fs create-layer --file-system-name workspace --base-root-path /workspace --durability-mode restore-safe --tag task=review + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md b/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md index 398481f493191..6b90ce9baa74a 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md @@ -9,7 +9,7 @@ Creates a symbolic link. The command alias is `tdc fs symlink`. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -32,20 +32,19 @@ tdc fs create-symlink - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Create a symbolic link +- Create a symbolic link: -```bash -tdc fs create-symlink --file-system-name workspace --target final.md --link-path /reports/latest.md -``` + ```bash + # Create a relative symbolic link inside the remote namespace. + tdc fs create-symlink --file-system-name workspace --target final.md --link-path /reports/latest.md + ``` -### Preview symbolic-link creation with the alias +## Related documentation -```bash -tdc fs symlink --file-system-name workspace --target archive/report.md --link-path /reports/archive-link --dry-run -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md index 5915594593e32..efb8b565611db 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md @@ -9,7 +9,7 @@ Requests asynchronous Filesystem deletion and removes its local registration. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -28,20 +28,26 @@ tdc fs delete-file-system - `--dry-run`: Validate the request without applying changes. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Preview file system deletion +- Delete a Filesystem: -```bash -tdc fs delete-file-system --file-system-name workspace --dry-run -``` + ```bash + # Request asynchronous deletion and remove its local registration after acceptance. + tdc fs delete-file-system --file-system-name workspace + ``` -### Delete a file system +- Preview Filesystem deletion: -```bash -tdc fs delete-file-system --file-system-name workspace -``` + ```bash + # Validate the selected Filesystem without sending the deletion request. + tdc fs delete-file-system --file-system-name workspace --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md b/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md index 95d0861056296..6c09dbd797fb6 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md @@ -9,7 +9,7 @@ Deletes a remote file or directory. The command alias is `tdc fs rm`. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -32,20 +32,26 @@ tdc fs delete-file - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--recursive`: Delete a directory recursively. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Delete a file +- Delete a remote file: -```bash -tdc fs delete-file --file-system-name workspace --path /reports/obsolete.md -``` + ```bash + # Remove one object from the selected Filesystem. + tdc fs delete-file --file-system-name workspace --path /reports/obsolete.md + ``` -### Preview recursive directory deletion +- Delete a directory recursively: -```bash -tdc fs delete-file --file-system-name workspace --path /scratch --recursive --dry-run -``` + ```bash + # Remove a directory and all of its descendants in one request. + tdc fs delete-file --file-system-name workspace --path /scratch --recursive + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md index 6bde39e86386e..daeef296b67c8 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md @@ -9,7 +9,7 @@ Describes one locally registered Filesystem. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -24,20 +24,19 @@ tdc fs describe-file-system - `--file-system-name `: Set the file system name. \[required] - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Describe a file system +- Describe a Filesystem: -```bash -tdc fs describe-file-system --file-system-name workspace -``` + ```bash + # Return registration, endpoint, and region details for one Filesystem. + tdc fs describe-file-system --file-system-name workspace + ``` -### Render file system details as text +## Related documentation -```bash -tdc fs describe-file-system --file-system-name workspace --output text -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md index 02bc1c2aa0579..e9b2b59a04547 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md @@ -9,7 +9,7 @@ Describes metadata for one remote path. The command alias is `tdc fs stat`. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -28,20 +28,19 @@ tdc fs describe-file - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Describe a file +- Describe a remote file: -```bash -tdc fs describe-file --file-system-name workspace --path /reports/report.md -``` + ```bash + # Inspect file size, metadata, tags, and revision information. + tdc fs describe-file --file-system-name workspace --path /reports/report.md + ``` -### Use the stat alias with text output +## Related documentation -```bash -tdc fs stat --file-system-name workspace --path /reports/report.md --output text -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md index a3def67899089..262d717e21959 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md @@ -9,7 +9,7 @@ Describes one Filesystem layer. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -28,20 +28,19 @@ tdc fs describe-layer - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Describe a layer +- Describe a layer: -```bash -tdc fs describe-layer --file-system-name workspace --layer-id "" -``` + ```bash + # Inspect one layer's base root, state, durability, and metadata. + tdc fs describe-layer --file-system-name workspace --layer-id "" + ``` -### Render layer details as text +## Related documentation -```bash -tdc fs describe-layer --file-system-name workspace --layer-id "" --output text -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md index 3d0d3bc2053c8..627fb2f0c0087 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md @@ -9,7 +9,7 @@ Lists changes in one layer, optionally up to a sequence number. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -30,20 +30,26 @@ tdc fs diff-layer - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--max-seq `: The highest layer sequence to include; 0 includes all layers. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Show all layer changes +- Show all layer changes: -```bash -tdc fs diff-layer --file-system-name workspace --layer-id "" -``` + ```bash + # Return the complete ordered change set for the selected layer. + tdc fs diff-layer --file-system-name workspace --layer-id "" + ``` -### Show changes through a sequence number +- Show an earlier layer view: -```bash -tdc fs diff-layer --file-system-name workspace --layer-id "" --max-seq 100 -``` + ```bash + # Limit the diff to changes at or before a sequence number. + tdc fs diff-layer --file-system-name workspace --layer-id "" --max-seq 100 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md index 507ee92bf4bf8..94579e475b812 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md @@ -9,7 +9,7 @@ Flushes dirty FUSE state while leaving the mount online. The command alias is `t > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -28,20 +28,19 @@ tdc fs drain-file-system - `--dry-run`: Validate the request without applying changes. - `--help`: Display help information. - `--timeout `: The time to wait for dirty handles and pending writes to drain. \[default: `30s`] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Drain pending writes +- Drain pending writes: -```bash -tdc fs drain-file-system --mount-path /path/to/workspace -``` + ```bash + # Flush queued FUSE writes while leaving the Filesystem mounted. + tdc fs drain-file-system --mount-path /path/to/workspace --timeout 30s + ``` -### Drain with the alias and an explicit timeout +## Related documentation -```bash -tdc fs drain --mount-path /path/to/workspace --timeout 30s -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-find-files.md b/ai/tdc/reference/commands/fs/tdc-fs-find-files.md index 58f8344c5e38b..9703d2219fb54 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-find-files.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-find-files.md @@ -9,7 +9,7 @@ Finds remote paths by name, type, tag, size, or modification time. The command a > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -46,20 +46,26 @@ tdc fs find-files - `--path `: File path prefix. \[default: /] - `--resource-type `: Resource type filter: `file` or `directory`. - `--tag `: Tag filter. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Find files by name +- Find files by name: -```bash -tdc fs find-files --file-system-name workspace --path /workspace --file-name-pattern "*.md" -``` + ```bash + # Locate Markdown files recursively under the selected remote path. + tdc fs find-files --file-system-name workspace --path /workspace --file-name-pattern "*.md" + ``` -### Find tagged files with the alias +- Find files by metadata: -```bash -tdc fs find --file-system-name workspace --path /workspace --tag stage=review --min-size-bytes 1024 -``` + ```bash + # Select tagged files that also meet a minimum size threshold. + tdc fs find-files --file-system-name workspace --path /workspace --tag stage=review --min-size-bytes 1024 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md b/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md index 469f00f789652..8932daaa6e1ab 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md @@ -9,7 +9,7 @@ Lists Filesystems registered in the selected local profile. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -22,20 +22,19 @@ tdc fs list-file-systems ## Options - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### List registered file systems as text +- List locally registered Filesystems: -```bash -tdc fs list-file-systems --output text -``` + ```bash + # Return the Filesystems registered under the selected local profile. + tdc fs list-file-systems + ``` -### Return registered file system names +## Related documentation -```bash -tdc fs list-file-systems --query 'file_systems[].file_system_name' -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-files.md b/ai/tdc/reference/commands/fs/tdc-fs-list-files.md index b1be753ee324f..8d290b8cd1427 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-files.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-files.md @@ -9,7 +9,7 @@ Lists entries below a remote path. The command alias is `tdc fs ls`. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -28,20 +28,19 @@ tdc fs list-files - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--path `: File system directory path. \[default: /] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### List files +- List a remote directory: -```bash -tdc fs list-files --file-system-name workspace --path /reports -``` + ```bash + # Return the entries under a specific Filesystem path. + tdc fs list-files --file-system-name workspace --path /reports + ``` -### List files as text +## Related documentation -```bash -tdc fs list-files --file-system-name workspace --path /reports --output text -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md b/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md index a41e115d6c5a1..5a95b8f19b9f8 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md @@ -9,7 +9,7 @@ Lists layers for the selected Filesystem. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -26,20 +26,19 @@ tdc fs list-layers - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### List layers +- List Filesystem layers: -```bash -tdc fs list-layers --file-system-name workspace -``` + ```bash + # Return all layers available in the selected Filesystem. + tdc fs list-layers --file-system-name workspace + ``` -### List layers as text +## Related documentation -```bash -tdc fs list-layers --file-system-name workspace --output text -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md index aa69bf45cfa15..01cc0123e5019 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md @@ -9,7 +9,7 @@ Mounts a Filesystem through automatic, FUSE, or WebDAV mode. The command alias i > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -59,21 +59,41 @@ tdc fs mount-file-system - `--ready-timeout `: Time to wait for a background mount to become ready. \[default: `30s`] - `--remote-path `: The TiDB Cloud file system root path to mount. \[default: /] - `--unpack-archive-path `: Restore the pack archive before mounting. -- `--version`: Display tdc version information. +- `--version`: Display version information. - `--write-back-cache`: Persist FUSE writes locally before writing them to the file system on flush. \[default: true] For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Mount a file system +- Mount a Filesystem with the default driver: -```bash -tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace -``` + ```bash + # Let the CLI select the default driver for the current platform. + tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace + ``` -### Create a read-only FUSE mount with the alias +- Create a read-only FUSE mount: -```bash -tdc fs mount --file-system-name workspace --mount-path /path/to/workspace --driver fuse --read-only -``` + ```bash + # Expose the remote namespace through FUSE without permitting writes. + tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver fuse --read-only + ``` + +- Use WebDAV on macOS without macFUSE: + + ```bash + # Select WebDAV explicitly when a FUSE runtime is unavailable. + tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver webdav + ``` + +- Tune the FUSE read cache: + + ```bash + # Increase cache capacity for repeated reads of medium-sized files. + tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver fuse --read-cache-size-mb 256 --read-cache-max-file-mb 16 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-move-file.md b/ai/tdc/reference/commands/fs/tdc-fs-move-file.md index b9bbe821a48bd..94c21215331a3 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-move-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-move-file.md @@ -9,7 +9,7 @@ Moves or renames a remote path. The command alias is `tdc fs mv`. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -34,20 +34,19 @@ tdc fs move-file - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--overwrite`: Replace an existing destination file. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Move a remote file +- Move a remote file: -```bash -tdc fs move-file --file-system-name workspace --from-remote /draft.md --to-remote /reports/final.md -``` + ```bash + # Rename or relocate an object entirely within the selected Filesystem. + tdc fs move-file --file-system-name workspace --from-remote /draft.md --to-remote /reports/final.md + ``` -### Preview a move with the alias +## Related documentation -```bash -tdc fs mv --file-system-name workspace --from-remote /draft.md --to-remote /reports/final.md --dry-run -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md index 401bb2ba2452b..569e2af464f7d 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md @@ -9,7 +9,7 @@ Packs selected local overlay state into a remote archive. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -40,20 +40,26 @@ tdc fs pack-file-system - `--mount-profile `: The mount profile: `coding-agent`, `portable`, or `none`. If omitted, uses `none`. - `--path `: Local overlay path for packing; repeatable. - `--remote-root `: The TiDB Cloud file system root represented by the local overlay. \[default: /] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Pack a mounted workspace +- Pack a mounted workspace: -```bash -tdc fs pack-file-system --file-system-name workspace --mount-path /path/to/workspace -``` + ```bash + # Persist the local overlay associated with an existing mount. + tdc fs pack-file-system --file-system-name workspace --mount-path /path/to/workspace + ``` -### Pack explicit local and remote roots +- Pack explicit roots: -```bash -tdc fs pack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable -``` + ```bash + # Create a portable archive from selected local and remote roots. + tdc fs pack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-read-file.md b/ai/tdc/reference/commands/fs/tdc-fs-read-file.md index 14627f0fa9425..e8acff4f9b9a4 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-read-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-read-file.md @@ -9,7 +9,7 @@ Writes a remote file or byte range to stdout. The command alias is `tdc fs cat`. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -32,20 +32,26 @@ tdc fs read-file - `--help`: Display help information. - `--length `: Byte length for a ranged read. - `--offset `: Zero-based byte offset for a ranged read. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Read a file +- Read a complete file: -```bash -tdc fs read-file --file-system-name workspace --path /reports/report.md -``` + ```bash + # Write the remote file contents directly to standard output. + tdc fs read-file --file-system-name workspace --path /reports/report.md + ``` -### Read a byte range +- Read a byte range: -```bash -tdc fs read-file --file-system-name workspace --path /archives/large.bin --offset 1024 --length 4096 -``` + ```bash + # Fetch only the requested range from a large remote object. + tdc fs read-file --file-system-name workspace --path /archives/large.bin --offset 1024 --length 4096 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md index 53b9704a60aa3..9d13958f844ba 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md @@ -9,7 +9,7 @@ Rolls back changes in one layer without committing them to the base. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -30,20 +30,19 @@ tdc fs rollback-layer - `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Preview a layer rollback +- Roll back a layer: -```bash -tdc fs rollback-layer --file-system-name workspace --layer-id "" --dry-run -``` + ```bash + # Discard uncommitted changes and restore the layer's base view. + tdc fs rollback-layer --file-system-name workspace --layer-id "" + ``` -### Roll back a layer +## Related documentation -```bash -tdc fs rollback-layer --file-system-name workspace --layer-id "" -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md b/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md index 1b95c114d80a8..8c505137fa4b9 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md @@ -9,7 +9,7 @@ Searches remote file content, optionally in a layer. The command alias is `tdc f > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -34,20 +34,26 @@ tdc fs search-file-content - `--layer-id `: Search within a file system layer. - `--limit `: Maximum number of search results; 0 uses the service default. - `--path `: File path prefix to be searched. \[default: /] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Search file content +- Search base Filesystem content: -```bash -tdc fs search-file-content --file-system-name workspace --path /workspace --pattern "TODO" --limit 50 -``` + ```bash + # Find matching text under a remote directory and limit the result count. + tdc fs search-file-content --file-system-name workspace --path /workspace --pattern "TODO" --limit 50 + ``` -### Search a layer with the grep alias +- Search content in a layer: -```bash -tdc fs grep --file-system-name workspace --path /workspace --pattern "deprecated" --layer-id "" -``` + ```bash + # Inspect uncommitted layer content separately from the base Filesystem. + tdc fs search-file-content --file-system-name workspace --path /workspace --pattern "deprecated" --layer-id "" + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md index 7291569d402e8..93c815c81ab54 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md @@ -9,7 +9,7 @@ Gracefully flushes and unmounts a background mount. The command alias is `tdc fs > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -36,20 +36,19 @@ tdc fs unmount-file-system - `--no-auto-pack`: Skip the portable mount profile's default auto-pack action. - `--pack-archive-path `: Pack archive to write after unmount. - `--timeout `: Time to wait for the mount process to exit. \[default: `30s`] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Unmount a file system +- Unmount a Filesystem: -```bash -tdc fs unmount-file-system --mount-path /path/to/workspace -``` + ```bash + # Gracefully flush pending writes and detach the Filesystem mount. + tdc fs unmount-file-system --mount-path /path/to/workspace + ``` -### Ignore an absent mount with the alias +## Related documentation -```bash -tdc fs umount --mount-path /path/to/workspace --ignore-absent -``` +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md index 02a74ee7b1b24..bd838718c79b9 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md @@ -9,7 +9,7 @@ Restores local overlay state from a remote archive. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -40,20 +40,26 @@ tdc fs unpack-file-system - `--mount-profile `: Mount profile: `coding-agent`, `portable`, or `none`. If omitted, uses `none`. - `--no-replace`: Merge archive entries instead of replacing them. - `--remote-root `: Find the packed archive under the specified root path when `--archive-path` is omitted. \[default: /] -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Unpack into a mounted workspace +- Unpack into a mounted workspace: -```bash -tdc fs unpack-file-system --file-system-name workspace --mount-path /path/to/workspace -``` + ```bash + # Restore the portable archive associated with an existing mount. + tdc fs unpack-file-system --file-system-name workspace --mount-path /path/to/workspace + ``` -### Unpack explicit roots without replacing files +- Unpack explicit roots without replacement: -```bash -tdc fs unpack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable --no-replace -``` + ```bash + # Restore missing files while preserving existing destination entries. + tdc fs unpack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable --no-replace + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md b/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md index 3296a518e65b9..42f6a371eb5ca 100644 --- a/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md +++ b/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md @@ -9,7 +9,7 @@ Lists projects accessible to the configured TiDB Cloud API key, with optional pa > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -26,20 +26,26 @@ tdc organization list-projects - `--help`: Display help information. - `--page-size `: Number of projects to request; 0 uses the API default. - `--page-token `: Page token returned by a previous list-projects call. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### List projects as text +- List accessible projects: -```bash -tdc organization list-projects --page-size 50 --output text -``` + ```bash + # Return the TiDB Cloud projects available to the configured API key. + tdc organization list-projects --page-size 50 + ``` -### Return virtual project IDs +- Select the virtual project ID: -```bash -tdc organization list-projects --query 'projects[?type == `tidbx_virtual`].id' --output text -``` + ```bash + # Use a JMESPath query to return only virtual project IDs. + tdc organization list-projects --query 'projects[?type == `tidbx_virtual`].id' --output text + ``` + +## Related documentation + +- [TiDB Cloud Organization CLI Command Reference](/ai/tdc/reference/tdc-organization.md) diff --git a/ai/tdc/reference/commands/tdc/tdc-configure.md b/ai/tdc/reference/commands/tdc/tdc-configure.md index 99608892413f6..d81134f33f52a 100644 --- a/ai/tdc/reference/commands/tdc/tdc-configure.md +++ b/ai/tdc/reference/commands/tdc/tdc-configure.md @@ -1,15 +1,15 @@ --- title: tdc configure -summary: Configure a local tdc profile interactively or non-interactively. +summary: Configure a local TiDB Cloud CLI profile interactively or non-interactively. --- # tdc configure -Configures a local tdc profile. Without flags, this is the only interactive tdc command. +Configures a local TiDB Cloud CLI profile. Without flags, this is the only interactive TiDB Cloud CLI command. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -26,27 +26,33 @@ tdc configure ## Options - `--help`: Display help information. -- `--non-interactive`: Use this option to avoid being prompted for configuration values. You must provide at least three configuration values (`--tdc-public-key`, `--tdc-private-key`, and `--region-code`) when using this option. This is useful when running tdc in a script or automated environment. +- `--non-interactive`: Use this option to avoid being prompted for configuration values. You must provide at least three configuration values (`--tdc-public-key`, `--tdc-private-key`, and `--region-code`) when using this option. This is useful when running `tdc` in a script or automated environment. - `--region-code `: Default region code, for example `aws-us-east-1` or `aws-ap-southeast-1`. - `--tdc-private-key `: TiDB Cloud API private key. - `--tdc-public-key `: TiDB Cloud API public key. -- `--version`: Display tdc version information. +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Configure tdc interactively +- Configure `tdc` interactively: -```bash -tdc configure -``` + ```bash + # Enter the default region code and TiDB Cloud API keys when prompted. + tdc configure + ``` -### Configure tdc for automation +- Configure `tdc` for automation: -```bash -TDC_REGION_CODE="aws-us-east-1" \ -TDC_PUBLIC_KEY="" \ -TDC_PRIVATE_KEY="" \ -tdc configure --profile ci --non-interactive -``` + ```bash + # Supply all required values without interactive prompts. + TDC_REGION_CODE="aws-us-east-1" \ + TDC_PUBLIC_KEY="" \ + TDC_PRIVATE_KEY="" \ + tdc configure --profile ci --non-interactive + ``` + +## Related documentation + +- [Install, Configure, and Update TiDB Cloud CLI](/ai/tdc/reference/tdc-install-configure-update.md) diff --git a/ai/tdc/reference/commands/tdc/tdc-update.md b/ai/tdc/reference/commands/tdc/tdc-update.md index 35017e040925f..15d3cb5284811 100644 --- a/ai/tdc/reference/commands/tdc/tdc-update.md +++ b/ai/tdc/reference/commands/tdc/tdc-update.md @@ -1,15 +1,15 @@ --- title: tdc update -summary: Check for or install a tdc release update. +summary: Check for or install a TiDB Cloud CLI release update. --- # tdc update -Checks for or installs a tdc release update. This command does not read or modify profiles and credentials. +Checks for or installs a TiDB Cloud CLI release update. This command does not read or modify profiles and credentials. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -25,25 +25,38 @@ tdc update ## Options -- `--check`: Check whether a newer tdc release is available without updating. +- `--check`: Check whether a newer `tdc` release is available without updating. - `--dry-run`: Show the update plan without changing the local binary. - `--fail-if-update-available`: With `--check`, exit with code 1 when an update is available. - `--help`: Display help information. -- `--target-version `: Target tdc version, such as `latest` or `vX.Y.Z`. \[default: latest] -- `--version`: Display tdc version information. +- `--target-version `: Target `tdc` version, such as `latest` or `vX.Y.Z`. \[default: latest] +- `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). ## Examples -### Check for an update +- Check whether an update is available: -```bash -tdc update --check -``` + ```bash + # Compare the installed version with the latest GitHub release without changing files. + tdc update --check + ``` -### Install a specific version +- Preview an update: -```bash -tdc update --target-version -``` + ```bash + # Show the files and versions that an update would change. + tdc update --dry-run + ``` + +- Install a specific release: + + ```bash + # Replace an eligible installation with the requested release version. + tdc update --target-version + ``` + +## Related documentation + +- [Install, Configure, and Update TiDB Cloud CLI](/ai/tdc/reference/tdc-install-configure-update.md) diff --git a/ai/tdc/reference/tdc-agent-sandbox-example.md b/ai/tdc/reference/tdc-agent-sandbox-example.md index 4c316c211b471..d4d0ce5b614db 100644 --- a/ai/tdc/reference/tdc-agent-sandbox-example.md +++ b/ai/tdc/reference/tdc-agent-sandbox-example.md @@ -5,11 +5,11 @@ summary: Provision a Filesystem on a trusted machine and give a clean agent sand # Use TiDB Cloud Filesystem in an Agent Sandbox -This example gives an ephemeral coding agent a durable workspace without copying a user's complete tdc configuration into the sandbox. +This example gives an ephemeral coding agent a durable workspace without copying a user's complete TiDB Cloud CLI configuration into the sandbox. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem @@ -19,14 +19,14 @@ Coding agents often start in clean, short-lived sandboxes. The local disk disapp A sandbox-local directory is fast but not durable or shared. Generic object-storage APIs require application-specific download and upload logic instead of ordinary file operations. Giving every sandbox the user's complete cloud credentials solves access at the cost of a broader security boundary. -## How tdc changes the workflow +## How TiDB Cloud CLI changes the workflow A trusted machine provisions the Filesystem once. The sandbox receives only the Filesystem owner token, region code, and Filesystem name, and can immediately use data-plane, mount, Git, journal, and vault workflows without `tdc configure`. When an agent needs only selected secrets, use a delegated vault token instead of the owner token. ## Prerequisites -- Install and configure tdc on a trusted machine. -- Install tdc in the sandbox. The release installer includes `tdc-drive9`. +- Install and configure the TiDB Cloud CLI on a trusted machine. +- Install the TiDB Cloud CLI in the sandbox. The release installer includes `tdc-drive9`. - Use a secure secret manager or encrypted sandbox input for token transfer. ## Step 1. Provision on the trusted machine @@ -113,5 +113,5 @@ tdc fs delete-file-system \ ## What's next -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-ci-artifact-handoff-example.md b/ai/tdc/reference/tdc-ci-artifact-handoff-example.md index d7a6f26eddd8a..0e4383e975505 100644 --- a/ai/tdc/reference/tdc-ci-artifact-handoff-example.md +++ b/ai/tdc/reference/tdc-ci-artifact-handoff-example.md @@ -1,21 +1,21 @@ --- -title: Hand Off CI Artifacts Between Isolated Jobs with tdc -summary: Persist build output in TiDB Cloud Filesystem and consume it from a later CI job without copying a complete tdc profile. +title: Hand Off CI Artifacts Between Isolated Jobs with TiDB Cloud Filesystem +summary: Persist build output in TiDB Cloud Filesystem and consume it from a later CI job without copying a complete TiDB Cloud CLI profile. --- -# Hand Off CI Artifacts Between Isolated Jobs with tdc +# Hand Off CI Artifacts Between Isolated Jobs with TiDB Cloud Filesystem This scenario uses a Filesystem as a durable handoff point between isolated CI jobs or runners. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## The problem Build and verification jobs often run on different ephemeral machines. Local output disappears with the producer, while provider-specific artifact services add another upload API, retention model, and download step to agent automation. -## How tdc changes the workflow +## How TiDB Cloud CLI changes the workflow The pipeline injects one Filesystem token, region, and name into both jobs. The producer uploads output under a run-specific path, and the consumer downloads or streams that exact path. Neither job needs TiDB Cloud API keys or a copied `~/.tdc/` directory. @@ -76,6 +76,6 @@ Use unique run IDs and do not delete the whole Filesystem from an individual job ## Related reference -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) -- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md index db97c0b3fa83f..dcb50833c82ce 100644 --- a/ai/tdc/reference/tdc-cli-reference.md +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -1,15 +1,15 @@ --- -title: tdc CLI Reference +title: TiDB Cloud CLI Command Reference summary: Reference global options, output and query behavior, dry-run rules, help forms, errors, command families, and Filesystem aliases. --- -# tdc CLI Reference +# TiDB Cloud CLI Command Reference -This reference describes behavior shared across the tdc command surface. +This reference describes behavior shared across the `tdc` command surface. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax @@ -17,7 +17,7 @@ This reference describes behavior shared across the tdc command surface. tdc [subcommand] [required options] [optional options] [global options] ``` -tdc accepts long flags only. A one-letter flag such as `-p` is rejected. +The `tdc` executable accepts long flags only. A one-letter flag such as `-p` is rejected. ## Command tree @@ -216,7 +216,7 @@ The following task-oriented guides explain how commands work together. They are | Guide | Purpose | | --- | --- | -| [Install, Configure, and Update](/ai/tdc/reference/tdc-install-configure-update.md) | Install releases, configure profiles, update, and uninstall tdc | +| [Install, Configure, and Update](/ai/tdc/reference/tdc-install-configure-update.md) | Install releases, configure profiles, update, and uninstall `tdc` | | [Organization and Projects](/ai/tdc/reference/tdc-organization.md) | Inspect projects and understand virtual-project selection | | [Starter Databases and SQL](/ai/tdc/reference/tdc-starter-database.md) | Manage Starter clusters, branches, and SQL | | [Filesystem](/ai/tdc/reference/tdc-filesystem.md) | Manage Filesystems, files, layers, packs, and mounts | @@ -255,5 +255,5 @@ Aliases use the same long flags, authentication, output, query, and error behavi ## Related documentation -- [Install, Configure, and Update tdc](/ai/tdc/reference/tdc-install-configure-update.md) -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [Install, Configure, and Update TiDB Cloud CLI](/ai/tdc/reference/tdc-install-configure-update.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md index 4bda5c77fe2e7..3a8e6e8ab3a32 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -1,15 +1,15 @@ --- -title: tdc Configuration and Credentials -summary: Reference tdc profiles, environment and flag precedence, local state paths, Filesystem registry, SQL credentials, mount locators, and operation logs. +title: TiDB Cloud CLI Configuration and Credentials +summary: Reference TiDB Cloud CLI profiles, precedence rules, local state paths, Filesystem registry, SQL credentials, mount locators, and operation logs. --- -# tdc Configuration and Credentials +# TiDB Cloud CLI Configuration and Credentials -tdc stores all product-owned local state under `~/.tdc/` and separates non-sensitive configuration from credentials. +`tdc` stores all product-owned local state under `~/.tdc/` and separates non-sensitive configuration from credentials. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Main files @@ -51,7 +51,7 @@ Credential selection is: 1. `TDC_PUBLIC_KEY` and `TDC_PRIVATE_KEY`, when either is set; 2. the selected section of `~/.tdc/credentials`. -Both environment values are required together. tdc never mixes one environment half with one file half. +Both environment values are required together. `tdc` never mixes one environment half with one file half. Placement selection is: @@ -88,7 +88,7 @@ Resource selection is: 2. `TDC_FS_FILE_SYSTEM_NAME`; 3. fail with `fs.missing_file_system_name`. -tdc never infers a Filesystem from a saved default or from the number of registered resources. Use `--file-system-name` for one command or `TDC_FS_FILE_SYSTEM_NAME` for a shell, sandbox, or automation environment. +`tdc` never infers a Filesystem from a saved default or from the number of registered resources. Use `--file-system-name` for one command or `TDC_FS_FILE_SYSTEM_NAME` for a shell, sandbox, or automation environment. FS owner credential selection for remote `fs`, `fs-git`, `fs-journal`, and owner `fs-vault` operations is: @@ -108,7 +108,7 @@ export TDC_REGION_CODE="aws-us-east-1" export TDC_FS_FILE_SYSTEM_NAME="workspace" ``` -These values form an in-memory namespace only. tdc does not write them to `~/.tdc/`. Provisioning and deletion still require TiDB Cloud API credentials; deletion also requires the local resource registration. +These values form an in-memory namespace only. `tdc` does not write them to `~/.tdc/`. Provisioning and deletion still require TiDB Cloud API credentials; deletion also requires the local resource registration. ## DB SQL credentials @@ -142,7 +142,7 @@ Each registered Filesystem has an isolated companion home: ~/.tdc/drive9-home/// ``` -Do not edit this state or a standalone `~/.drive9` configuration for tdc workflows. +Do not edit this state or a standalone `~/.drive9` configuration for `tdc` workflows. A successful background FS or vault mount writes a non-secret locator: @@ -154,7 +154,7 @@ The locator records the placement and companion-home information required for dr ## Operation logs -tdc writes redacted local JSON Lines events to: +`tdc` writes redacted local JSON Lines events to: ```text ~/.tdc/logs/tdc.jsonl @@ -190,5 +190,5 @@ Do not put them in source control, tickets, logs, command examples, or unprotect ## Related documentation -- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) -- [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-daily-workflow-example.md b/ai/tdc/reference/tdc-daily-workflow-example.md index 397b7607a6cf8..fd649fbb6f6bf 100644 --- a/ai/tdc/reference/tdc-daily-workflow-example.md +++ b/ai/tdc/reference/tdc-daily-workflow-example.md @@ -1,19 +1,19 @@ --- -title: Run a Daily tdc Workflow -summary: Inspect projects, manage a Starter cluster and Filesystem, check for tdc updates, and clean up resources. +title: Run a Daily TiDB Cloud CLI Workflow +summary: Inspect projects, manage a Starter cluster and Filesystem, check for TiDB Cloud CLI updates, and clean up resources. --- -# Run a Daily tdc Workflow +# Run a Daily TiDB Cloud CLI Workflow This example follows a typical operator workflow across TiDB Cloud Starter and TiDB Cloud Filesystem. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Prerequisites -- Install tdc and run `tdc configure`. +- Install `tdc` and run `tdc configure`. - Ensure your organization has capacity for one Starter cluster and one Filesystem. ## Step 1. Inspect the active account @@ -99,7 +99,7 @@ tdc db delete-db-cluster \ --db-cluster-id "" ``` -Deleting local tdc configuration is not a substitute for deleting remote resources. +Deleting local TiDB Cloud CLI configuration is not a substitute for deleting remote resources. ## Security notes @@ -109,5 +109,5 @@ Deleting local tdc configuration is not a substitute for deleting remote resourc ## What's next -- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/tdc-filesystem-git.md b/ai/tdc/reference/tdc-filesystem-git.md index 260a91444935e..a76b214ae0cc9 100644 --- a/ai/tdc/reference/tdc-filesystem-git.md +++ b/ai/tdc/reference/tdc-filesystem-git.md @@ -1,15 +1,15 @@ --- -title: tdc fs-git Command Reference -summary: Reference every tdc fs-git command for cloning, hydrating, and managing linked Git worktrees. +title: TiDB Cloud Filesystem Git CLI Command Reference +summary: Reference every `tdc fs-git` command for cloning, hydrating, and managing linked Git worktrees. --- -# tdc fs-git Command Reference +# TiDB Cloud Filesystem Git CLI Command Reference `tdc fs-git` accelerates Git workspace setup on mounted TiDB Cloud Filesystem paths. It augments Git; you continue to use ordinary `git` commands for status, edit, add, commit, fetch, and push. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree @@ -113,4 +113,4 @@ The default coding-agent mount profile keeps `.git` and rebuildable generated fi ## What's next - [Prepare a Git Workspace for Agents](/ai/tdc/reference/tdc-git-workspace-for-agents-example.md) -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/tdc-filesystem-journal.md b/ai/tdc/reference/tdc-filesystem-journal.md index 658cb74c2f3bd..6bfc9c2d6d976 100644 --- a/ai/tdc/reference/tdc-filesystem-journal.md +++ b/ai/tdc/reference/tdc-filesystem-journal.md @@ -1,15 +1,15 @@ --- -title: tdc fs-journal Command Reference -summary: Reference every tdc fs-journal command for creating, appending, reading, searching, and verifying journals. +title: TiDB Cloud Filesystem Journal CLI Command Reference +summary: Reference every `tdc fs-journal` command for creating, appending, reading, searching, and verifying journals. --- -# tdc fs-journal Command Reference +# TiDB Cloud Filesystem Journal CLI Command Reference `tdc fs-journal` provides an append-only, verifiable ledger for agent and workflow events. Unlike a mutable text file, a journal assigns ordered sequence numbers, supports structured search, and maintains a hash chain that can detect alteration. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree @@ -58,7 +58,7 @@ tdc fs-journal append-journal-entries \ --entry-json '{"type":"tool.called","tool":"tdc"}' ``` -Use `--entry-type` as a default for entries without `type`, and add `--source` or repeatable `--subject` metadata. `--idempotency-key` makes a retry deterministic; tdc generates one when omitted. +Use `--entry-type` as a default for entries without `type`, and add `--source` or repeatable `--subject` metadata. `--idempotency-key` makes a retry deterministic; the CLI generates one when omitted. For pipelines, send JSON Lines on stdin, or use `--json-array` for a JSON array. @@ -98,4 +98,4 @@ Verification recalculates the ordered hash chain and reports whether the entries ## What's next - [Record an Agent Workflow in a Journal](/ai/tdc/reference/tdc-journal-agent-workflow-example.md) -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-filesystem-vault.md b/ai/tdc/reference/tdc-filesystem-vault.md index 1fbb583f6b0ea..5b6cade6937d8 100644 --- a/ai/tdc/reference/tdc-filesystem-vault.md +++ b/ai/tdc/reference/tdc-filesystem-vault.md @@ -1,15 +1,15 @@ --- -title: tdc fs-vault Command Reference -summary: Reference every tdc fs-vault command for secrets, grants, audit events, process injection, and read-only mounts. +title: TiDB Cloud Filesystem Vault CLI Command Reference +summary: Reference every `tdc fs-vault` command for secrets, grants, audit events, process injection, and read-only mounts. --- -# tdc fs-vault Command Reference +# TiDB Cloud Filesystem Vault CLI Command Reference `tdc fs-vault` stores structured secrets and delegates limited, expiring access to agents. Owner operations use the Filesystem owner credential; delegated reads use a vault token scoped to selected secrets or fields. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree @@ -162,11 +162,11 @@ Unmount also supports `--timeout`, `--force`, and `--ignore-absent`. Vault mount - Give an agent the narrowest field scope and shortest practical TTL. - Prefer `run-with-secret` over writing plaintext to disk. -- Do not store delegated tokens in tdc config or operation logs. +- Do not store delegated tokens in TiDB Cloud CLI configuration or operation logs. - Stop processes using a vault mount before unmounting. - Revoke a grant after the task finishes. ## What's next - [Delegate Secrets to an Agent](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) -- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/reference/tdc-filesystem.md b/ai/tdc/reference/tdc-filesystem.md index 0ceb839d62528..ad22207fe6ab8 100644 --- a/ai/tdc/reference/tdc-filesystem.md +++ b/ai/tdc/reference/tdc-filesystem.md @@ -1,15 +1,15 @@ --- -title: tdc fs Command Reference -summary: Reference every tdc fs command for Filesystem resources, files, layers, packs, and mounts. +title: TiDB Cloud Filesystem CLI Command Reference +summary: Reference every `tdc fs` command for Filesystem resources, files, layers, packs, and mounts. --- -# tdc fs Command Reference +# TiDB Cloud Filesystem CLI Command Reference Use `tdc fs` to provision TiDB Cloud Filesystem resources and access their data from commands or local mounts. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree @@ -100,7 +100,7 @@ tdc fs ## Prerequisites - Run `tdc configure` before provisioning or deleting a Filesystem. -- Install tdc with the release installer so the `tdc-drive9` companion is next to the `tdc` binary. +- Install `tdc` with the release installer so the `tdc-drive9` companion is next to the `tdc` binary. - Treat the returned FS owner token as a secret. Data-plane commands can instead use an existing Filesystem with `TDC_FS_TOKEN`, `TDC_REGION_CODE`, and `TDC_FS_FILE_SYSTEM_NAME`, without TiDB Cloud API keys. @@ -115,7 +115,7 @@ tdc fs create-file-system \ --wait ``` -Without `--wait`, tdc returns after Drive9 accepts provisioning. With the flag, tdc waits up to 10 minutes until the root is readable through the public Drive9 data-plane CLI. A failed wait leaves the resource and locally stored credential intact. +Without `--wait`, `tdc` returns after Drive9 accepts provisioning. With the flag, `tdc` waits up to 10 minutes until the root is readable through the public Drive9 data-plane CLI. A failed wait leaves the resource and locally stored credential intact. The JSON response includes `fs_token`. Capture it without displaying the complete result: @@ -153,7 +153,7 @@ tdc fs delete-file-system \ --file-system-name workspace ``` -Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and a locally registered resource; an FS token alone cannot delete the resource. Drive9 deletion is asynchronous, so a successfully accepted request reports `status: "deleting"` while tdc removes the selected local registry entry and credential. +Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and a locally registered resource; an FS token alone cannot delete the resource. Drive9 deletion is asynchronous, so a successfully accepted request reports `status: "deleting"` while `tdc` removes the selected local registry entry and credential. ## Select one of multiple Filesystems @@ -163,7 +163,7 @@ One profile can own multiple resources. Selection precedence is: 2. `TDC_FS_FILE_SYSTEM_NAME`; 3. fail with `fs.missing_file_system_name`. -tdc does not infer a resource from the profile registry, even when only one resource is registered. This makes scripts deterministic when resources are added or removed. +`tdc` does not infer a resource from the profile registry, even when only one resource is registered. This makes scripts deterministic when resources are added or removed. ## Copy and read data @@ -305,7 +305,7 @@ The default `--driver auto` is platform-specific. `--remote-path` exposes a subt ### Mount in Docker and Docker Compose -Installing FUSE3 inside an image does not enable mounts by itself. The Docker host must provide `/dev/fuse`, and the container must receive permission to perform the mount. The following Dockerfile installs the required Ubuntu package and tdc without storing any cloud or Filesystem credentials in the image: +Installing FUSE3 inside an image does not enable mounts by itself. The Docker host must provide `/dev/fuse`, and the container must receive permission to perform the mount. The following Dockerfile installs the required Ubuntu package and `tdc` without storing any cloud or Filesystem credentials in the image: ```dockerfile FROM ubuntu:24.04 @@ -382,7 +382,7 @@ docker compose run --rm agent > **Warning:** > -> `SYS_ADMIN` and an unconfined AppArmor profile weaken container isolation. Use them only for a dedicated, trusted agent container. Rootless Docker and managed container platforms might prohibit these settings; use tdc fs data-plane commands without a mount when FUSE cannot be granted. The mount exists in the container mount namespace and disappears when the container stops, so wait for graceful unmount to succeed before stopping a container that might have pending writes. +> `SYS_ADMIN` and an unconfined AppArmor profile weaken container isolation. Use them only for a dedicated, trusted agent container. Rootless Docker and managed container platforms might prohibit these settings; use `tdc fs` data-plane commands without a mount when FUSE cannot be granted. The mount exists in the container mount namespace and disappears when the container stops, so wait for graceful unmount to succeed before stopping a container that might have pending writes. macOS intentionally keeps WebDAV as the automatic choice even when macFUSE is installed. To use FUSE, install a supported release from the [official macFUSE site](https://macfuse.github.io/), complete any approval or restart requested by its installer, and run: @@ -489,4 +489,4 @@ Aliases change only the command name. All flags remain long and identical to the - [Use a Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) - [Share a Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) -- [tdc fs-git Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) diff --git a/ai/tdc/reference/tdc-git-workspace-for-agents-example.md b/ai/tdc/reference/tdc-git-workspace-for-agents-example.md index e6e9b67099152..4b87bd1756ad5 100644 --- a/ai/tdc/reference/tdc-git-workspace-for-agents-example.md +++ b/ai/tdc/reference/tdc-git-workspace-for-agents-example.md @@ -9,7 +9,7 @@ This example removes a large repository clone from the critical path of starting > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem @@ -19,9 +19,9 @@ An ephemeral agent normally waits for `git clone` and checkout to download a rep A normal clone blocks until the initial object transfer and checkout finish. A native blobless partial clone reduces the first transfer, but later Git commands and file reads can still trigger repeated on-demand fetches on the agent's critical path. Neither approach by itself provides a shared Filesystem workspace that can be restored across agent runtimes. -## How tdc changes the workflow +## How TiDB Cloud CLI changes the workflow -`tdc fs-git clone-git-workspace --blobless --hydrate background` registers the Git workspace and exposes its file tree before all clean blobs finish downloading. The command returns so the agent can inspect paths and start working while tdc hydrates the clean tree and local Git object database in the background. Reads that arrive before hydration completes fall back to Git's lazy fetch for correctness. Ordinary Git remains responsible for edits, commits, fetches, and pushes. +`tdc fs-git clone-git-workspace --blobless --hydrate background` registers the Git workspace and exposes its file tree before all clean blobs finish downloading. The command returns so the agent can inspect paths and start working while `tdc` hydrates the clean tree and local Git object database in the background. Reads that arrive before hydration completes fall back to Git's lazy fetch for correctness. Ordinary Git remains responsible for edits, commits, fetches, and pushes. ## Prerequisites @@ -93,11 +93,11 @@ Use `--force` for worktree removal only when uncommitted changes can be discarde ## Security and durability notes -- Repository credentials are managed by Git, not tdc. +- Repository credentials are managed by Git, not `tdc`. - The coding-agent profile keeps `.git` and ignored generated files locally for performance. - Preserve or pack local overlay state before deleting an ephemeral machine when it cannot be rebuilt. ## What's next -- [tdc fs-git Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/tdc-install-configure-update.md b/ai/tdc/reference/tdc-install-configure-update.md index c84bd0ddc02cd..fd76fd0f2309c 100644 --- a/ai/tdc/reference/tdc-install-configure-update.md +++ b/ai/tdc/reference/tdc-install-configure-update.md @@ -1,15 +1,15 @@ --- -title: tdc Installation, Configuration, and Update Command Reference -summary: Reference tdc release installation, configure and update commands, version checks, and uninstallation. +title: Install, Configure, and Update TiDB Cloud CLI +summary: Install TiDB Cloud CLI releases, configure profiles, check versions, apply updates, and uninstall the CLI. --- -# tdc Installation, Configuration, and Update Command Reference +# Install, Configure, and Update TiDB Cloud CLI This reference documents the supported release installers, top-level configuration and update commands, help and version behavior, and uninstallation. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree @@ -26,7 +26,7 @@ tdc Run `tdc configure help` or `tdc update help` for the complete generated flag list. -## Install tdc +## Install TiDB Cloud CLI ### macOS and Linux @@ -36,7 +36,7 @@ Run the installer: 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: +After installation, add `tdc` to the current shell and verify it: ```bash export PATH="$HOME/.tdc/bin:$PATH" @@ -55,24 +55,24 @@ iwr https://github.com/tidbcloud/tdc/releases/latest/download/install.ps1 -OutFi powershell -ExecutionPolicy Bypass -File $script -Yes ``` -After installation, add tdc to the current PowerShell session and verify it: +After installation, add `tdc` to the current PowerShell session and verify it: ```powershell $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. +Add `$HOME\.tdc\bin` to your user `PATH` to keep `tdc` available in new PowerShell sessions. ## Configure a profile -Interactive configuration is the only tdc workflow that prompts: +Interactive configuration is the only TiDB Cloud CLI workflow that prompts: ```bash tdc configure ``` -tdc requests a TiDB Cloud API public key, private key, and canonical region code. It validates the key by listing projects and records the unique `tidbx_virtual` project as the profile's default project. +The TiDB Cloud CLI requests a TiDB Cloud API public key, private key, and canonical region code. It validates the key by listing projects and records the unique `tidbx_virtual` project as the profile's default project. Configure a named profile: @@ -109,9 +109,9 @@ tdc --version tdc fs --version ``` -Required flags appear before optional flags in generated usage. tdc supports long flags only. +Required flags appear before optional flags in generated usage. The TiDB Cloud CLI supports long flags only. -## Update tdc +## Update TiDB Cloud CLI Check without changing files: @@ -132,7 +132,7 @@ tdc update --dry-run tdc update ``` -Install a specific tdc release: +Install a specific TiDB Cloud CLI release: ```bash tdc update --target-version v0.1.2 @@ -147,7 +147,7 @@ tdc update For WebDAV, close writers and unmount. Use the FUSE-only drain command separately only when you need a durability barrier without unmounting. Installations in protected or package-manager-owned locations are not modified. Run the installer once to migrate an older `/usr/local/bin` installation to `~/.tdc/bin`. -## Uninstall tdc +## Uninstall TiDB Cloud CLI Remove only the binaries: @@ -161,7 +161,7 @@ On Windows: Remove-Item "$HOME\.tdc\bin\tdc.exe", "$HOME\.tdc\bin\tdc-drive9.exe" ``` -Removing binaries preserves profiles, credentials, Filesystem registrations, DB SQL credentials, logs, and mount locators. Remove `~/.tdc/` only when you intend to delete all local tdc state: +Removing binaries preserves profiles, credentials, Filesystem registrations, DB SQL credentials, logs, and mount locators. Remove `~/.tdc/` only when you intend to delete all local TiDB Cloud CLI state: ```bash rm -rf "$HOME/.tdc" @@ -171,6 +171,6 @@ Deleting local state does not delete remote Starter clusters or Filesystem resou ## What's next -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) -- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/tdc-journal-agent-workflow-example.md b/ai/tdc/reference/tdc-journal-agent-workflow-example.md index 54d8098c5c318..f7d6c0b0f16ed 100644 --- a/ai/tdc/reference/tdc-journal-agent-workflow-example.md +++ b/ai/tdc/reference/tdc-journal-agent-workflow-example.md @@ -1,15 +1,15 @@ --- -title: Record an Agent Workflow in a Filesystem Journal +title: Record an Agent Workflow in a TiDB Cloud Filesystem Journal summary: Create a journal, append structured agent events, search the workflow, and verify the journal hash chain. --- -# Record an Agent Workflow in a Filesystem Journal +# Record an Agent Workflow in a TiDB Cloud Filesystem Journal This example records an agent task as a structured, ordered, and verifiable event history. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem @@ -19,7 +19,7 @@ An agent task can span planning, tool calls, tests, retries, and handoffs betwee A text file can be edited or truncated after an event is written, has no intrinsic sequence or hash chain, and requires every producer to invent parsing and concurrency rules. Retrying an append can also create duplicate events unless the application builds its own idempotency layer. -## How tdc changes the workflow +## How TiDB Cloud CLI changes the workflow A Filesystem journal stores structured append-only entries with sequence information, searchable fields, optional idempotency keys, and hash-chain verification. Agents append semantic events such as `task.started` and `test.finished`; operators can query the workflow and verify the stored chain without treating a mutable log file as evidence. @@ -83,7 +83,7 @@ A successful result confirms the stored sequence and hash chain are consistent. ## Cleanup -Journals are append-only and currently have no delete command in the tdc public surface. Use a synthetic journal ID and retain it as workflow evidence. Delete the containing Filesystem only when its complete contents are no longer needed. +Journals are append-only and currently have no delete command in the public `tdc` command surface. Use a synthetic journal ID and retain it as workflow evidence. Delete the containing Filesystem only when its complete contents are no longer needed. ## Security notes @@ -92,5 +92,5 @@ Journals are append-only and currently have no delete command in the tdc public ## What's next -- [tdc fs-journal Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) - [Delegate Secrets to an Agent](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) diff --git a/ai/tdc/reference/tdc-organization.md b/ai/tdc/reference/tdc-organization.md index 5ec7471c18f4b..30bd9e46b78c8 100644 --- a/ai/tdc/reference/tdc-organization.md +++ b/ai/tdc/reference/tdc-organization.md @@ -1,15 +1,15 @@ --- -title: tdc organization Command Reference -summary: Reference the tdc organization command tree, project listing inputs, output, and examples. +title: TiDB Cloud Organization CLI Command Reference +summary: Reference the `tdc organization` command tree, project listing inputs, output, and examples. --- -# tdc organization Command Reference +# TiDB Cloud Organization CLI Command Reference Use `tdc organization` to inspect the projects accessible to the configured TiDB Cloud API key. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree @@ -69,5 +69,5 @@ tdc db create-db-cluster \ ## What's next -- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-parallel-agent-dataset-example.md b/ai/tdc/reference/tdc-parallel-agent-dataset-example.md index 1a8a483256f44..9fdec6030c75f 100644 --- a/ai/tdc/reference/tdc-parallel-agent-dataset-example.md +++ b/ai/tdc/reference/tdc-parallel-agent-dataset-example.md @@ -1,21 +1,21 @@ --- -title: Share a Read-Only Dataset Across Parallel Agents with tdc +title: Share a Read-Only Dataset Across Parallel Agents with TiDB Cloud Filesystem summary: Upload one unstructured dataset and expose the same read-only mounted namespace to multiple agent workers. --- -# Share a Read-Only Dataset Across Parallel Agents with tdc +# Share a Read-Only Dataset Across Parallel Agents with TiDB Cloud Filesystem This scenario gives multiple short-lived workers one shared corpus without copying it into every sandbox. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## The problem Parallel document-processing or evaluation agents often need the same PDFs, images, logs, or model artifacts. Downloading the complete corpus into every worker delays startup, duplicates storage, and leaves each worker with a different point-in-time copy. -## How tdc changes the workflow +## How TiDB Cloud CLI changes the workflow An owner uploads the corpus once. Every worker selects the same Filesystem and mounts it read-only, so ordinary tools can traverse a common namespace. Workers write results to separate task paths or a different output Filesystem. @@ -77,6 +77,6 @@ tdc fs unmount-file-system --mount-path "$HOME/corpus" ## Related reference -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) - [Use a Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) -- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/reference/tdc-persistent-agent-state-example.md b/ai/tdc/reference/tdc-persistent-agent-state-example.md index 471b6813184dd..d91d501e2c28b 100644 --- a/ai/tdc/reference/tdc-persistent-agent-state-example.md +++ b/ai/tdc/reference/tdc-persistent-agent-state-example.md @@ -1,21 +1,21 @@ --- -title: Persist Agent State Across Disposable Sandboxes with tdc +title: Persist Agent State Across Disposable Sandboxes with TiDB Cloud Filesystem summary: Preserve plans, checkpoints, outputs, and workflow history in a TiDB Cloud Filesystem while replacing agent sandboxes. --- -# Persist Agent State Across Disposable Sandboxes with tdc +# Persist Agent State Across Disposable Sandboxes with TiDB Cloud Filesystem This scenario keeps an agent's durable state in TiDB Cloud Filesystem while its compute environment remains disposable. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## The problem An agent sandbox can disappear after a timeout, failure, or deployment. Plans, intermediate results, and diagnostic files stored only on its local disk disappear with it. Keeping the sandbox alive only to preserve state ties storage durability to compute lifecycle and wastes resources. -## How tdc changes the workflow +## How TiDB Cloud CLI changes the workflow A trusted machine provisions one Filesystem. Each sandbox receives only the Filesystem token, region code, and name. The agent writes durable task state to the remote namespace and records workflow transitions in a journal. A replacement sandbox can read both without receiving TiDB Cloud control-plane keys. @@ -79,6 +79,6 @@ Continue writing results under the same task path. Use a unique task ID so paral ## Related reference -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [tdc fs-journal Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-query-sql-with-roles-example.md b/ai/tdc/reference/tdc-query-sql-with-roles-example.md index d4e8c259395ed..945efc1657456 100644 --- a/ai/tdc/reference/tdc-query-sql-with-roles-example.md +++ b/ai/tdc/reference/tdc-query-sql-with-roles-example.md @@ -1,6 +1,6 @@ --- title: Query TiDB Cloud Starter with Explicit SQL Roles -summary: Prepare tdc-managed SQL users and run read-only, read-write, and admin statements with clear privilege intent. +summary: Prepare TiDB Cloud CLI-managed SQL users and run read-only, read-write, and admin statements with explicit privilege intent. --- # Query TiDB Cloud Starter with Explicit SQL Roles @@ -9,7 +9,7 @@ This example lets an agent perform schema, data, and verification work while mak > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem @@ -19,13 +19,13 @@ An agent that can inspect data often also needs to apply a migration or update a TiDB supports SQL privileges, but a conventional client session uses the privileges of the one credential used to connect. Users must create, store, and switch among credentials themselves, and an agent can silently keep using an overly privileged connection across task phases. -## How tdc changes the workflow +## How TiDB Cloud CLI changes the workflow `tdc db create-db-sql-users` creates stable read-only, read-write, and admin identities and stores their credentials locally. Each `execute-sql-statement` invocation selects one role explicitly, uses the corresponding credential, and executes one statement. The agent can therefore use admin for schema changes, read-write for data changes, and read-only for verification without handling passwords directly. ## Prerequisites -- Configure tdc. +- Configure `tdc`. - Select an active Starter cluster ID. ## Step 1. Prepare users @@ -105,11 +105,11 @@ rm -f .env.tidb ## Security notes - Use the least privileged explicit role for each statement. -- tdc accepts one SQL statement per invocation. +- `tdc` accepts one SQL statement per invocation. - HTTPS is the default transport; `--transport mysql` is an explicit fallback. - Connection strings and environment output contain credentials. ## What's next -- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/tdc/reference/tdc-regions-security-and-limitations.md index 612701e9ef24d..e8ae67db9b044 100644 --- a/ai/tdc/reference/tdc-regions-security-and-limitations.md +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -1,19 +1,19 @@ --- -title: tdc Regions, Security, and Limitations -summary: Reference supported regions, authentication boundaries, platform dependencies, Preview constraints, and Filesystem companion behavior. +title: TiDB Cloud CLI Regions, Security, and Limitations +summary: Reference supported regions, authentication boundaries, platform dependencies, preview constraints, and Filesystem companion behavior. --- -# tdc Regions, Security, and Limitations +# TiDB Cloud CLI Regions, Security, and Limitations -This reference describes current placement, authentication, platform, and Preview boundaries. +This reference describes current placement, authentication, platform, and preview boundaries. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## TiDB Cloud regions -tdc accepts one canonical region code: +The TiDB Cloud CLI accepts one canonical region code: | Canonical code | Provider | Location | | --- | --- | --- | @@ -24,7 +24,7 @@ tdc accepts one canonical region code: | `aws-ap-southeast-1` | AWS | Singapore | | `ali-ap-southeast-1` | Alibaba Cloud | Singapore | -Alibaba Cloud currently supports only Singapore in tdc. Users cannot configure raw service URLs. +Alibaba Cloud currently supports only the Singapore region in the TiDB Cloud CLI. Users cannot configure raw service URLs. ## Filesystem regions @@ -37,7 +37,7 @@ Filesystem endpoint availability is resolved from the hosted Drive9 region manif | AWS | `aws-us-west-2` | | Alibaba Cloud | `ali-ap-southeast-1` | -The hosted manifest is authoritative and can change during Preview. A profile in another TiDB Cloud region can manage Starter databases but receives an unsupported Filesystem endpoint error until that placement appears in the manifest. +The hosted manifest is authoritative and can change during preview. A profile in another TiDB Cloud region can manage Starter databases but receives an unsupported Filesystem endpoint error until that placement appears in the manifest. ## Credential requirements @@ -61,7 +61,7 @@ TiDB Cloud API calls use Digest authentication. SQL HTTPS execution uses generat - Use `--read-only` for SQL inspection by untrusted or exploratory agents. Use `--admin` only for DDL or privilege management, and use `--read-write` only when data changes are intended. - Use `--dry-run` before destructive control-plane operations. Keep `~/.tdc/credentials`, resource credentials, and DB SQL credentials owner-readable only. - Grant Docker access to `/dev/fuse`, `SYS_ADMIN`, and an unconfined AppArmor profile only to dedicated, trusted containers. These settings reduce container isolation. -- Review local operation logs before sharing diagnostics. tdc redacts known secret classes, but SQL text, resource names, paths, and operational context can still be sensitive. +- Review local operation logs before sharing diagnostics. `tdc` redacts known secret classes, but SQL text, resource names, paths, and operational context can still be sensitive. ## Mount platform limitations @@ -71,9 +71,9 @@ TiDB Cloud API calls use Digest authentication. SQL HTTPS execution uses generat | Linux | FUSE | Requires FUSE3 and `/dev/fuse`; explicit WebDAV requires `davfs2` | | Windows | WebDAV | Requires the WebClient service and a drive-letter mount path; FUSE and vault mount are unavailable | -FUSE and WebDAV are implemented by the bundled [Drive9](https://github.com/mem9-ai/drive9) companion. tdc does not fall back to a separate native mount implementation. +FUSE and WebDAV are implemented by the bundled [Drive9](https://github.com/mem9-ai/drive9) companion. The TiDB Cloud CLI does not fall back to a separate native mount implementation. -Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path under `$HOME` or `/mnt`; `/workspace` requires an explicit local AppArmor rule even when tdc runs as root. +Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path under `$HOME` or `/mnt`; `/workspace` requires an explicit local AppArmor rule even when `tdc` runs as root. ## Durability limitations @@ -82,22 +82,22 @@ Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path - `drain-file-system` is a FUSE-only online durability barrier that leaves the mount active. - Abruptly killing the mount process or deleting a machine can lose uncommitted memory/write-back state. - The default coding-agent mount profile stores dependency trees, generated output, caches, and Git internals locally. Local-only data disappears when its disk disappears unless it is packed or otherwise preserved. -- A running mount remains on the companion version loaded at mount time. Unmount and remount after updating tdc. +- A running mount remains on the companion version loaded at mount time. Unmount and remount after updating the TiDB Cloud CLI. - Remote-committed Filesystem data survives client or sandbox deletion; deleting the machine does not delete the remote resource. ## Product limitations -- tdc is Preview and command contracts can change. +- The TiDB Cloud CLI is in preview, and command contracts can change. - Database management targets TiDB Cloud Starter, not every TiDB Cloud cluster tier. - SQL execution accepts one statement per invocation. - Read-write is the default SQL role; use explicit role flags in security-sensitive automation. - Journals are append-only and the current public command surface has no journal delete command. - Filesystem resource list and describe commands operate on the local registry; they are not an organization-wide discovery API. - Telemetry commands, serverless-function deployment, Homebrew, and Scoop distribution are not implemented. -- tdc depends on its installed `tdc-drive9` companion for all public Filesystem runtime behavior. +- The TiDB Cloud CLI depends on its installed `tdc-drive9` companion for all public Filesystem runtime behavior. ## Related documentation -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) -- [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md b/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md index d16c195413d2e..38a8f9a91a9bd 100644 --- a/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md +++ b/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md @@ -9,7 +9,7 @@ This example gives agents or users on two machines one shared workspace without > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem @@ -19,14 +19,14 @@ An agent can prepare source files or artifacts on machine A and continue the tas Local disks do not provide a shared namespace. Commands such as `scp` and archive upload transfer point-in-time copies rather than live state, while object storage does not by itself behave like the mounted directory expected by editors, build tools, and agents. -## How tdc changes the workflow +## How TiDB Cloud CLI changes the workflow Both machines select the same TiDB Cloud Filesystem. Data-plane commands and the mounted path address one remote namespace, so a write from either interface becomes visible through the other after it is flushed. Machine B needs only the Filesystem token, region code, and name; it does not need TiDB Cloud API keys or a copied profile. ## Prerequisites -- Machine A has configured tdc. -- Both machines have tdc installed. +- Machine A has configured `tdc`. +- Both machines have `tdc` installed. - You have a secure secret-transfer channel. ## Step 1. Create the Filesystem on machine A @@ -102,5 +102,5 @@ tdc fs delete-file-system \ ## What's next -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) - [Use a Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) diff --git a/ai/tdc/reference/tdc-starter-database.md b/ai/tdc/reference/tdc-starter-database.md index 0136464095d93..8546b3e0f97b5 100644 --- a/ai/tdc/reference/tdc-starter-database.md +++ b/ai/tdc/reference/tdc-starter-database.md @@ -1,15 +1,15 @@ --- -title: tdc db Command Reference -summary: Reference every tdc db command for Starter clusters, branches, SQL users, connection strings, and SQL execution. +title: TiDB Cloud Starter CLI Command Reference +summary: Reference every `tdc db` command for Starter clusters, branches, SQL users, connection strings, and SQL execution. --- -# tdc db Command Reference +# TiDB Cloud Starter CLI Command Reference Use `tdc db` to manage TiDB Cloud Starter clusters, branches, and SQL access. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree @@ -48,7 +48,7 @@ tdc db ## Prerequisites -- Configure tdc with `tdc configure`. +- Configure `tdc` with `tdc configure`. - Ensure the API key can manage Starter clusters in the selected project. - Use synthetic names in automation so cleanup can identify only resources created by that run. @@ -103,7 +103,7 @@ tdc db delete-db-cluster \ --wait ``` -tdc resolves the cluster name internally; no name-confirmation flag is required. Without `--wait`, delete returns after TiDB Cloud accepts the asynchronous request. The wait flag waits up to 12 minutes and returns when the cluster is `DELETED` or no longer accessible. +`tdc` resolves the cluster name internally; no name-confirmation flag is required. Without `--wait`, delete returns after TiDB Cloud accepts the asynchronous request. The wait flag waits up to 12 minutes and returns when the cluster is `DELETED` or no longer accessible. ## Manage branches @@ -139,7 +139,7 @@ Create and delete support `--dry-run`. ## Create SQL users -Create or repair the three tdc-managed SQL roles: +Create or repair the three TiDB Cloud CLI-managed SQL roles: ```bash tdc db create-db-sql-users \ @@ -218,5 +218,5 @@ The default `--transport https` sends the SQL request over HTTPS without a persi ## What's next - [Query SQL with Explicit Roles](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) -- [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) -- [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) +- [TiDB Cloud CLI Command Reference](/ai/tdc/reference/tdc-cli-reference.md) +- [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-troubleshooting.md b/ai/tdc/reference/tdc-troubleshooting.md index 4963179ba8317..505336b694dd2 100644 --- a/ai/tdc/reference/tdc-troubleshooting.md +++ b/ai/tdc/reference/tdc-troubleshooting.md @@ -1,15 +1,15 @@ --- -title: Troubleshoot tdc -summary: Diagnose tdc authentication, project, Filesystem selection, companion, quota, SQL user, mount, and interrupted-cleanup failures. +title: Troubleshoot TiDB Cloud CLI +summary: Diagnose TiDB Cloud CLI authentication, project, Filesystem selection, companion, quota, SQL user, mount, and interrupted-cleanup failures. --- -# Troubleshoot tdc +# Troubleshoot TiDB Cloud CLI -Use this reference to diagnose common current tdc failures. Add `--debug` only when needed; debug output is redacted but should still be reviewed before sharing. +Use this reference to diagnose common current TiDB Cloud CLI failures. Add `--debug` only when needed; debug output is redacted but should still be reviewed before sharing. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## API authentication fails @@ -40,7 +40,7 @@ tdc organization list-projects \ --query 'projects[].{id:id,name:name,type:type}' ``` -If no virtual project appears, confirm the API key's organization and project access. If multiple virtual projects appear, report the ambiguous account state through the [tdc issue tracker](https://github.com/tidbcloud/tdc/issues). +If no virtual project appears, confirm the API key's organization and project access. If multiple virtual projects appear, report the ambiguous account state through the [`tdc` issue tracker](https://github.com/tidbcloud/tdc/issues). ## Filesystem token is missing @@ -70,7 +70,7 @@ Or select the Filesystem for subsequent commands in the current shell: export TDC_FS_FILE_SYSTEM_NAME="workspace" ``` -tdc intentionally does not infer a Filesystem from the local registry, including when only one resource is registered. +The TiDB Cloud CLI intentionally does not infer a Filesystem from the local registry, including when only one resource is registered. ## Filesystem region is unsupported @@ -78,13 +78,13 @@ The configured TiDB Cloud region might not have a `tidb_cloud_native` Filesystem ## Companion is missing or incompatible -The release installer places `tdc-drive9` next to `tdc`. Re-run the current installer when tdc reports a missing companion: +The release installer places `tdc-drive9` next to `tdc`. Re-run the current installer when the TiDB Cloud CLI reports a missing companion: ```bash curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes ``` -Verify that `PATH` resolves the expected tdc: +Verify that `PATH` resolves the expected `tdc`: ```bash command -v tdc @@ -165,7 +165,7 @@ mkdir -p "$HOME/workspace" tdc fs mount-file-system --mount-path "$HOME/workspace" ``` -Changing the owner or mode of `/workspace` does not bypass AppArmor. If the path cannot change, add explicit `/workspace` mount and unmount rules to `/etc/apparmor.d/local/fusermount3` as described in [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md#ubuntu-2604-mount-paths). +Changing the owner or mode of `/workspace` does not bypass AppArmor. If the path cannot change, add explicit `/workspace` mount and unmount rules to `/etc/apparmor.d/local/fusermount3` as described in [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md#ubuntu-2604-mount-paths). ## Mount becomes stale after a process crash @@ -209,4 +209,4 @@ tdc fs delete-file-system \ ## Report a problem -Include the tdc version, OS and architecture, command name, stable error code, and redacted logs. Never include API keys, FS or vault tokens, DB passwords, SQL containing private data, or file contents. Report issues at [github.com/tidbcloud/tdc/issues](https://github.com/tidbcloud/tdc/issues). +Include the TiDB Cloud CLI version, OS and architecture, command name, stable error code, and redacted logs. Never include API keys, FS or vault tokens, DB passwords, SQL containing private data, or file contents. Report issues at [github.com/tidbcloud/tdc/issues](https://github.com/tidbcloud/tdc/issues). diff --git a/ai/tdc/reference/tdc-vault-agent-secrets-example.md b/ai/tdc/reference/tdc-vault-agent-secrets-example.md index b9bff1b6f0008..0524b862eea17 100644 --- a/ai/tdc/reference/tdc-vault-agent-secrets-example.md +++ b/ai/tdc/reference/tdc-vault-agent-secrets-example.md @@ -1,15 +1,15 @@ --- -title: Delegate Filesystem Vault Secrets to an Agent +title: Delegate TiDB Cloud Filesystem Vault Secrets to an Agent summary: Store a secret, grant one field to an agent, inject it into a process, audit access, and revoke the grant. --- -# Delegate Filesystem Vault Secrets to an Agent +# Delegate TiDB Cloud Filesystem Vault Secrets to an Agent This example gives an agent temporary access to one secret field without sharing the Filesystem owner token or the complete secret. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem @@ -19,7 +19,7 @@ An agent might need one API endpoint or token to complete a short task. Putting Environment variables and files can deliver a secret, but they do not create a scoped, expiring delegation or an access audit trail. A separate cloud secret manager can provide those controls, but it requires another identity, policy, and integration path for every sandbox. -## How tdc changes the workflow +## How TiDB Cloud CLI changes the workflow The Filesystem owner stores the secret once and creates a short-lived grant scoped to the required field. The agent receives only the delegated vault token and can inject the allowed value into a child process. The owner can inspect audit events and revoke the grant without rotating or exposing the Filesystem owner credential. @@ -105,5 +105,5 @@ rm -f ./api-token.txt ## What's next -- [tdc fs-vault Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) -- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/tdc-overview.md b/ai/tdc/tdc-overview.md index 0f05cb99050c8..d27eada2ac2e5 100644 --- a/ai/tdc/tdc-overview.md +++ b/ai/tdc/tdc-overview.md @@ -1,19 +1,19 @@ --- -title: TiDB Cloud CLI (tdc) Overview -summary: Learn when to use the Preview tdc command-line interface to manage TiDB Cloud Starter databases and persistent Filesystems for users, automation, and AI agents. +title: TiDB Cloud Command Line Interface Overview +summary: Learn when to use the TiDB Cloud CLI to manage TiDB Cloud Starter databases and persistent Filesystems for users, automation, and AI agents. --- -# TiDB Cloud CLI (tdc) Overview +# TiDB Cloud Command Line Interface Overview -tdc is the new TiDB Cloud command-line interface 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. +The TiDB Cloud Command Line Interface—`tdc`—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. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. -## When to use tdc +## When to use TiDB Cloud CLI -Use tdc when a workflow needs to manage TiDB Cloud from a terminal, script, CI job, or AI agent environment. Typical scenarios include: +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. @@ -22,23 +22,23 @@ Use tdc when a workflow needs to manage TiDB Cloud from a terminal, script, CI j - **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 tdc does not provide, use `ticloud`. +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`. -## tdc, ticloud, and the TiDB Cloud console +## TiDB Cloud CLI, ticloud, and the TiDB Cloud console TiDB Cloud currently has two command-line interfaces with different product scopes. `tdc` is the new CLI for Starter and TiDB Cloud Filesystem. `ticloud` remains the CLI for Essential and also supports existing Starter workflows. | Interface | Use it for | Interaction model | | --- | --- | --- | | `tdc` (Preview) | New TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows | Predictable commands, JSON output by default, and non-interactive operation except for `tdc configure` | -| `ticloud` | TiDB Cloud Essential and operations not available in tdc, such as import, export, and audit-log commands | Traditional CLI workflows with interactive and non-interactive modes | +| `ticloud` | TiDB Cloud Essential and operations not available in the TiDB Cloud CLI, such as import, export, and audit-log commands | Traditional CLI workflows with interactive and non-interactive modes | | TiDB Cloud console | Visual resource inspection, guided setup, and manual operations | Browser-based and interactive | -New Starter and Filesystem automation should use tdc. Use `ticloud` for Essential and any command that has no tdc equivalent. tdc replaces `ticloud` only for the Starter workflows that tdc supports; it does not replace `ticloud` for Essential. +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 tdc manages +## What TiDB Cloud CLI manages -tdc covers the following functional areas: +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; @@ -46,7 +46,7 @@ tdc covers the following functional areas: - Filesystem layers, packs, Git workspaces, journals, and vault operations; - profiles, regional endpoint selection, local credentials, updates, structured output, and JMESPath queries. -tdc has a two-level command model: +The `tdc` executable has a two-level command model: ```text tdc @@ -54,25 +54,24 @@ tdc Examples include `tdc db list-db-clusters`, `tdc fs copy-file`, and `tdc fs-journal verify-journal`. The top-level `tdc configure` and `tdc update` commands configure and maintain the CLI. -## tdc and Drive9 +## TiDB Cloud CLI and Drive9 -tdc installs a bundled [Drive9](https://github.com/mem9-ai/drive9) companion named `tdc-drive9`. tdc owns profile selection, TiDB Cloud credentials, region and Filesystem selection, output formatting, and tdc error behavior. The companion owns Filesystem data-plane semantics, FUSE and WebDAV mounts, layers, pack and unpack, Git workspace acceleration, journals, and vault operations. +The TiDB Cloud CLI installs a bundled [Drive9](https://github.com/mem9-ai/drive9) companion named `tdc-drive9`. The TiDB Cloud CLI owns profile selection, TiDB Cloud credentials, region and Filesystem selection, output formatting, and `tdc` error behavior. The companion owns Filesystem data-plane semantics, FUSE and WebDAV mounts, layers, pack and unpack, Git workspace acceleration, journals, and vault operations. -You do not need to install, configure, or invoke Drive9 separately for normal tdc workflows. +You do not need to install, configure, or invoke Drive9 separately for normal TiDB Cloud CLI workflows. ## Find the right documentation -- Follow the [Quick Start](/ai/tdc/tdc-quick-start.md) to install tdc and complete your first Starter or Filesystem workflow. -- Use the command references for exact command trees, inputs, behavior, and examples: +Follow the [Quick Start](/ai/tdc/tdc-quick-start.md) to install the TiDB Cloud CLI and complete your first Starter or Filesystem workflow. Use these guides for task-oriented instructions: -- [Install, Configure, and Update tdc](/ai/tdc/reference/tdc-install-configure-update.md) -- [Manage Projects in TiDB Cloud Organizations with tdc](/ai/tdc/reference/tdc-organization.md) -- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [tdc fs-git Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) -- [tdc fs-journal Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) -- [tdc fs-vault Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) -- [Troubleshoot tdc](/ai/tdc/reference/tdc-troubleshooting.md) +- [Install, Configure, and Update TiDB Cloud CLI](/ai/tdc/reference/tdc-install-configure-update.md) +- [TiDB Cloud Organization CLI Command Reference](/ai/tdc/reference/tdc-organization.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) ### Scenario references @@ -80,7 +79,7 @@ Use scenarios to follow a complete workflow that combines multiple commands and For users and automation: -- [Run a Daily tdc Workflow](/ai/tdc/reference/tdc-daily-workflow-example.md) +- [Run a Daily TiDB Cloud CLI Workflow](/ai/tdc/reference/tdc-daily-workflow-example.md) - [Query SQL with Explicit Roles](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) - [Share a Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) - [Hand Off CI Artifacts Between Jobs](/ai/tdc/reference/tdc-ci-artifact-handoff-example.md) @@ -96,8 +95,8 @@ For AI agents: ### Reference -- [tdc CLI Reference](/ai/tdc/reference/tdc-cli-reference.md) -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) -- [tdc Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [TiDB Cloud CLI Command Reference](/ai/tdc/reference/tdc-cli-reference.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) -To report a problem or suggest an improvement, create an issue in the [tdc GitHub repository](https://github.com/tidbcloud/tdc/issues). +To report a problem or suggest an improvement, create an issue in the [TiDB Cloud CLI GitHub repository](https://github.com/tidbcloud/tdc/issues). diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index 515d12baf6510..a66d31659f73f 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -1,25 +1,25 @@ --- -title: Get Started with TiDB Cloud CLI (tdc) -summary: Install and configure tdc, then complete a first TiDB Cloud Starter database or Filesystem operation. +title: Get Started with TiDB Cloud CLI +summary: Install and configure the TiDB Cloud CLI, then complete a first TiDB Cloud Starter database or Filesystem operation. --- -# Get Started with TiDB Cloud CLI (tdc) +# Get Started with TiDB Cloud CLI -This quick start installs tdc, configures one profile, and gets a successful result from either TiDB Cloud Starter or TiDB Cloud Filesystem. +This quick start installs the TiDB Cloud CLI, configures one profile, and gets a successful result from either TiDB Cloud Starter or TiDB Cloud Filesystem. > **Note:** > -> tdc is currently in Preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. ## When to use this quick start -Use this quick start when you want to automate a new Starter database or create a persistent workspace for a user, script, or AI agent. It follows the tdc workflow. If you manage TiDB Cloud Essential or need an operation that tdc does not provide, use the [`ticloud` CLI documentation](/tidb-cloud/get-started-with-cli.md). +Use this quick start when you want to automate a new Starter database or create a persistent workspace for a user, script, or AI agent. It follows the TiDB Cloud CLI workflow. If you manage TiDB Cloud Essential or need an operation that the TiDB Cloud CLI does not provide, use the [`ticloud` CLI documentation](/tidb-cloud/get-started-with-cli.md). ## 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. -## Step 1. Install tdc +## Step 1. Install TiDB Cloud CLI On macOS or Linux, run the installer: @@ -27,14 +27,14 @@ On macOS or Linux, run the installer: 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: +After installation, add `tdc` to the current shell and verify it: ```bash export PATH="$HOME/.tdc/bin:$PATH" tdc --version ``` -Add `export PATH="$HOME/.tdc/bin:$PATH"` to your shell profile to keep tdc available in new terminals. +Add `export PATH="$HOME/.tdc/bin:$PATH"` to your shell profile to keep `tdc` available in new terminals. On Windows PowerShell, run the installer: @@ -44,16 +44,16 @@ iwr https://github.com/tidbcloud/tdc/releases/latest/download/install.ps1 -OutFi powershell -ExecutionPolicy Bypass -File $script -Yes ``` -After installation, add tdc to the current PowerShell session and verify it: +After installation, add `tdc` to the current PowerShell session and verify it: ```powershell $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. +Add `$HOME\.tdc\bin` to your user `PATH` to keep `tdc` available in new PowerShell sessions. -## Step 2. Configure tdc +## Step 2. Configure TiDB Cloud CLI Run the interactive configuration: @@ -84,7 +84,7 @@ tdc fs create-file-system \ --output text ``` -tdc stores the Filesystem credential locally. Write and read a file directly: +`tdc` stores the Filesystem credential locally. Write and read a file directly: ```bash printf 'hello from tdc\n' | tdc fs copy-file \ @@ -148,6 +148,6 @@ unset TDC_DB_CLUSTER_ID ## What's next -- [tdc db Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [tdc fs Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [tdc Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) From 88856e1fd307bad4dc0fad61184fcbf22e79fbb3 Mon Sep 17 00:00:00 2001 From: Cheese Date: Tue, 28 Jul 2026 15:15:24 +0800 Subject: [PATCH 18/29] docs: document global CLI preferences --- ai/tdc/reference/commands/tdc/tdc-update.md | 2 +- .../tdc-configuration-and-credentials.md | 27 ++++++++++++++----- .../tdc-regions-security-and-limitations.md | 2 +- 3 files changed, 22 insertions(+), 9 deletions(-) diff --git a/ai/tdc/reference/commands/tdc/tdc-update.md b/ai/tdc/reference/commands/tdc/tdc-update.md index 15d3cb5284811..a6200ba7ad45e 100644 --- a/ai/tdc/reference/commands/tdc/tdc-update.md +++ b/ai/tdc/reference/commands/tdc/tdc-update.md @@ -5,7 +5,7 @@ summary: Check for or install a TiDB Cloud CLI release update. # tdc update -Checks for or installs a TiDB Cloud CLI release update. This command does not read or modify profiles and credentials. +Checks for or installs a TiDB Cloud CLI release update. This command does not read or modify settings, profiles, credentials, operation logs, or other state under `~/.tdc/`. > **Note:** > diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md index 3a8e6e8ab3a32..e0d7e176ec723 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -18,11 +18,6 @@ summary: Reference TiDB Cloud CLI profiles, precedence rules, local state paths, [default] region_code = "aws-us-east-1" project_id = "..." - -[logging] -enabled = true -max_file_mb = 10 -max_files = 5 ``` ```toml @@ -34,6 +29,20 @@ tdc_private_key = "..." The credentials file uses owner-only permissions where the platform supports POSIX modes. +Global preferences are separate from profiles and credentials: + +```toml +# ~/.tdc/.preferences +schema_version = 1 + +[logging] +enabled = true +max_file_mb = 10 +max_files = 5 +``` + +The dot-prefixed preferences file is optional, hidden from ordinary directory listings, and applies to every profile. Fresh installs and `tdc configure` do not create it. Reading a user-created file does not rewrite its permissions, comments, or formatting. + ## Profile selection The profile namespace is selected in this order: @@ -168,14 +177,18 @@ Disable it for one process: TDC_LOGGING=off tdc db list-db-clusters ``` -Or configure: +Or create or edit `~/.tdc/.preferences`: ```toml +schema_version = 1 + [logging] enabled = false ``` -Environment values `off`, `false`, `0`, and `no` disable logging; `on`, `true`, `1`, and `yes` enable it. Environment takes precedence over config. +Environment values `off`, `false`, `0`, and `no` disable logging; `on`, `true`, `1`, and `yes` enable it. Environment takes precedence over settings. Invalid settings disable operation logging without failing the requested command. + +Existing installations that stored `[logging]` in `~/.tdc/config` migrate those values to `~/.tdc/.preferences` automatically. The migration preserves profiles and credentials. `tdc update` does not read or write settings, profiles, credentials, operation logs, or other state under `~/.tdc/`. ## Sensitive values diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/tdc/reference/tdc-regions-security-and-limitations.md index e8ae67db9b044..5ee9f681aee3b 100644 --- a/ai/tdc/reference/tdc-regions-security-and-limitations.md +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -61,7 +61,7 @@ TiDB Cloud API calls use Digest authentication. SQL HTTPS execution uses generat - Use `--read-only` for SQL inspection by untrusted or exploratory agents. Use `--admin` only for DDL or privilege management, and use `--read-write` only when data changes are intended. - Use `--dry-run` before destructive control-plane operations. Keep `~/.tdc/credentials`, resource credentials, and DB SQL credentials owner-readable only. - Grant Docker access to `/dev/fuse`, `SYS_ADMIN`, and an unconfined AppArmor profile only to dedicated, trusted containers. These settings reduce container isolation. -- Review local operation logs before sharing diagnostics. `tdc` redacts known secret classes, but SQL text, resource names, paths, and operational context can still be sensitive. +- Review local operation logs before sharing diagnostics. The logs exclude SQL text, paths, payloads, and credential values, but command names, flag names, profile and region metadata, status codes, and operational timing can still be sensitive. ## Mount platform limitations From c91263605fed305463b6f187fe9ce169b0da63fa Mon Sep 17 00:00:00 2001 From: Cheese Date: Wed, 29 Jul 2026 12:43:29 +0800 Subject: [PATCH 19/29] docs: document tdc telemetry controls --- .../tdc-configuration-and-credentials.md | 22 +++++++++++++++++++ .../reference/tdc-install-configure-update.md | 4 ++++ .../tdc-regions-security-and-limitations.md | 2 +- 3 files changed, 27 insertions(+), 1 deletion(-) diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md index e0d7e176ec723..046d73020fd92 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -39,6 +39,9 @@ schema_version = 1 enabled = true max_file_mb = 10 max_files = 5 + +[telemetry] +enabled = false ``` The dot-prefixed preferences file is optional, hidden from ordinary directory listings, and applies to every profile. Fresh installs and `tdc configure` do not create it. Reading a user-created file does not rewrite its permissions, comments, or formatting. @@ -190,6 +193,25 @@ Environment values `off`, `false`, `0`, and `no` disable logging; `on`, `true`, Existing installations that stored `[logging]` in `~/.tdc/config` migrate those values to `~/.tdc/.preferences` automatically. The migration preserves profiles and credentials. `tdc update` does not read or write settings, profiles, credentials, operation logs, or other state under `~/.tdc/`. +## Anonymous telemetry + +Release builds send one best-effort completion event for eligible commands to the TiDB Cloud CLI telemetry service. The event contains the canonical command and explicitly supplied flag names, stable exit and error codes, duration, region, CLI version, OS, architecture, install source, and a random pseudonymous installation ID. It does not contain flag values, credentials, tokens, SQL text, file paths or contents, command output, API payloads, profile names, or cloud resource IDs. + +Development builds and recognized CI environments default to disabled. Help, version, commandless usage, and every `tdc update` mode are always excluded. Disable telemetry persistently by adding the following global preference: + +```toml +[telemetry] +enabled = false +``` + +Disable it for one process without changing the file: + +```bash +TDC_TELEMETRY=off tdc db list-db-clusters +``` + +The TiDB Cloud CLI creates `~/.tdc/.telemetry-installation-id` lazily for the first eligible event and restricts it to the current user where POSIX permissions are available. Delete this file to reset the pseudonymous identity. Telemetry delivery is lossy and never changes command output, errors, or exit status. + ## Sensitive values Treat these as secrets: diff --git a/ai/tdc/reference/tdc-install-configure-update.md b/ai/tdc/reference/tdc-install-configure-update.md index fd76fd0f2309c..35f05c93b84cb 100644 --- a/ai/tdc/reference/tdc-install-configure-update.md +++ b/ai/tdc/reference/tdc-install-configure-update.md @@ -45,6 +45,8 @@ tdc --version The installer places `tdc` and its `tdc-drive9` companion in `~/.tdc/bin`. Add the `PATH` export to your shell profile. The installer does not require `sudo` and does not write credentials. +After installation, the installer displays the anonymous telemetry fields, prohibited data, persistent opt-out path, and process-scoped `TDC_TELEMETRY=off` override. It does not prompt for a telemetry choice or create the optional preferences file. + ### Windows Run the installer: @@ -64,6 +66,8 @@ tdc --version Add `$HOME\.tdc\bin` to your user `PATH` to keep `tdc` available in new PowerShell sessions. +The Windows installer displays the same anonymous telemetry and opt-out notice without creating a preference or installation identity. + ## Configure a profile Interactive configuration is the only TiDB Cloud CLI workflow that prompts: diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/tdc/reference/tdc-regions-security-and-limitations.md index 5ee9f681aee3b..1c018a084a04c 100644 --- a/ai/tdc/reference/tdc-regions-security-and-limitations.md +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -93,7 +93,7 @@ Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path - Read-write is the default SQL role; use explicit role flags in security-sensitive automation. - Journals are append-only and the current public command surface has no journal delete command. - Filesystem resource list and describe commands operate on the local registry; they are not an organization-wide discovery API. -- Telemetry commands, serverless-function deployment, Homebrew, and Scoop distribution are not implemented. +- Telemetry management commands are intentionally not implemented. Control telemetry through `~/.tdc/.preferences` or `TDC_TELEMETRY`; serverless-function deployment, Homebrew, and Scoop distribution are not implemented. - The TiDB Cloud CLI depends on its installed `tdc-drive9` companion for all public Filesystem runtime behavior. ## Related documentation From 865b8491b01dca7fb5319f41a866b7b82706ab01 Mon Sep 17 00:00:00 2001 From: Cheese Date: Wed, 29 Jul 2026 15:52:22 +0800 Subject: [PATCH 20/29] docs: document Starter-only DB guardrails --- .../commands/db/tdc-db-create-db-cluster-branch.md | 2 +- ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md | 2 +- .../reference/commands/db/tdc-db-create-db-sql-users.md | 2 +- .../commands/db/tdc-db-delete-db-cluster-branch.md | 2 +- ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md | 2 +- .../commands/db/tdc-db-describe-db-cluster-branch.md | 2 +- .../reference/commands/db/tdc-db-describe-db-cluster.md | 2 +- .../reference/commands/db/tdc-db-execute-sql-statement.md | 2 +- .../commands/db/tdc-db-format-db-connection-string.md | 2 +- .../commands/db/tdc-db-list-db-cluster-branches.md | 2 +- ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md | 2 +- ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md | 2 +- ai/tdc/reference/tdc-starter-database.md | 8 ++++++-- 13 files changed, 18 insertions(+), 14 deletions(-) diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md index f9818bc5758a3..933ef210ced82 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md @@ -5,7 +5,7 @@ summary: Create a branch for a TiDB Cloud Starter cluster. # tdc db create-db-cluster-branch -Creates a branch for one Starter cluster. `--wait` waits for the branch to become `ACTIVE`. +Creates a branch for one Starter cluster. `--wait` waits for the branch to become `ACTIVE`. The command verifies that the parent cluster is Starter before creating the branch. > **Note:** > diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md index a875b2cdf4d59..154973ffdb143 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md @@ -5,7 +5,7 @@ summary: Create a TiDB Cloud Starter cluster. # tdc db create-db-cluster -Creates a Starter cluster. `--db-cluster-type` defaults to `starter`, and `--wait` waits for the cluster to become `ACTIVE`. +Creates a Starter cluster. `--db-cluster-type` defaults to `starter`, and `--wait` waits for the cluster to become `ACTIVE`. The TiDB Cloud CLI validates the returned service plan; if verification fails after creation is accepted, it reports the cluster ID and retains the cluster for inspection. > **Note:** > diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md b/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md index c8ab8b983950e..8f23c8ba3f184 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md @@ -5,7 +5,7 @@ summary: Create TiDB Cloud CLI-managed SQL users for a Starter cluster. # tdc db create-db-sql-users -Idempotently creates or repairs the read-only, read-write, and admin SQL users managed by `tdc`. +Idempotently creates or repairs the read-only, read-write, and admin SQL users managed by `tdc`. The command verifies that the cluster is Starter before calling SQL-user APIs or writing local credentials. > **Note:** > diff --git a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md index 8168b376faa03..44c68ed0801d0 100644 --- a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md +++ b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md @@ -5,7 +5,7 @@ summary: Delete a branch from a TiDB Cloud Starter cluster. # tdc db delete-db-cluster-branch -Deletes one branch from a Starter cluster. +Deletes one branch from a Starter cluster. The command verifies that the parent cluster is Starter before reading or deleting the branch. > **Note:** > diff --git a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md index ea5a9a24f2f38..b5ba9b90b0ad1 100644 --- a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md @@ -5,7 +5,7 @@ summary: Delete a TiDB Cloud Starter cluster. # tdc db delete-db-cluster -Deletes one Starter cluster. `--wait` waits until deletion is observable. +Deletes one Starter cluster. `--wait` waits until deletion is observable. The command verifies the service plan before sending the delete request and rejects non-Starter or unverifiable clusters without sending `DELETE`. > **Note:** > diff --git a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md index 2b238b67d4645..087577cb449d8 100644 --- a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md +++ b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md @@ -5,7 +5,7 @@ summary: Describe a branch for a TiDB Cloud Starter cluster. # tdc db describe-db-cluster-branch -Describes one branch by cluster ID and branch ID. +Describes one branch by cluster ID and branch ID. The command verifies that the parent cluster is Starter before reading the branch. > **Note:** > diff --git a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md index 3cd01b8244c91..3255a33aee89c 100644 --- a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md @@ -5,7 +5,7 @@ summary: Describe a TiDB Cloud Starter cluster. # tdc db describe-db-cluster -Describes one Starter cluster. Use `--view FULL` to request expanded fields. +Describes one Starter cluster. Use `--view FULL` to request expanded fields. The command rejects the cluster if its API metadata does not verify it as Starter. > **Note:** > diff --git a/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md b/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md index 15520e9ec7c16..d6ccb865a371c 100644 --- a/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md +++ b/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md @@ -5,7 +5,7 @@ summary: Execute one SQL statement against a TiDB Cloud Starter cluster. # tdc db execute-sql-statement -Executes exactly one SQL statement. Read-write is the default role; explicit role selection is recommended. +Executes exactly one SQL statement. Read-write is the default role; explicit role selection is recommended. The command verifies that the cluster is Starter before loading credentials or sending an HTTPS or MySQL request. > **Note:** > diff --git a/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md b/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md index 24702c1bdbe49..1ea76a810cdc4 100644 --- a/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md +++ b/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md @@ -5,7 +5,7 @@ summary: Format a connection string for a TiDB Cloud CLI-managed SQL user. # tdc db format-db-connection-string -Formats stored SQL credentials for read-write, read-only, or admin access. +Formats stored SQL credentials for read-write, read-only, or admin access. The command verifies that the cluster is Starter before loading its local SQL credentials. > **Note:** > diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md b/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md index fa3f5af52b22a..827d670cea3c1 100644 --- a/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md +++ b/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md @@ -5,7 +5,7 @@ summary: List branches for a TiDB Cloud Starter cluster. # tdc db list-db-cluster-branches -Lists branches for one Starter cluster, with optional pagination. +Lists branches for one Starter cluster, with optional pagination. The command verifies that the parent cluster is Starter before listing branches. > **Note:** > diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md index 6cc46e8c62c81..0676a75e6111e 100644 --- a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md +++ b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md @@ -5,7 +5,7 @@ summary: List TiDB Cloud Starter clusters. # tdc db list-db-clusters -Lists Starter clusters with optional pagination, filtering, ordering, and JMESPath projection. +Lists verified Starter clusters with optional pagination, filtering, ordering, and JMESPath projection. Non-Starter and unverifiable clusters are omitted. The command preserves `next_page_token` after filtering and omits the server `total_size`, which can include other service plans. > **Note:** > diff --git a/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md index c12fa5180c69a..2088d435a6aa7 100644 --- a/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md @@ -5,7 +5,7 @@ summary: Update a TiDB Cloud Starter cluster. # tdc db update-db-cluster -Updates the display name or monthly spending limit of one Starter cluster. +Updates the display name or monthly spending limit of one Starter cluster. The command verifies the service plan before sending the update and rejects non-Starter or unverifiable clusters without sending `PATCH`. > **Note:** > diff --git a/ai/tdc/reference/tdc-starter-database.md b/ai/tdc/reference/tdc-starter-database.md index 8546b3e0f97b5..e3cb1d4778d49 100644 --- a/ai/tdc/reference/tdc-starter-database.md +++ b/ai/tdc/reference/tdc-starter-database.md @@ -5,7 +5,7 @@ summary: Reference every `tdc db` command for Starter clusters, branches, SQL us # TiDB Cloud Starter CLI Command Reference -Use `tdc db` to manage TiDB Cloud Starter clusters, branches, and SQL access. +Use `tdc db` to manage TiDB Cloud Starter clusters, branches, and SQL access. The TiDB Cloud CLI validates the cluster service plan before every cluster-scoped operation and rejects Essential or unverifiable clusters before continuing. > **Note:** > @@ -75,7 +75,7 @@ tdc db list-db-clusters --page-size 20 --order-by "createTime desc" tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name,state:state}' ``` -The list command also accepts `--page-token`, `--filter`, and `--skip`. +The list command also accepts `--page-token`, `--filter`, and `--skip`. The shared TiDB Cloud API can return multiple service plans, so the TiDB Cloud CLI filters each page to verified Starter clusters. It preserves `next_page_token` but omits `total_size`, because the server total includes clusters outside the Starter-only result. Describe and update a cluster: @@ -107,6 +107,8 @@ tdc db delete-db-cluster \ ## Manage branches +Every branch command verifies that the parent cluster is Starter before calling a branch endpoint. + Create and list branches: ```bash @@ -139,6 +141,8 @@ Create and delete support `--dry-run`. ## Create SQL users +SQL access commands verify that the target cluster is Starter before reading or writing local SQL credentials, calling SQL-user APIs, or contacting a SQL endpoint. + Create or repair the three TiDB Cloud CLI-managed SQL roles: ```bash From 73117ec57924cda6223b46ff92e38bbb9d42656d Mon Sep 17 00:00:00 2001 From: Cheese Date: Wed, 29 Jul 2026 18:43:10 +0800 Subject: [PATCH 21/29] docs: explain server-default Starter project selection --- ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md | 4 ++-- ai/tdc/reference/tdc-configuration-and-credentials.md | 4 +++- ai/tdc/reference/tdc-organization.md | 2 +- ai/tdc/reference/tdc-starter-database.md | 2 +- 4 files changed, 7 insertions(+), 5 deletions(-) diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md index 154973ffdb143..b92722a5ccf5b 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md @@ -5,7 +5,7 @@ summary: Create a TiDB Cloud Starter cluster. # tdc db create-db-cluster -Creates a Starter cluster. `--db-cluster-type` defaults to `starter`, and `--wait` waits for the cluster to become `ACTIVE`. The TiDB Cloud CLI validates the returned service plan; if verification fails after creation is accepted, it reports the cluster ID and retains the cluster for inspection. +Creates a Starter cluster. `--db-cluster-type` defaults to `starter`, and `--wait` waits for the cluster to become `ACTIVE`. Project selection uses an explicit `--project-id`, then the configured virtual project, then the TiDB Cloud account default. The TiDB Cloud CLI validates the returned service plan; if verification fails after creation is accepted, it reports the cluster ID and retains the cluster for inspection. > **Note:** > @@ -32,7 +32,7 @@ tdc db create-db-cluster - `--dry-run`: Validate the request without applying changes. - `--help`: Display help information. - `--monthly-spending-limit-usd-cents `: Monthly spending limit in USD cents; omit to use the API default. -- `--project-id `: TiDB Cloud project ID. +- `--project-id `: TiDB Cloud project ID. Overrides the configured and account defaults. - `--version`: Display version information. - `--wait`: Wait until the created cluster becomes `ACTIVE` before returning. diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md index 046d73020fd92..2c03c67035f03 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -79,7 +79,9 @@ Starter create selects a project in this order: 1. explicit non-empty `--project-id`; 2. profile `project_id` discovered by `tdc configure`; -3. fail before sending the create request. +3. omit the project label and let TiDB Cloud select the account's default project. + +An explicitly empty `--project-id` is invalid. When no project ID is available, `tdc` omits the project label entirely rather than sending an empty value. Other DB commands identify resources by cluster or branch ID and do not use `project_id`. Filesystem commands do not consume the DB project default. diff --git a/ai/tdc/reference/tdc-organization.md b/ai/tdc/reference/tdc-organization.md index 30bd9e46b78c8..c2f1967c26354 100644 --- a/ai/tdc/reference/tdc-organization.md +++ b/ai/tdc/reference/tdc-organization.md @@ -59,7 +59,7 @@ region_code = "aws-us-east-1" project_id = "..." ``` -`tdc db create-db-cluster` uses this project when `--project-id` is omitted. Pass an explicit project ID to override it for one cluster: +`tdc db create-db-cluster` uses this project when `--project-id` is omitted. If the saved ID is removed, cluster creation omits the project label and TiDB Cloud selects the account's default project. Pass an explicit project ID to override either default for one cluster: ```bash tdc db create-db-cluster \ diff --git a/ai/tdc/reference/tdc-starter-database.md b/ai/tdc/reference/tdc-starter-database.md index e3cb1d4778d49..e577cf295bc6f 100644 --- a/ai/tdc/reference/tdc-starter-database.md +++ b/ai/tdc/reference/tdc-starter-database.md @@ -65,7 +65,7 @@ tdc db create-db-cluster \ --db-cluster-name demo-cluster ``` -The configured virtual project is used unless you provide `--project-id`. `--db-cluster-type` is optional and defaults to `starter`; the only accepted explicit value is `starter`. `--monthly-spending-limit-usd-cents` is optional; setting it can require a payment method. +An explicit `--project-id` overrides the configured virtual project. If neither is available, TiDB Cloud selects the account's default project. `--db-cluster-type` is optional and defaults to `starter`; the only accepted explicit value is `starter`. `--monthly-spending-limit-usd-cents` is optional; setting it can require a payment method. List and filter clusters: From cdab1c1d90734fdc5cab70ec027b0af439cb5286 Mon Sep 17 00:00:00 2001 From: Cheese Date: Thu, 6 Aug 2026 00:11:55 +0800 Subject: [PATCH 22/29] docs: scope Starter cluster lists by region --- .../commands/db/tdc-db-list-db-clusters.md | 13 +++++++++++-- ai/tdc/reference/tdc-starter-database.md | 5 +++-- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md index 0676a75e6111e..b8320f6857697 100644 --- a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md +++ b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md @@ -5,7 +5,7 @@ summary: List TiDB Cloud Starter clusters. # tdc db list-db-clusters -Lists verified Starter clusters with optional pagination, filtering, ordering, and JMESPath projection. Non-Starter and unverifiable clusters are omitted. The command preserves `next_page_token` after filtering and omits the server `total_size`, which can include other service plans. +Lists verified Starter clusters in the effective region with optional pagination, filtering, ordering, and JMESPath projection. Cross-region, non-Starter, and unverifiable clusters are omitted. The command preserves `next_page_token` after filtering and omits the server `total_size`, which can include resources outside the verified result. > **Note:** > @@ -41,10 +41,17 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c - List clusters: ```bash - # Return all visible Starter clusters as structured JSON. + # Return Starter clusters in the profile's configured region as structured JSON. tdc db list-db-clusters ``` +- List clusters in another region: + + ```bash + # Override the region for this invocation without changing the profile. + tdc --region aws-us-west-2 db list-db-clusters + ``` + - Select cluster fields: ```bash @@ -52,6 +59,8 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name,state:state}' ``` +The effective region resolves from global `--region`, then `TDC_REGION_CODE`, then the selected profile's `region_code`. User-supplied `--filter` expressions are combined with this mandatory region scope and cannot expand the result to other regions. + ## Related documentation - [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) diff --git a/ai/tdc/reference/tdc-starter-database.md b/ai/tdc/reference/tdc-starter-database.md index e577cf295bc6f..f6aa86f00d1c3 100644 --- a/ai/tdc/reference/tdc-starter-database.md +++ b/ai/tdc/reference/tdc-starter-database.md @@ -34,7 +34,7 @@ tdc db | Command | Purpose and key inputs | Example | | --- | --- | --- | | `create-db-cluster` | Creates a Starter cluster. Requires `--db-cluster-name`; `--db-cluster-type` is optional and defaults to `starter`. Use `--wait` for an `ACTIVE` result. | `tdc db create-db-cluster --db-cluster-name app-db --wait` | -| `list-db-clusters` | Lists Starter clusters with pagination, filter, ordering, and query support. | `tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name}'` | +| `list-db-clusters` | Lists Starter clusters in the effective region with pagination, filter, ordering, and query support. | `tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name}'` | | `describe-db-cluster` | Reads one cluster by `--db-cluster-id`; `--view FULL` requests expanded fields. | `tdc db describe-db-cluster --db-cluster-id "" --view FULL` | | `update-db-cluster` | Changes the name or monthly spending limit of one cluster. Supports `--dry-run`. | `tdc db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2` | | `delete-db-cluster` | Deletes one cluster by ID. Use `--wait` to wait until deletion is observable. | `tdc db delete-db-cluster --db-cluster-id "" --wait` | @@ -73,9 +73,10 @@ List and filter clusters: tdc db list-db-clusters tdc db list-db-clusters --page-size 20 --order-by "createTime desc" tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name,state:state}' +tdc --region aws-us-west-2 db list-db-clusters ``` -The list command also accepts `--page-token`, `--filter`, and `--skip`. The shared TiDB Cloud API can return multiple service plans, so the TiDB Cloud CLI filters each page to verified Starter clusters. It preserves `next_page_token` but omits `total_size`, because the server total includes clusters outside the Starter-only result. +The list command also accepts `--page-token`, `--filter`, and `--skip`. It always scopes the API request to the effective region, which resolves from global `--region`, then `TDC_REGION_CODE`, then the selected profile. The shared TiDB Cloud API can return multiple service plans or unverifiable resources, so the TiDB Cloud CLI defensively filters each page to verified Starter clusters in that region. It preserves `next_page_token` but omits `total_size`, because the server total can include clusters outside the verified result. A user `--filter` is combined with the mandatory region filter and cannot expand the result to another region. Describe and update a cluster: From 2897f1300c435feb07f4f502f9e1ba6aec7f6f79 Mon Sep 17 00:00:00 2001 From: Cheese Date: Thu, 6 Aug 2026 13:00:54 +0800 Subject: [PATCH 23/29] docs: describe telemetry environment metadata --- ai/tdc/reference/tdc-configuration-and-credentials.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md index 2c03c67035f03..3c15f182bcf76 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -214,6 +214,14 @@ TDC_TELEMETRY=off tdc db list-db-clusters The TiDB Cloud CLI creates `~/.tdc/.telemetry-installation-id` lazily for the first eligible event and restricts it to the current user where POSIX permissions are available. Delete this file to reset the pseudonymous identity. Telemetry delivery is lossy and never changes command output, errors, or exit status. +An integration can attach explicit process-scoped metadata without changing a profile or command. `TDC_TELEMETRY_TAG` accepts a UTF-8 string up to 128 bytes. `TDC_TELEMETRY_EXTRA` accepts one complete JSON value up to 2 KiB after compaction. Invalid, prohibited, deeply nested, or oversized metadata is omitted without affecting the command. Do not include credentials, tokens, SQL, paths, personal data, profile names, or cloud resource IDs in either value: + +```bash +TDC_TELEMETRY_TAG="e2b-preview" \ +TDC_TELEMETRY_EXTRA='{"campaign":"launch","runtime":"e2b"}' \ +tdc fs list-files --file-system-name workspace --path / +``` + ## Sensitive values Treat these as secrets: From ff01d36c0fde4731fa086150f38eeb95b04bbae6 Mon Sep 17 00:00:00 2001 From: Cheese Date: Fri, 7 Aug 2026 07:52:03 +0800 Subject: [PATCH 24/29] docs: describe remote filesystem inventory --- TOC-ai.md | 1 + ai/_index.md | 1 + .../fs-git/tdc-fs-git-add-git-worktree.md | 8 +- .../fs-git/tdc-fs-git-clone-git-workspace.md | 10 +-- .../tdc-fs-git-hydrate-git-workspace.md | 6 +- .../fs-git/tdc-fs-git-remove-git-worktree.md | 6 +- .../tdc-fs-journal-append-journal-entries.md | 10 +-- .../tdc-fs-journal-create-journal.md | 8 +- .../tdc-fs-journal-read-journal-entries.md | 8 +- .../tdc-fs-journal-search-journal-entries.md | 10 +-- .../tdc-fs-journal-verify-journal.md | 6 +- .../fs-vault/tdc-fs-vault-create-grant.md | 8 +- .../fs-vault/tdc-fs-vault-create-secret.md | 10 +-- .../fs-vault/tdc-fs-vault-delete-grant.md | 6 +- .../fs-vault/tdc-fs-vault-delete-secret.md | 6 +- .../tdc-fs-vault-list-audit-events.md | 8 +- .../fs-vault/tdc-fs-vault-list-secrets.md | 8 +- .../fs-vault/tdc-fs-vault-mount-vault.md | 8 +- .../fs-vault/tdc-fs-vault-read-secret.md | 10 +-- .../fs-vault/tdc-fs-vault-replace-secret.md | 8 +- .../fs-vault/tdc-fs-vault-run-with-secret.md | 8 +- .../commands/fs/tdc-fs-check-file-system.md | 6 +- .../commands/fs/tdc-fs-chmod-file.md | 6 +- .../commands/fs/tdc-fs-commit-layer.md | 6 +- .../reference/commands/fs/tdc-fs-copy-file.md | 16 ++-- .../commands/fs/tdc-fs-create-directory.md | 6 +- .../commands/fs/tdc-fs-create-file-system.md | 10 +-- .../commands/fs/tdc-fs-create-hardlink.md | 6 +- .../fs/tdc-fs-create-layer-checkpoint.md | 8 +- .../commands/fs/tdc-fs-create-layer.md | 8 +- .../commands/fs/tdc-fs-create-symlink.md | 6 +- .../commands/fs/tdc-fs-delete-file-system.md | 14 ++-- .../commands/fs/tdc-fs-delete-file.md | 8 +- .../fs/tdc-fs-describe-file-system.md | 12 +-- .../commands/fs/tdc-fs-describe-file.md | 6 +- .../commands/fs/tdc-fs-describe-layer.md | 6 +- .../commands/fs/tdc-fs-diff-layer.md | 8 +- .../commands/fs/tdc-fs-find-files.md | 8 +- .../fs/tdc-fs-import-file-system-token.md | 58 ++++++++++++++ .../commands/fs/tdc-fs-list-file-systems.md | 8 +- .../commands/fs/tdc-fs-list-files.md | 6 +- .../commands/fs/tdc-fs-list-layers.md | 6 +- .../commands/fs/tdc-fs-mount-file-system.md | 12 +-- .../reference/commands/fs/tdc-fs-move-file.md | 6 +- .../commands/fs/tdc-fs-pack-file-system.md | 8 +- .../reference/commands/fs/tdc-fs-read-file.md | 8 +- .../commands/fs/tdc-fs-rollback-layer.md | 6 +- .../commands/fs/tdc-fs-search-file-content.md | 8 +- .../commands/fs/tdc-fs-unpack-file-system.md | 8 +- ai/tdc/reference/tdc-agent-sandbox-example.md | 17 ++--- .../tdc-ci-artifact-handoff-example.md | 3 +- ai/tdc/reference/tdc-cli-reference.md | 1 + .../tdc-configuration-and-credentials.md | 27 ++++--- .../reference/tdc-daily-workflow-example.md | 7 +- ai/tdc/reference/tdc-filesystem-journal.md | 2 +- ai/tdc/reference/tdc-filesystem.md | 76 +++++++++---------- .../tdc-parallel-agent-dataset-example.md | 14 ++-- .../tdc-persistent-agent-state-example.md | 8 +- .../tdc-regions-security-and-limitations.md | 6 +- ...hare-filesystem-across-machines-example.md | 20 ++--- ai/tdc/reference/tdc-troubleshooting.md | 28 ++++--- ai/tdc/tdc-quick-start.md | 13 ++-- 62 files changed, 348 insertions(+), 302 deletions(-) create mode 100644 ai/tdc/reference/commands/fs/tdc-fs-import-file-system-token.md diff --git a/TOC-ai.md b/TOC-ai.md index 9facffc93f500..3591f4cc2e3c4 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -115,6 +115,7 @@ - [execute-sql-statement](/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md) - fs - [create-file-system](/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md) + - [import-file-system-token](/ai/tdc/reference/commands/fs/tdc-fs-import-file-system-token.md) - [list-file-systems](/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md) - [describe-file-system](/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md) - [check-file-system](/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md) diff --git a/ai/_index.md b/ai/_index.md index c334a8369d6cd..065986a96b0a9 100644 --- a/ai/_index.md +++ b/ai/_index.md @@ -98,6 +98,7 @@ The command reference follows the two-level `tdc` command tree. Every command ha | [`tdc organization list-projects`](/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md) | List accessible TiDB Cloud projects. | | [`tdc db create-db-cluster`](/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md) | Start with the database command reference. | | [`tdc fs create-file-system`](/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md) | Start with the Filesystem command reference. | +| [`tdc fs import-file-system-token`](/ai/tdc/reference/commands/fs/tdc-fs-import-file-system-token.md) | Restore local access from an existing FS token. | | [`tdc fs-git clone-git-workspace`](/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md) | Start with the Filesystem Git command reference. | | [`tdc fs-journal create-journal`](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md) | Start with the Filesystem journal command reference. | | [`tdc fs-vault create-secret`](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md) | Start with the Filesystem Vault command reference. | diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md index c11706a3f1b5a..a6b6a0ad6b562 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md @@ -22,7 +22,7 @@ tdc fs-git add-git-worktree [--commit-ish ] [--detach] [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--hydrate ] @@ -38,7 +38,7 @@ tdc fs-git add-git-worktree - `--commit-ish `: Optional commit-ish for the linked worktree. - `--detach`: Create a detached linked worktree. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--hydrate `: Blobless hydrate mode: `auto`, `background`, `sync`, or `off`. \[default: auto] @@ -52,14 +52,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Give an agent an isolated branch while sharing the base Git object store. - tdc fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-feature --branch-name feature-x + tdc fs-git add-git-worktree --file-system-id --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-feature --branch-name feature-x ``` - Create a detached worktree: ```bash # Inspect a commit without creating or switching a branch. - tdc fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-review --commit-ish origin/main --detach + tdc fs-git add-git-worktree --file-system-id --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-review --commit-ish origin/main --detach ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md index 1700d1d7a96b9..c25bbb618f840 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md @@ -19,7 +19,7 @@ tdc fs-git clone-git-workspace --target-path [--blobless] [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--hydrate ] @@ -32,7 +32,7 @@ tdc fs-git clone-git-workspace - `--target-path `: The mounted file system path to clone into. \[required] - `--blobless`: Create a blobless partial local `.git` and hydrate clean blobs separately. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--hydrate `: Blobless hydrate mode: `auto`, `background`, `sync`, or `off`. \[default: auto] @@ -46,21 +46,21 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Create a complete Git checkout in the mounted Filesystem path. - tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb + tdc fs-git clone-git-workspace --file-system-id --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb ``` - Start a blobless workspace immediately: ```bash # Expose the repository tree while clean Git objects hydrate in the background. - tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate background + tdc fs-git clone-git-workspace --file-system-id --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate background ``` - Wait for blobless hydration: ```bash # Keep the clone command running until clean Git objects finish hydrating. - tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate sync + tdc fs-git clone-git-workspace --file-system-id --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate sync ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md index 53299166bcb11..0f1f2a87e4d3e 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md @@ -16,7 +16,7 @@ Hydrates clean Git objects for an existing `tdc` Git workspace. ```text tdc fs-git hydrate-git-workspace --target-path - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--timeout ] @@ -26,7 +26,7 @@ tdc fs-git hydrate-git-workspace ## Options - `--target-path `: Mounted `tdc fs` workspace path. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--timeout `: Maximum hydrate duration. \[default: `30m0s`] @@ -40,7 +40,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Download missing clean Git objects for an existing blobless workspace. - tdc fs-git hydrate-git-workspace --file-system-name workspace --target-path /path/to/workspace/tidb --timeout 30m + tdc fs-git hydrate-git-workspace --file-system-id --target-path /path/to/workspace/tidb --timeout 30m ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md index 2a4e83c0eb141..720ce6a8879d1 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md +++ b/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md @@ -17,7 +17,7 @@ Removes a linked worktree without recursively deleting shared clean-tree data. tdc fs-git remove-git-worktree --worktree-path [--dry-run] - [--file-system-name ] + [--file-system-id ] [--force] [--fs-token ] [--help] @@ -28,7 +28,7 @@ tdc fs-git remove-git-worktree - `--worktree-path `: Mounted `tdc fs` path of the linked worktree. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--force`: Remove even when the linked worktree has local changes. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. @@ -42,7 +42,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Force removal when the isolated worktree still contains local changes. - tdc fs-git remove-git-worktree --file-system-name workspace --worktree-path /path/to/workspace/tidb-feature --force + tdc fs-git remove-git-worktree --file-system-id --worktree-path /path/to/workspace/tidb-feature --force ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md index 9b57cee986053..a251422cfe377 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md @@ -19,7 +19,7 @@ tdc fs-journal append-journal-entries [--dry-run] [--entry-json ] [--entry-type ] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--idempotency-key ] @@ -35,7 +35,7 @@ tdc fs-journal append-journal-entries - `--dry-run`: Validate the request without applying changes. - `--entry-json `: One JSON journal entry object; repeatable. - `--entry-type `: Default entry type for entries missing type. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--idempotency-key `: Append idempotency key; generated when omitted. @@ -52,21 +52,21 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Record an event object exactly as supplied on the command line. - tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-json '{"type":"task.started"}' + tdc fs-journal append-journal-entries --file-system-id --journal-id jrn-demo --entry-json '{"type":"task.started"}' ``` - Append an idempotent typed entry: ```bash # Prevent retries from recording the same completion event twice. - tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-type task.completed --subject issue-42 --idempotency-key issue-42-complete + tdc fs-journal append-journal-entries --file-system-id --journal-id jrn-demo --entry-type task.completed --subject issue-42 --idempotency-key issue-42-complete ``` - Append a JSON array from standard input: ```bash # Batch multiple ordered events in a single append operation. - printf '[{"type":"step.started"},{"type":"step.completed"}]' | tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --json-array + printf '[{"type":"step.started"},{"type":"step.completed"}]' | tdc fs-journal append-journal-entries --file-system-id --journal-id jrn-demo --json-array ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md index d6f9f1302e433..7d1d3c8337aea 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md @@ -17,7 +17,7 @@ Creates a journal. If `--journal-id` is omitted, the service generates one. tdc fs-journal create-journal [--actor ] [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--journal-id ] @@ -31,7 +31,7 @@ tdc fs-journal create-journal - `--actor `: Actor in the form `type:id`. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--journal-id `: Journal ID; generated when omitted. @@ -48,14 +48,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Create an append-only journal for one agent task. - tdc fs-journal create-journal --file-system-name workspace --journal-id jrn-demo --journal-kind agent --title "demo task" + tdc fs-journal create-journal --file-system-id --journal-id jrn-demo --journal-kind agent --title "demo task" ``` - Create a labeled deployment journal: ```bash # Attach actor and environment metadata for later searches. - tdc fs-journal create-journal --file-system-name workspace --journal-kind deployment --actor agent:tdc --label env=dev + tdc fs-journal create-journal --file-system-id --journal-kind deployment --actor agent:tdc --label env=dev ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md index 6bf6d26229332..2d0b3e5582a71 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md @@ -17,7 +17,7 @@ Reads entries from one journal in sequence order. tdc fs-journal read-journal-entries --journal-id [--after-seq ] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--limit ] @@ -28,7 +28,7 @@ tdc fs-journal read-journal-entries - `--journal-id `: Journal ID. \[required] - `--after-seq `: Read entries after this sequence. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--limit `: Maximum entries to read. \[default: 100] @@ -42,14 +42,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return the first page of ordered entries for a journal. - tdc fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo + tdc fs-journal read-journal-entries --file-system-id --journal-id jrn-demo ``` - Continue after a sequence number: ```bash # Read the next page after the last sequence processed by a consumer. - tdc fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo --after-seq 100 --limit 50 + tdc fs-journal read-journal-entries --file-system-id --journal-id jrn-demo --after-seq 100 --limit 50 ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md index d07cef283431e..04e700577c9ea 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md @@ -18,7 +18,7 @@ tdc fs-journal search-journal-entries [--actor ] [--cursor ] [--entry-type ] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--include-entries] @@ -37,7 +37,7 @@ tdc fs-journal search-journal-entries - `--actor `: Actor in the form `type:id`. - `--cursor `: Pagination cursor. - `--entry-type `: Entry type filter. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--include-entries`: Include full entry payloads in matches. @@ -58,21 +58,21 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Find journals containing task-start events and include their payloads. - tdc fs-journal search-journal-entries --file-system-name workspace --entry-type task.started --include-entries + tdc fs-journal search-journal-entries --file-system-id --entry-type task.started --include-entries ``` - Search by label and time: ```bash # Limit deployment journal matches to one environment and time window. - tdc fs-journal search-journal-entries --file-system-name workspace --label env=dev --since 2026-07-01T00:00:00Z --limit 100 + tdc fs-journal search-journal-entries --file-system-id --label env=dev --since 2026-07-01T00:00:00Z --limit 100 ``` - Search by actor and subject: ```bash # Find events produced by one agent for a specific task subject. - tdc fs-journal search-journal-entries --file-system-name workspace --actor agent:tdc --subject issue-42 --include-entries + tdc fs-journal search-journal-entries --file-system-id --actor agent:tdc --subject issue-42 --include-entries ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md index 5ee9b41519449..469dce5d1daf8 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md +++ b/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md @@ -16,7 +16,7 @@ Verifies the integrity of one journal hash chain. ```text tdc fs-journal verify-journal --journal-id - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -25,7 +25,7 @@ tdc fs-journal verify-journal ## Options - `--journal-id `: Journal ID. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -38,7 +38,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Validate the journal's ordered hash chain and integrity metadata. - tdc fs-journal verify-journal --file-system-name workspace --journal-id jrn-demo + tdc fs-journal verify-journal --file-system-id --journal-id jrn-demo ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md index 35fdacea52aff..1d85fd1756b78 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md @@ -20,7 +20,7 @@ tdc fs-vault create-grant --scope --ttl [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--label-hint ] @@ -35,7 +35,7 @@ tdc fs-vault create-grant - `--scope `: Vault scope such as secret or secret/field; repeatable. \[required] - `--ttl `: Grant time to live, for example, `1h`. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--label-hint `: Optional grant label hint. @@ -50,14 +50,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Limit an agent to one secret field for ten minutes. - tdc fs-vault create-grant --file-system-name workspace --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m + tdc fs-vault create-grant --file-system-id --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m ``` - Return only the delegated token: ```bash # Produce token-only output for injection into an isolated CI job. - tdc fs-vault create-grant --file-system-name workspace --agent-id ci-agent --scope api-dev/TOKEN --permission read --ttl 5m --token-only + tdc fs-vault create-grant --file-system-id --agent-id ci-agent --scope api-dev/TOKEN --permission read --ttl 5m --token-only ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md index d952eff72f9ed..97b0bb23b9bb3 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md @@ -18,7 +18,7 @@ tdc fs-vault create-secret --field --secret-name [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -29,7 +29,7 @@ tdc fs-vault create-secret - `--field `: Secret field assignment `key=value`, `key=@file`, or `key=-`; repeatable. \[required] - `--secret-name `: Vault secret name. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -42,21 +42,21 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Keep the password out of the command line by reading it from a local file. - tdc fs-vault create-secret --file-system-name workspace --secret-name db-prod --field DB_URL=mysql://example --field PASSWORD=@./password.txt + tdc fs-vault create-secret --file-system-id --secret-name db-prod --field DB_URL=mysql://example --field PASSWORD=@./password.txt ``` - Read a secret field from standard input: ```bash # Supply a sensitive token through a pipe instead of a process argument. - printf '%s' "$API_TOKEN" | tdc fs-vault create-secret --file-system-name workspace --secret-name api-dev --field TOKEN=- + printf '%s' "$API_TOKEN" | tdc fs-vault create-secret --file-system-id --secret-name api-dev --field TOKEN=- ``` - Preview secret creation: ```bash # Validate field assignments without storing secret material. - tdc fs-vault create-secret --file-system-name workspace --secret-name api-dev --field TOKEN=@./token.txt --dry-run + tdc fs-vault create-secret --file-system-id --secret-name api-dev --field TOKEN=@./token.txt --dry-run ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md index 9ac3163cf99ff..98885f9d6b07e 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md @@ -17,7 +17,7 @@ Revokes one delegated Filesystem Vault grant. tdc fs-vault delete-grant --grant-id [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--reason ] @@ -29,7 +29,7 @@ tdc fs-vault delete-grant - `--grant-id `: Vault grant ID. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--reason `: Optional revoke reason. @@ -44,7 +44,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Invalidate the delegated token and record the revocation reason. - tdc fs-vault delete-grant --file-system-name workspace --grant-id "" --reason rotated + tdc fs-vault delete-grant --file-system-id --grant-id "" --reason rotated ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md index af816d9a85c27..3ce46b6040595 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md @@ -17,7 +17,7 @@ Deletes one Filesystem Vault secret. tdc fs-vault delete-secret --secret-name [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -27,7 +27,7 @@ tdc fs-vault delete-secret - `--secret-name `: Vault secret name. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -40,7 +40,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Remove the selected secret and its fields from the Vault. - tdc fs-vault delete-secret --file-system-name workspace --secret-name db-prod + tdc fs-vault delete-secret --file-system-id --secret-name db-prod ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md index 22d58df25248a..0cf44caaec5a4 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md @@ -16,7 +16,7 @@ Lists vault audit events with optional agent, secret, and time filters. ```text tdc fs-vault list-audit-events [--agent-id ] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--limit ] @@ -28,7 +28,7 @@ tdc fs-vault list-audit-events ## Options - `--agent-id `: Filter by agent ID. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--limit `: Maximum events to return. \[default: 100] @@ -44,14 +44,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Inspect recent access and mutation events for the selected secret. - tdc fs-vault list-audit-events --file-system-name workspace --secret-name db-prod --limit 20 + tdc fs-vault list-audit-events --file-system-id --secret-name db-prod --limit 20 ``` - List recent events for an agent: ```bash # Filter the audit trail to one delegated identity and time range. - tdc fs-vault list-audit-events --file-system-name workspace --agent-id deploy-agent --since 24h + tdc fs-vault list-audit-events --file-system-id --agent-id deploy-agent --since 24h ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md index 46ac7381cc82f..9ca64c4fbd8ec 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md @@ -15,7 +15,7 @@ Lists secrets visible to the active owner or delegated credential. ```text tdc fs-vault list-secrets - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--vault-token ] @@ -24,7 +24,7 @@ tdc fs-vault list-secrets ## Options -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--vault-token `: Delegated `tdc fs-vault` token; prefer `TDC_VAULT_TOKEN`. @@ -38,14 +38,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return secret metadata without exposing field values. - tdc fs-vault list-secrets --file-system-name workspace + tdc fs-vault list-secrets --file-system-id ``` - List secrets visible to a delegated token: ```bash # Restrict the result to secrets within the token's granted scope. - tdc fs-vault list-secrets --file-system-name workspace --vault-token "$TDC_VAULT_TOKEN" + tdc fs-vault list-secrets --file-system-id --vault-token "$TDC_VAULT_TOKEN" ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md index dd865a22a85ff..ac18176ac8e12 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md @@ -17,7 +17,7 @@ Mounts readable vault fields as a local read-only FUSE filesystem. tdc fs-vault mount-vault --mount-path [--dry-run] - [--file-system-name ] + [--file-system-id ] [--foreground] [--fs-token ] [--help] @@ -30,7 +30,7 @@ tdc fs-vault mount-vault - `--mount-path `: Local mount path. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--foreground`: Run mount runtime in the foreground until interrupted. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. @@ -46,14 +46,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Expose only the paths allowed by the delegated Vault token. - tdc fs-vault mount-vault --file-system-name workspace --mount-path ./vault --vault-token "$TDC_VAULT_TOKEN" + tdc fs-vault mount-vault --file-system-id --mount-path ./vault --vault-token "$TDC_VAULT_TOKEN" ``` - Run the Vault mount in the foreground: ```bash # Keep the runtime attached for containers or process supervisors. - tdc fs-vault mount-vault --file-system-name workspace --mount-path ./vault --foreground --ready-timeout 60s + tdc fs-vault mount-vault --file-system-id --mount-path ./vault --foreground --ready-timeout 60s ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md index e8d0624cea925..80332a728616f 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md @@ -17,7 +17,7 @@ Reads a complete secret or one field using an owner or delegated credential. tdc fs-vault read-secret --secret-name [--field ] - [--file-system-name ] + [--file-system-id ] [--format ] [--fs-token ] [--help] @@ -29,7 +29,7 @@ tdc fs-vault read-secret - `--secret-name `: Vault secret name. \[required] - `--field `: Optional field name to read. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--format `: Read output format: `json`, `raw`, or `env`. \[default: json] - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. @@ -44,21 +44,21 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Write only the selected field value for direct consumption by a process. - tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field PASSWORD --format raw + tdc fs-vault read-secret --file-system-id --secret-name db-prod --field PASSWORD --format raw ``` - Format a field as an environment assignment: ```bash # Emit an exportable environment-variable representation of the field. - tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field DB_URL --format env + tdc fs-vault read-secret --file-system-id --secret-name db-prod --field DB_URL --format env ``` - Read with a delegated Vault token: ```bash # Access only the scope granted to an agent without using the owner token. - tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field DB_URL --vault-token "$TDC_VAULT_TOKEN" --format raw + tdc fs-vault read-secret --file-system-id --secret-name db-prod --field DB_URL --vault-token "$TDC_VAULT_TOKEN" --format raw ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md index d3dfcda169e7d..366ca36aa084f 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md @@ -18,7 +18,7 @@ tdc fs-vault replace-secret --from-directory --secret-path [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -29,7 +29,7 @@ tdc fs-vault replace-secret - `--from-directory `: Directory whose files become secret fields. \[required] - `--secret-path `: Vault path in the form `/n/vault/`. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -42,14 +42,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Replace all fields with files loaded from the selected directory. - tdc fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields + tdc fs-vault replace-secret --file-system-id --secret-path /n/vault/db-prod --from-directory ./secret-fields ``` - Preview secret replacement: ```bash # Validate the replacement source without changing the stored secret. - tdc fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields --dry-run + tdc fs-vault replace-secret --file-system-id --secret-path /n/vault/db-prod --from-directory ./secret-fields --dry-run ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md index 13490d86a6ac2..8670223906ff0 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md +++ b/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md @@ -16,7 +16,7 @@ Runs a command with one secret injected into its environment. Arguments after `- ```text tdc fs-vault run-with-secret --secret-path - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--vault-token ] @@ -26,7 +26,7 @@ tdc fs-vault run-with-secret ## Options - `--secret-path `: Vault path in the form `/n/vault/`. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--vault-token `: Delegated `tdc fs-vault` token; prefer `TDC_VAULT_TOKEN`. @@ -40,14 +40,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Inject all fields into the child process environment without printing them. - tdc fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- env + tdc fs-vault run-with-secret --file-system-id --secret-path /n/vault/db-prod -- env ``` - Use an injected field in a shell command: ```bash # Verify that the child process receives DB_URL without exposing its value. - tdc fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- sh -c 'test -n "$DB_URL"' + tdc fs-vault run-with-secret --file-system-id --secret-path /n/vault/db-prod -- sh -c 'test -n "$DB_URL"' ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md index 83e6b894d5722..841f578155b01 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md @@ -15,7 +15,7 @@ Checks Filesystem selection, endpoint resolution, credentials, and companion acc ```text tdc fs check-file-system - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -23,7 +23,7 @@ tdc fs check-file-system ## Options -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -36,7 +36,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Verify that the selected token can reach and read the Filesystem root. - tdc fs check-file-system --file-system-name workspace + tdc fs check-file-system --file-system-id ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md b/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md index 5da5399eaf6da..2f24943242eea 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md @@ -18,7 +18,7 @@ tdc fs chmod-file --mode --path [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -29,7 +29,7 @@ tdc fs chmod-file - `--mode `: The permission mode as an octal value such as 0644. \[required] - `--path `: File or directory path. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -42,7 +42,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Restrict the selected file to owner read and write access. - tdc fs chmod-file --file-system-name workspace --path /reports/final.md --mode 0600 + tdc fs chmod-file --file-system-id --path /reports/final.md --mode 0600 ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md index 25fc65687d622..4c07a458cb1fe 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md @@ -17,7 +17,7 @@ Applies one layer to its base Filesystem. tdc fs commit-layer --layer-id [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -27,7 +27,7 @@ tdc fs commit-layer - `--layer-id `: Layer ID. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -40,7 +40,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Apply the selected layer's changes to its base Filesystem view. - tdc fs commit-layer --file-system-name workspace --layer-id "" + tdc fs commit-layer --file-system-id --layer-id "" ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md b/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md index a70f1b54076fc..5a1c6c8d4235a 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md @@ -19,7 +19,7 @@ tdc fs copy-file [--create-parents] [--description ] [--dry-run] - [--file-system-name ] + [--file-system-id ] [--from-local ] [--from-remote ] [--from-stdin] @@ -42,7 +42,7 @@ tdc fs copy-file - `--create-parents`: Create missing local parent directories when copying from a TiDB Cloud file system. - `--description `: The file description for `--to-remote` operation. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--from-local `: The local source path. - `--from-remote `: The source path in the TiDB Cloud file system. - `--from-stdin`: Read from stdin and write to `--to-remote`. @@ -66,42 +66,42 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Copy a local report into the selected remote Filesystem. - tdc fs copy-file --file-system-name workspace --from-local ./report.md --to-remote /reports/report.md + tdc fs copy-file --file-system-id --from-local ./report.md --to-remote /reports/report.md ``` - Download a remote file: ```bash # Create missing local parent directories while downloading the file. - tdc fs copy-file --file-system-name workspace --from-remote /reports/report.md --to-local ./downloads/report.md --create-parents + tdc fs copy-file --file-system-id --from-remote /reports/report.md --to-local ./downloads/report.md --create-parents ``` - Copy a remote directory: ```bash # Duplicate a complete directory tree without downloading it locally. - tdc fs copy-file --file-system-name workspace --from-remote /reports --to-remote /archive/reports --recursive + tdc fs copy-file --file-system-id --from-remote /reports --to-remote /archive/reports --recursive ``` - Resume a large upload: ```bash # Continue an interrupted local-to-remote transfer instead of restarting it. - tdc fs copy-file --file-system-name workspace --from-local ./large.bin --to-remote /artifacts/large.bin --resume + tdc fs copy-file --file-system-id --from-local ./large.bin --to-remote /artifacts/large.bin --resume ``` - Append to a remote log: ```bash # Add local log data to the existing remote object efficiently. - tdc fs copy-file --file-system-name workspace --from-local ./tail.log --to-remote /logs/app.log --append + tdc fs copy-file --file-system-id --from-local ./tail.log --to-remote /logs/app.log --append ``` - Stream standard input to the Filesystem: ```bash # Upload generated content without creating an intermediate local file. - printf 'ready\n' | tdc fs copy-file --file-system-name workspace --from-stdin --to-remote /status.txt --tag source=stdin --description "generated status" + printf 'ready\n' | tdc fs copy-file --file-system-id --from-stdin --to-remote /status.txt --tag source=stdin --description "generated status" ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md b/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md index 8d244602b2c82..214e62c682651 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md @@ -17,7 +17,7 @@ Creates a remote directory. The command alias is `tdc fs mkdir`. tdc fs create-directory --path [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--mode ] @@ -28,7 +28,7 @@ tdc fs create-directory - `--path `: The file system path of the directory to create. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--mode `: The directory mode as an octal value such as 0755. @@ -42,7 +42,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Create the directory with explicit POSIX permission metadata. - tdc fs create-directory --file-system-name workspace --path /reports/archive --mode 0755 + tdc fs create-directory --file-system-id --path /reports/archive --mode 0755 ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md index 359e882eaf35b..187a16503130b 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md @@ -5,7 +5,7 @@ summary: Create a TiDB Cloud Filesystem. # tdc fs create-file-system -Creates a Filesystem. `--wait` waits until data-plane access is ready. +Creates a Filesystem with a server-assigned ID. The response contains the owner `fs_token` once. `--wait` waits until data-plane access is ready. > **Note:** > @@ -15,7 +15,6 @@ Creates a Filesystem. `--wait` waits until data-plane access is ready. ```text tdc fs create-file-system - --file-system-name [--dry-run] [--help] [--version] @@ -24,7 +23,6 @@ tdc fs create-file-system ## Options -- `--file-system-name `: Set the file system name. \[required] - `--dry-run`: Validate the request without applying changes. - `--help`: Display help information. - `--version`: Display version information. @@ -38,21 +36,21 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Wait until the new Filesystem root is readable before returning. - tdc fs create-file-system --file-system-name workspace --wait + tdc fs create-file-system --wait ``` - Create a Filesystem asynchronously: ```bash # Return after provisioning is accepted so work can continue in parallel. - tdc fs create-file-system --file-system-name scratch + tdc fs create-file-system ``` - Preview Filesystem creation: ```bash # Validate credentials, placement, and the request without provisioning storage. - tdc fs create-file-system --file-system-name workspace --dry-run + tdc fs create-file-system --dry-run ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md b/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md index 02ea2cd74127d..2fb072e9d9861 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md @@ -18,7 +18,7 @@ tdc fs create-hardlink --link-path --source-path [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -29,7 +29,7 @@ tdc fs create-hardlink - `--link-path `: The file path for the hard link being created in the TiDB Cloud file system. \[required] - `--source-path `: The existing file path in the TiDB Cloud file system. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -42,7 +42,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Expose the same remote file content at a second path. - tdc fs create-hardlink --file-system-name workspace --source-path /reports/final.md --link-path /reports/final-copy.md + tdc fs create-hardlink --file-system-id --source-path /reports/final.md --link-path /reports/final-copy.md ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md b/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md index afc1543538f5b..095d8582084f0 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md @@ -18,7 +18,7 @@ tdc fs create-layer-checkpoint --layer-id [--checkpoint-id ] [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--label ] @@ -30,7 +30,7 @@ tdc fs create-layer-checkpoint - `--layer-id `: The layer ID identifying the layer. \[required] - `--checkpoint-id `: Checkpoint ID. Normally it is generated by the service automatically. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--label `: The checkpoint label. @@ -44,14 +44,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Record the current layer state under a stable checkpoint ID. - tdc fs create-layer-checkpoint --file-system-name workspace --layer-id "" --checkpoint-id before-review + tdc fs create-layer-checkpoint --file-system-id --layer-id "" --checkpoint-id before-review ``` - Create an automatically identified checkpoint: ```bash # Let the service assign the checkpoint ID while retaining a human label. - tdc fs create-layer-checkpoint --file-system-name workspace --layer-id "" --label "before review" + tdc fs create-layer-checkpoint --file-system-id --layer-id "" --label "before review" ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md index 45385251806f1..ec72c5cf871d2 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md @@ -19,7 +19,7 @@ tdc fs create-layer [--actor-id ] [--dry-run] [--durability-mode ] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--layer-id ] @@ -34,7 +34,7 @@ tdc fs create-layer - `--actor-id `: Actor ID identifying the layer owner (for example, the agent name). - `--dry-run`: Validate the request without applying changes. - `--durability-mode `: Layer durability mode; must be `restore-safe`. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--layer-id `: The layer ID. Normally it is generated by the service automatically. @@ -50,14 +50,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Start an isolated writable view over the selected base root. - tdc fs create-layer --file-system-name workspace --base-root-path /workspace --layer-name agent-task + tdc fs create-layer --file-system-id --base-root-path /workspace --layer-name agent-task ``` - Create a restore-safe tagged layer: ```bash # Request durable layer behavior and attach task metadata. - tdc fs create-layer --file-system-name workspace --base-root-path /workspace --durability-mode restore-safe --tag task=review + tdc fs create-layer --file-system-id --base-root-path /workspace --durability-mode restore-safe --tag task=review ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md b/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md index 6b90ce9baa74a..ffbf2b7c85b41 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md @@ -18,7 +18,7 @@ tdc fs create-symlink --link-path --target [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -29,7 +29,7 @@ tdc fs create-symlink - `--link-path `: The file path for the created symbolic link. \[required] - `--target `: The actual file path being linked to. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -42,7 +42,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Create a relative symbolic link inside the remote namespace. - tdc fs create-symlink --file-system-name workspace --target final.md --link-path /reports/latest.md + tdc fs create-symlink --file-system-id --target final.md --link-path /reports/latest.md ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md index efb8b565611db..4c7e68be98eaa 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md @@ -5,7 +5,7 @@ summary: Delete a TiDB Cloud Filesystem. # tdc fs delete-file-system -Requests asynchronous Filesystem deletion and removes its local registration. +Requests asynchronous Filesystem deletion by ID. A locally stored FS token is not required. > **Note:** > @@ -15,18 +15,16 @@ Requests asynchronous Filesystem deletion and removes its local registration. ```text tdc fs delete-file-system - --file-system-name + --file-system-id [--dry-run] - [--fs-token ] [--help] [--version] ``` ## Options -- `--file-system-name `: Set the file system name. \[required] +- `--file-system-id `: Set the file system ID. \[required] - `--dry-run`: Validate the request without applying changes. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -37,15 +35,15 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c - Delete a Filesystem: ```bash - # Request asynchronous deletion and remove its local registration after acceptance. - tdc fs delete-file-system --file-system-name workspace + # Request asynchronous deletion and remove only the matching local credential after acceptance. + tdc fs delete-file-system --file-system-id ``` - Preview Filesystem deletion: ```bash # Validate the selected Filesystem without sending the deletion request. - tdc fs delete-file-system --file-system-name workspace --dry-run + tdc fs delete-file-system --file-system-id --dry-run ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md b/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md index 6c09dbd797fb6..17cf2f6a57b1b 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md @@ -17,7 +17,7 @@ Deletes a remote file or directory. The command alias is `tdc fs rm`. tdc fs delete-file --path [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--recursive] @@ -28,7 +28,7 @@ tdc fs delete-file - `--path `: File or directory path in the TiDB Cloud file system. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--recursive`: Delete a directory recursively. @@ -42,14 +42,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Remove one object from the selected Filesystem. - tdc fs delete-file --file-system-name workspace --path /reports/obsolete.md + tdc fs delete-file --file-system-id --path /reports/obsolete.md ``` - Delete a directory recursively: ```bash # Remove a directory and all of its descendants in one request. - tdc fs delete-file --file-system-name workspace --path /scratch --recursive + tdc fs delete-file --file-system-id --path /scratch --recursive ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md index daeef296b67c8..265b3d386bebe 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md @@ -1,11 +1,11 @@ --- title: tdc fs describe-file-system -summary: Describe a locally registered TiDB Cloud Filesystem. +summary: Describe a remote TiDB Cloud Filesystem. --- # tdc fs describe-file-system -Describes one locally registered Filesystem. +Describes one remote Filesystem by its server-assigned ID. The command does not require a locally stored FS token. > **Note:** > @@ -15,14 +15,14 @@ Describes one locally registered Filesystem. ```text tdc fs describe-file-system - --file-system-name + --file-system-id [--help] [--version] ``` ## Options -- `--file-system-name `: Set the file system name. \[required] +- `--file-system-id `: Set the file system ID. \[required] - `--help`: Display help information. - `--version`: Display version information. @@ -33,8 +33,8 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c - Describe a Filesystem: ```bash - # Return registration, endpoint, and region details for one Filesystem. - tdc fs describe-file-system --file-system-name workspace + # Return remote status and whether this machine has a matching local token. + tdc fs describe-file-system --file-system-id ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md index e9b2b59a04547..d0b8d6b6b1c17 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md @@ -16,7 +16,7 @@ Describes metadata for one remote path. The command alias is `tdc fs stat`. ```text tdc fs describe-file --path - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -25,7 +25,7 @@ tdc fs describe-file ## Options - `--path `: File or directory path in the TiDB Cloud file system. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -38,7 +38,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Inspect file size, metadata, tags, and revision information. - tdc fs describe-file --file-system-name workspace --path /reports/report.md + tdc fs describe-file --file-system-id --path /reports/report.md ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md index 262d717e21959..291e8da5a8d2b 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md @@ -16,7 +16,7 @@ Describes one Filesystem layer. ```text tdc fs describe-layer --layer-id - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -25,7 +25,7 @@ tdc fs describe-layer ## Options - `--layer-id `: The ID of the specified file system layer. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -38,7 +38,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Inspect one layer's base root, state, durability, and metadata. - tdc fs describe-layer --file-system-name workspace --layer-id "" + tdc fs describe-layer --file-system-id --layer-id "" ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md index 627fb2f0c0087..42ab0d9115dd9 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md @@ -16,7 +16,7 @@ Lists changes in one layer, optionally up to a sequence number. ```text tdc fs diff-layer --layer-id - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--max-seq ] @@ -26,7 +26,7 @@ tdc fs diff-layer ## Options - `--layer-id `: The ID of the layer. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--max-seq `: The highest layer sequence to include; 0 includes all layers. @@ -40,14 +40,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return the complete ordered change set for the selected layer. - tdc fs diff-layer --file-system-name workspace --layer-id "" + tdc fs diff-layer --file-system-id --layer-id "" ``` - Show an earlier layer view: ```bash # Limit the diff to changes at or before a sequence number. - tdc fs diff-layer --file-system-name workspace --layer-id "" --max-seq 100 + tdc fs diff-layer --file-system-id --layer-id "" --max-seq 100 ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-find-files.md b/ai/tdc/reference/commands/fs/tdc-fs-find-files.md index 9703d2219fb54..fdb36fdc7278a 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-find-files.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-find-files.md @@ -16,7 +16,7 @@ Finds remote paths by name, type, tag, size, or modification time. The command a ```text tdc fs find-files [--file-name-pattern ] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--layer-id ] @@ -34,7 +34,7 @@ tdc fs find-files ## Options - `--file-name-pattern `: File name pattern filter, such as `*.md`. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--layer-id `: Search files and directories within a specific file system layer. @@ -56,14 +56,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Locate Markdown files recursively under the selected remote path. - tdc fs find-files --file-system-name workspace --path /workspace --file-name-pattern "*.md" + tdc fs find-files --file-system-id --path /workspace --file-name-pattern "*.md" ``` - Find files by metadata: ```bash # Select tagged files that also meet a minimum size threshold. - tdc fs find-files --file-system-name workspace --path /workspace --tag stage=review --min-size-bytes 1024 + tdc fs find-files --file-system-id --path /workspace --tag stage=review --min-size-bytes 1024 ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-import-file-system-token.md b/ai/tdc/reference/commands/fs/tdc-fs-import-file-system-token.md new file mode 100644 index 0000000000000..bbc1ee671b665 --- /dev/null +++ b/ai/tdc/reference/commands/fs/tdc-fs-import-file-system-token.md @@ -0,0 +1,58 @@ +--- +title: tdc fs import-file-system-token +summary: Import an existing TiDB Cloud Filesystem token. +--- + +# tdc fs import-file-system-token + +Validates an existing FS token against its regional endpoint and stores it in the selected local profile. The file system ID is derived from the token; `--file-system-id` is an optional consistency assertion. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +tdc fs import-file-system-token + [--dry-run] + [--file-system-id ] + [--from-file ] + [--fs-token ] + [--help] + [--replace] + [--version] +``` + +## Options + +- `--dry-run`: Validate the token and destination without writing local credentials. +- `--file-system-id `: Assert that the token belongs to this file system ID. +- `--from-file `: Read the token from an owner-only file, or use `-` for standard input. +- `--fs-token `: Supply the token directly. Prefer `TDC_FS_TOKEN` or `--from-file` to avoid process argument exposure. +- `--help`: Display help information. +- `--replace`: Replace a different locally stored token for the same file system after validation. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). + +## Examples + +- Import a token from a protected file: + + ```bash + # Validate the token remotely and store it under its embedded file system ID. + chmod 600 ./fs-token + tdc fs import-file-system-token --from-file ./fs-token --region aws-us-east-1 + ``` + +- Import a token from standard input: + + ```bash + # Avoid placing the token in shell history or a process argument. + cat ./fs-token | tdc fs import-file-system-token --from-file - --region aws-us-east-1 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md b/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md index 8932daaa6e1ab..6221e52a388b7 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md @@ -1,11 +1,11 @@ --- title: tdc fs list-file-systems -summary: List locally registered TiDB Cloud Filesystems. +summary: List remote TiDB Cloud Filesystems in a region. --- # tdc fs list-file-systems -Lists Filesystems registered in the selected local profile. +Lists every Filesystem that the selected TiDB Cloud credentials can access in the effective region. `has_local_token` indicates whether this machine has a matching data-plane token. > **Note:** > @@ -28,10 +28,10 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ## Examples -- List locally registered Filesystems: +- List remotely managed Filesystems: ```bash - # Return the Filesystems registered under the selected local profile. + # Return the remote inventory for the profile's region without exposing tokens. tdc fs list-file-systems ``` diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-files.md b/ai/tdc/reference/commands/fs/tdc-fs-list-files.md index 8d290b8cd1427..58255a03dd957 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-files.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-files.md @@ -15,7 +15,7 @@ Lists entries below a remote path. The command alias is `tdc fs ls`. ```text tdc fs list-files - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--path ] @@ -24,7 +24,7 @@ tdc fs list-files ## Options -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--path `: File system directory path. \[default: /] @@ -38,7 +38,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return the entries under a specific Filesystem path. - tdc fs list-files --file-system-name workspace --path /reports + tdc fs list-files --file-system-id --path /reports ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md b/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md index 5a95b8f19b9f8..9f4c8ffae5264 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md @@ -15,7 +15,7 @@ Lists layers for the selected Filesystem. ```text tdc fs list-layers - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -23,7 +23,7 @@ tdc fs list-layers ## Options -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -36,7 +36,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return all layers available in the selected Filesystem. - tdc fs list-layers --file-system-name workspace + tdc fs list-layers --file-system-id ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md index 01cc0123e5019..f5741d95eb640 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md @@ -19,7 +19,7 @@ tdc fs mount-file-system [--cache-dir ] [--driver ] [--dry-run] - [--file-system-name ] + [--file-system-id ] [--foreground] [--fs-token ] [--help] @@ -44,7 +44,7 @@ tdc fs mount-file-system - `--cache-dir `: Local FUSE cache directory. If omitted, uses `~/.tdc/cache/mounts/`. - `--driver `: Mount driver: `auto`, `fuse`, or `webdav`. \[default: auto] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--foreground`: Run the mount runtime in the foreground until interrupted. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. @@ -70,28 +70,28 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Let the CLI select the default driver for the current platform. - tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace + tdc fs mount-file-system --file-system-id --mount-path /path/to/workspace ``` - Create a read-only FUSE mount: ```bash # Expose the remote namespace through FUSE without permitting writes. - tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver fuse --read-only + tdc fs mount-file-system --file-system-id --mount-path /path/to/workspace --driver fuse --read-only ``` - Use WebDAV on macOS without macFUSE: ```bash # Select WebDAV explicitly when a FUSE runtime is unavailable. - tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver webdav + tdc fs mount-file-system --file-system-id --mount-path /path/to/workspace --driver webdav ``` - Tune the FUSE read cache: ```bash # Increase cache capacity for repeated reads of medium-sized files. - tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver fuse --read-cache-size-mb 256 --read-cache-max-file-mb 16 + tdc fs mount-file-system --file-system-id --mount-path /path/to/workspace --driver fuse --read-cache-size-mb 256 --read-cache-max-file-mb 16 ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-move-file.md b/ai/tdc/reference/commands/fs/tdc-fs-move-file.md index 94c21215331a3..0988bbe323bd9 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-move-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-move-file.md @@ -18,7 +18,7 @@ tdc fs move-file --from-remote --to-remote [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--overwrite] @@ -30,7 +30,7 @@ tdc fs move-file - `--from-remote `: Source file path. \[required] - `--to-remote `: Destination file path. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--overwrite`: Replace an existing destination file. @@ -44,7 +44,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Rename or relocate an object entirely within the selected Filesystem. - tdc fs move-file --file-system-name workspace --from-remote /draft.md --to-remote /reports/final.md + tdc fs move-file --file-system-id --from-remote /draft.md --to-remote /reports/final.md ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md index 569e2af464f7d..ac435ec84dce1 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md @@ -17,7 +17,7 @@ Packs selected local overlay state into a remote archive. tdc fs pack-file-system [--archive-path ] [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--local-root ] @@ -32,7 +32,7 @@ tdc fs pack-file-system - `--archive-path `: The path for the packed archive. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--local-root `: Local overlay root containing the overlay directory. @@ -50,14 +50,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Persist the local overlay associated with an existing mount. - tdc fs pack-file-system --file-system-name workspace --mount-path /path/to/workspace + tdc fs pack-file-system --file-system-id --mount-path /path/to/workspace ``` - Pack explicit roots: ```bash # Create a portable archive from selected local and remote roots. - tdc fs pack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable + tdc fs pack-file-system --file-system-id --local-root ./overlay --remote-root /workspace --mount-profile portable ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-read-file.md b/ai/tdc/reference/commands/fs/tdc-fs-read-file.md index e8acff4f9b9a4..65a93b29782b3 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-read-file.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-read-file.md @@ -16,7 +16,7 @@ Writes a remote file or byte range to stdout. The command alias is `tdc fs cat`. ```text tdc fs read-file --path - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--length ] @@ -27,7 +27,7 @@ tdc fs read-file ## Options - `--path `: File path in the selected file system. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--length `: Byte length for a ranged read. @@ -42,14 +42,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Write the remote file contents directly to standard output. - tdc fs read-file --file-system-name workspace --path /reports/report.md + tdc fs read-file --file-system-id --path /reports/report.md ``` - Read a byte range: ```bash # Fetch only the requested range from a large remote object. - tdc fs read-file --file-system-name workspace --path /archives/large.bin --offset 1024 --length 4096 + tdc fs read-file --file-system-id --path /archives/large.bin --offset 1024 --length 4096 ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md b/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md index 9d13958f844ba..51998409b0d6d 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md @@ -17,7 +17,7 @@ Rolls back changes in one layer without committing them to the base. tdc fs rollback-layer --layer-id [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--version] @@ -27,7 +27,7 @@ tdc fs rollback-layer - `--layer-id `: The ID of the layer. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. @@ -40,7 +40,7 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Discard uncommitted changes and restore the layer's base view. - tdc fs rollback-layer --file-system-name workspace --layer-id "" + tdc fs rollback-layer --file-system-id --layer-id "" ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md b/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md index 8c505137fa4b9..95a3ff064b8e9 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md @@ -16,7 +16,7 @@ Searches remote file content, optionally in a layer. The command alias is `tdc f ```text tdc fs search-file-content --pattern - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--layer-id ] @@ -28,7 +28,7 @@ tdc fs search-file-content ## Options - `--pattern `: Content search matching pattern. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--layer-id `: Search within a file system layer. @@ -44,14 +44,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Find matching text under a remote directory and limit the result count. - tdc fs search-file-content --file-system-name workspace --path /workspace --pattern "TODO" --limit 50 + tdc fs search-file-content --file-system-id --path /workspace --pattern "TODO" --limit 50 ``` - Search content in a layer: ```bash # Inspect uncommitted layer content separately from the base Filesystem. - tdc fs search-file-content --file-system-name workspace --path /workspace --pattern "deprecated" --layer-id "" + tdc fs search-file-content --file-system-id --path /workspace --pattern "deprecated" --layer-id "" ``` ## Related documentation diff --git a/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md b/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md index bd838718c79b9..adbf21e552675 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md +++ b/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md @@ -17,7 +17,7 @@ Restores local overlay state from a remote archive. tdc fs unpack-file-system [--archive-path ] [--dry-run] - [--file-system-name ] + [--file-system-id ] [--fs-token ] [--help] [--local-root ] @@ -32,7 +32,7 @@ tdc fs unpack-file-system - `--archive-path `: The path for the packed archive. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-id `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_ID`. - `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. - `--help`: Display help information. - `--local-root `: The local overlay root to restore into. @@ -50,14 +50,14 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Restore the portable archive associated with an existing mount. - tdc fs unpack-file-system --file-system-name workspace --mount-path /path/to/workspace + tdc fs unpack-file-system --file-system-id --mount-path /path/to/workspace ``` - Unpack explicit roots without replacement: ```bash # Restore missing files while preserving existing destination entries. - tdc fs unpack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable --no-replace + tdc fs unpack-file-system --file-system-id --local-root ./overlay --remote-root /workspace --mount-profile portable --no-replace ``` ## Related documentation diff --git a/ai/tdc/reference/tdc-agent-sandbox-example.md b/ai/tdc/reference/tdc-agent-sandbox-example.md index d4d0ce5b614db..899ccc1d4b95e 100644 --- a/ai/tdc/reference/tdc-agent-sandbox-example.md +++ b/ai/tdc/reference/tdc-agent-sandbox-example.md @@ -21,7 +21,7 @@ A sandbox-local directory is fast but not durable or shared. Generic object-stor ## How TiDB Cloud CLI changes the workflow -A trusted machine provisions the Filesystem once. The sandbox receives only the Filesystem owner token, region code, and Filesystem name, and can immediately use data-plane, mount, Git, journal, and vault workflows without `tdc configure`. When an agent needs only selected secrets, use a delegated vault token instead of the owner token. +A trusted machine provisions the Filesystem once. The sandbox receives only the Filesystem owner token and region code, and can immediately use data-plane, mount, Git, journal, and vault workflows without `tdc configure`. The token identifies the Filesystem. When an agent needs only selected secrets, use a delegated vault token instead of the owner token. ## Prerequisites @@ -32,14 +32,13 @@ A trusted machine provisions the Filesystem once. The sandbox receives only the ## Step 1. Provision on the trusted machine ```bash -export TDC_FS_TOKEN="$(tdc fs create-file-system \ - --file-system-name agent-sandbox \ - --wait \ - --query fs_token \ - --output text)" +umask 077 +tdc fs create-file-system --wait > ./filesystem.json +export FILE_SYSTEM_ID="$(jq -r '.file_system_id' ./filesystem.json)" +export TDC_FS_TOKEN="$(jq -r '.fs_token' ./filesystem.json)" ``` -Record the canonical region code used by the profile, for example `aws-us-east-1`. Do not print the token. +Store the token in a secret manager, record `FILE_SYSTEM_ID` for control-plane cleanup, and record the canonical region code used by the profile, for example `aws-us-east-1`. Delete `filesystem.json` after storing the token securely. ## Step 2. Inject the minimum sandbox environment @@ -48,7 +47,6 @@ Configure the sandbox secret/environment mechanism with: ```bash TDC_FS_TOKEN= TDC_REGION_CODE=aws-us-east-1 -TDC_FS_FILE_SYSTEM_NAME=agent-sandbox ``` The sandbox does not need `TDC_PUBLIC_KEY`, `TDC_PRIVATE_KEY`, `tdc configure`, or files copied from `~/.tdc/`. @@ -78,7 +76,6 @@ On Linux with FUSE: ```bash mkdir -p "$HOME/workspace" tdc fs mount-file-system \ - --file-system-name agent-sandbox \ --mount-path "$HOME/workspace" \ --driver fuse @@ -101,7 +98,7 @@ Use `tdc fs drain-file-system --mount-path "$HOME/workspace"` separately when yo ```bash tdc fs delete-file-system \ - --file-system-name agent-sandbox + --file-system-id "$FILE_SYSTEM_ID" ``` ## Security notes diff --git a/ai/tdc/reference/tdc-ci-artifact-handoff-example.md b/ai/tdc/reference/tdc-ci-artifact-handoff-example.md index 0e4383e975505..b4a840dd6dd5f 100644 --- a/ai/tdc/reference/tdc-ci-artifact-handoff-example.md +++ b/ai/tdc/reference/tdc-ci-artifact-handoff-example.md @@ -17,7 +17,7 @@ Build and verification jobs often run on different ephemeral machines. Local out ## How TiDB Cloud CLI changes the workflow -The pipeline injects one Filesystem token, region, and name into both jobs. The producer uploads output under a run-specific path, and the consumer downloads or streams that exact path. Neither job needs TiDB Cloud API keys or a copied `~/.tdc/` directory. +The pipeline injects one Filesystem token and region into both jobs. The token identifies the Filesystem. The producer uploads output under a run-specific path, and the consumer downloads or streams that exact path. Neither job needs TiDB Cloud API keys or a copied `~/.tdc/` directory. ## Prerequisites @@ -26,7 +26,6 @@ Provision a Filesystem on a trusted machine and store these values as protected ```text TDC_FS_TOKEN TDC_REGION_CODE -TDC_FS_FILE_SYSTEM_NAME ``` Use a CI-generated run identifier such as `RUN_ID` to isolate concurrent pipelines. diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md index dcb50833c82ce..eaf6bd9201f22 100644 --- a/ai/tdc/reference/tdc-cli-reference.md +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -42,6 +42,7 @@ tdc │ └── execute-sql-statement ├── fs │ ├── create-file-system +│ ├── import-file-system-token │ ├── list-file-systems │ ├── describe-file-system │ ├── check-file-system diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md index 3c15f182bcf76..395612ee0a77c 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -1,6 +1,6 @@ --- title: TiDB Cloud CLI Configuration and Credentials -summary: Reference TiDB Cloud CLI profiles, precedence rules, local state paths, Filesystem registry, SQL credentials, mount locators, and operation logs. +summary: Reference TiDB Cloud CLI profiles, precedence rules, local state paths, Filesystem credentials, SQL credentials, mount locators, and operation logs. --- # TiDB Cloud CLI Configuration and Credentials @@ -85,24 +85,24 @@ An explicitly empty `--project-id` is invalid. When no project ID is available, Other DB commands identify resources by cluster or branch ID and do not use `project_id`. Filesystem commands do not consume the DB project default. -## Filesystem resource registry +## Filesystem credentials and remote inventory -One profile can register multiple Filesystems. Resource state is isolated from the main profile configuration: +One profile can access multiple Filesystems. Drive9's remote inventory is authoritative for resource existence and status. Local state stores only credentials and their routing hint: ```text -~/.tdc/fs_resources///config -~/.tdc/fs_resources///credentials +~/.tdc/fs_credentials///credentials ``` -The resource config contains the stored Filesystem name, tenant ID, cloud provider, region code, and creation time. The credentials file contains only the owner `api_key` and uses owner-only permissions. +The credential contains the server-assigned file system ID, canonical region code, and owner `api_key`, and uses owner-only permissions. `tdc fs list-file-systems` reads remote resources and joins only the non-secret `has_local_token` hint. Resource selection is: -1. explicit `--file-system-name`; -2. `TDC_FS_FILE_SYSTEM_NAME`; -3. fail with `fs.missing_file_system_name`. +1. explicit `--file-system-id`; +2. `TDC_FS_FILE_SYSTEM_ID`; +3. derive the ID from an explicitly supplied FS token; +4. otherwise fail with `fs.missing_file_system_id`. -`tdc` never infers a Filesystem from a saved default or from the number of registered resources. Use `--file-system-name` for one command or `TDC_FS_FILE_SYSTEM_NAME` for a shell, sandbox, or automation environment. +`tdc` never infers a Filesystem from a saved default or from the number of local credentials. Use `--file-system-id` for one command or `TDC_FS_FILE_SYSTEM_ID` for a shell, sandbox, or automation environment. FS owner credential selection for remote `fs`, `fs-git`, `fs-journal`, and owner `fs-vault` operations is: @@ -114,15 +114,14 @@ Prefer `TDC_FS_TOKEN` over a flag because flags can remain in shell history or p ## Config-free Filesystem inputs -A clean sandbox can use: +A clean sandbox needs only: ```bash export TDC_FS_TOKEN="" export TDC_REGION_CODE="aws-us-east-1" -export TDC_FS_FILE_SYSTEM_NAME="workspace" ``` -These values form an in-memory namespace only. `tdc` does not write them to `~/.tdc/`. Provisioning and deletion still require TiDB Cloud API credentials; deletion also requires the local resource registration. +These values form an in-memory namespace only. `tdc` derives the ID from the token and does not write either value to `~/.tdc/`. `TDC_FS_FILE_SYSTEM_ID` is optional and, when present, must match the token. Remote list, describe, provisioning, and deletion require TiDB Cloud API credentials; deletion does not require a local FS token. ## DB SQL credentials @@ -219,7 +218,7 @@ An integration can attach explicit process-scoped metadata without changing a pr ```bash TDC_TELEMETRY_TAG="e2b-preview" \ TDC_TELEMETRY_EXTRA='{"campaign":"launch","runtime":"e2b"}' \ -tdc fs list-files --file-system-name workspace --path / +tdc fs list-files --file-system-id --path / ``` ## Sensitive values diff --git a/ai/tdc/reference/tdc-daily-workflow-example.md b/ai/tdc/reference/tdc-daily-workflow-example.md index fd649fbb6f6bf..2427abcb98999 100644 --- a/ai/tdc/reference/tdc-daily-workflow-example.md +++ b/ai/tdc/reference/tdc-daily-workflow-example.md @@ -58,16 +58,13 @@ tdc db execute-sql-statement \ ## Step 4. Create and use a Filesystem ```bash -tdc fs create-file-system \ - --file-system-name daily-workspace +export TDC_FS_FILE_SYSTEM_ID="$(tdc fs create-file-system --query file_system_id --output text)" printf 'daily workflow\n' | tdc fs copy-file \ - --file-system-name daily-workspace \ --from-stdin \ --to-remote /notes/today.txt tdc fs list-files \ - --file-system-name daily-workspace \ --path /notes \ --output text ``` @@ -93,7 +90,7 @@ tdc update ```bash tdc fs delete-file-system \ - --file-system-name daily-workspace + --file-system-id "$TDC_FS_FILE_SYSTEM_ID" tdc db delete-db-cluster \ --db-cluster-id "" diff --git a/ai/tdc/reference/tdc-filesystem-journal.md b/ai/tdc/reference/tdc-filesystem-journal.md index 6bfc9c2d6d976..9a2efd4568df5 100644 --- a/ai/tdc/reference/tdc-filesystem-journal.md +++ b/ai/tdc/reference/tdc-filesystem-journal.md @@ -32,7 +32,7 @@ tdc fs-journal ## Prerequisites -Select a Filesystem through a profile or provide `TDC_FS_TOKEN`, `TDC_REGION_CODE`, and `TDC_FS_FILE_SYSTEM_NAME`. +Select a Filesystem by ID with locally stored credentials, or provide only `TDC_FS_TOKEN` and `TDC_REGION_CODE`; `TDC_FS_FILE_SYSTEM_ID` is an optional assertion. ## Create a journal diff --git a/ai/tdc/reference/tdc-filesystem.md b/ai/tdc/reference/tdc-filesystem.md index ad22207fe6ab8..591186f776a32 100644 --- a/ai/tdc/reference/tdc-filesystem.md +++ b/ai/tdc/reference/tdc-filesystem.md @@ -16,6 +16,7 @@ Use `tdc fs` to provision TiDB Cloud Filesystem resources and access their data ```text tdc fs ├── create-file-system +├── import-file-system-token ├── list-file-systems ├── describe-file-system ├── check-file-system @@ -52,11 +53,12 @@ tdc fs | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `create-file-system` | Provisions a Filesystem. Requires `--file-system-name`; `--wait` waits until data-plane access is ready. | `tdc fs create-file-system --file-system-name workspace --wait` | -| `list-file-systems` | Lists resources registered in the selected local profile. | `tdc fs list-file-systems --output text` | -| `describe-file-system` | Reads one locally registered resource by name. | `tdc fs describe-file-system --file-system-name workspace` | -| `check-file-system` | Verifies resource selection, endpoint resolution, credentials, and companion access. | `tdc fs check-file-system --file-system-name workspace` | -| `delete-file-system` | Requests asynchronous deletion and removes its local registration. Requires TiDB Cloud credentials and the owner resource credential. | `tdc fs delete-file-system --file-system-name workspace` | +| `create-file-system` | Provisions a Filesystem with a server-assigned ID; `--wait` waits until data-plane access is ready. | `tdc fs create-file-system --wait` | +| `import-file-system-token` | Validates and stores an existing token under its embedded file system ID. | `tdc fs import-file-system-token --from-file ./fs-token --region aws-us-east-1` | +| `list-file-systems` | Lists remote resources available to the TiDB Cloud credentials in the effective region. | `tdc fs list-file-systems --output text` | +| `describe-file-system` | Reads one remote resource by ID without requiring its FS token. | `tdc fs describe-file-system --file-system-id ` | +| `check-file-system` | Verifies resource selection, endpoint resolution, credentials, and companion access. | `tdc fs check-file-system --file-system-id ` | +| `delete-file-system` | Requests asynchronous deletion by ID and removes a matching local credential after acceptance. | `tdc fs delete-file-system --file-system-id ` | ### Data and namespace commands @@ -93,77 +95,72 @@ tdc fs | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `mount-file-system` | Mounts a resource through automatic, FUSE, or WebDAV mode. Requires `--mount-path`; select the resource with a flag or environment variable. | `tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace` | +| `mount-file-system` | Mounts a resource through automatic, FUSE, or WebDAV mode. Requires `--mount-path`; select the resource with a flag or environment variable. | `tdc fs mount-file-system --file-system-id --mount-path /path/to/workspace` | | `drain-file-system` | Flushes pending FUSE work while leaving the mount online. | `tdc fs drain-file-system --mount-path /path/to/workspace --timeout 30s` | | `unmount-file-system` | Gracefully flushes and unmounts a background FUSE or WebDAV mount. | `tdc fs unmount-file-system --mount-path /path/to/workspace` | ## Prerequisites -- Run `tdc configure` before provisioning or deleting a Filesystem. +- Run `tdc configure` before provisioning, listing, describing, or deleting Filesystems. - Install `tdc` with the release installer so the `tdc-drive9` companion is next to the `tdc` binary. +- Install `jq` to run the JSON extraction examples as written, or use an equivalent JSON processor. - Treat the returned FS owner token as a secret. -Data-plane commands can instead use an existing Filesystem with `TDC_FS_TOKEN`, `TDC_REGION_CODE`, and `TDC_FS_FILE_SYSTEM_NAME`, without TiDB Cloud API keys. +Data-plane commands can instead use an existing Filesystem with only `TDC_FS_TOKEN` and `TDC_REGION_CODE`, without TiDB Cloud API keys. `TDC_FS_FILE_SYSTEM_ID` is an optional assertion. ## Manage Filesystem resources -Create a resource and wait until data-plane access is ready: +Create a resource, wait until data-plane access is ready, and save the server-assigned ID and one-time owner token without making the file world-readable: ```bash -tdc fs create-file-system \ - --file-system-name workspace \ - --wait +umask 077 +tdc fs create-file-system --wait > ./filesystem.json +export TDC_FS_FILE_SYSTEM_ID="$(jq -r '.file_system_id' ./filesystem.json)" +export TDC_FS_TOKEN="$(jq -r '.fs_token' ./filesystem.json)" ``` Without `--wait`, `tdc` returns after Drive9 accepts provisioning. With the flag, `tdc` waits up to 10 minutes until the root is readable through the public Drive9 data-plane CLI. A failed wait leaves the resource and locally stored credential intact. -The JSON response includes `fs_token`. Capture it without displaying the complete result: +The JSON response includes `fs_token` exactly once. Store it in a secret manager, then delete `filesystem.json`. A configured machine can use the locally stored credential by ID without exporting the token. -```bash -export TDC_FS_TOKEN="$(tdc fs create-file-system \ - --file-system-name sandbox \ - --wait \ - --query fs_token \ - --output text)" -``` - -List and describe locally registered resources: +List remote resources in the effective region and describe one by ID: ```bash tdc fs list-file-systems -tdc fs describe-file-system --file-system-name workspace +tdc fs describe-file-system --file-system-id ``` Select a resource for subsequent commands in the current shell: ```bash -export TDC_FS_FILE_SYSTEM_NAME="workspace" +export TDC_FS_FILE_SYSTEM_ID="" ``` Check the selected resource and companion: ```bash -tdc fs check-file-system --file-system-name workspace +tdc fs check-file-system --file-system-id ``` Delete a resource only after removing data you need: ```bash tdc fs delete-file-system \ - --file-system-name workspace + --file-system-id ``` -Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and a locally registered resource; an FS token alone cannot delete the resource. Drive9 deletion is asynchronous, so a successfully accepted request reports `status: "deleting"` while `tdc` removes the selected local registry entry and credential. +Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and an ID, but not a local FS token. Drive9 deletion is asynchronous, so a successfully accepted request reports `status: "deleting"` while `tdc` removes only a matching ID-keyed local credential. ## Select one of multiple Filesystems One profile can own multiple resources. Selection precedence is: -1. `--file-system-name`; -2. `TDC_FS_FILE_SYSTEM_NAME`; -3. fail with `fs.missing_file_system_name`. +1. `--file-system-id`; +2. `TDC_FS_FILE_SYSTEM_ID`; +3. the ID embedded in an explicitly supplied FS token; +4. otherwise fail with `fs.missing_file_system_id`. -`tdc` does not infer a resource from the profile registry, even when only one resource is registered. This makes scripts deterministic when resources are added or removed. +`tdc` does not infer a resource from local credential count, even when only one credential exists. This makes scripts deterministic when resources are added or removed. ## Copy and read data @@ -289,7 +286,7 @@ Create the local mount path and mount in the background: ```bash mkdir -p /path/to/workspace tdc fs mount-file-system \ - --file-system-name workspace \ + --file-system-id \ --mount-path /path/to/workspace ``` @@ -326,7 +323,7 @@ RUN mkdir -p /workspace CMD ["bash"] ``` -Build the image, then pass the Filesystem owner token, canonical region code, and Filesystem name at runtime: +Build the image, then pass the Filesystem owner token and canonical region code at runtime: ```bash docker build -t tdc-fuse . @@ -337,11 +334,10 @@ docker run --rm -it \ --security-opt apparmor=unconfined \ --env TDC_FS_TOKEN \ --env TDC_REGION_CODE \ - --env TDC_FS_FILE_SYSTEM_NAME \ tdc-fuse ``` -The three environment variables must already exist in the host shell. Inside the container, mount and use the Filesystem normally: +The two environment variables must already exist in the host shell. Inside the container, mount and use the Filesystem normally: ```bash tdc fs mount --mount-path /workspace @@ -367,7 +363,7 @@ services: environment: TDC_FS_TOKEN: ${TDC_FS_TOKEN} TDC_REGION_CODE: ${TDC_REGION_CODE} - TDC_FS_FILE_SYSTEM_NAME: ${TDC_FS_FILE_SYSTEM_NAME} + TDC_FS_FILE_SYSTEM_ID: ${TDC_FS_FILE_SYSTEM_ID} stdin_open: true tty: true ``` @@ -388,7 +384,7 @@ macOS intentionally keeps WebDAV as the automatic choice even when macFUSE is in ```bash tdc fs mount-file-system \ - --file-system-name workspace \ + --file-system-id \ --mount-path /path/to/workspace \ --driver fuse ``` @@ -397,7 +393,7 @@ Explicit FUSE supports cache controls: ```bash tdc fs mount-file-system \ - --file-system-name workspace \ + --file-system-id \ --mount-path /path/to/workspace \ --driver fuse \ --cache-dir "$HOME/.tdc/cache/workspace" \ @@ -415,7 +411,7 @@ Prefer an allowed mount path: ```bash mkdir -p "$HOME/workspace" tdc fs mount-file-system \ - --file-system-name workspace \ + --file-system-id \ --mount-path "$HOME/workspace" ``` @@ -425,7 +421,7 @@ For a system-level path, `/mnt/workspace` is allowed by the default profile: sudo mkdir -p /mnt/workspace sudo chown "$(id -u):$(id -g)" /mnt/workspace tdc fs mount-file-system \ - --file-system-name workspace \ + --file-system-id \ --mount-path /mnt/workspace ``` diff --git a/ai/tdc/reference/tdc-parallel-agent-dataset-example.md b/ai/tdc/reference/tdc-parallel-agent-dataset-example.md index 9fdec6030c75f..e6f10eef27842 100644 --- a/ai/tdc/reference/tdc-parallel-agent-dataset-example.md +++ b/ai/tdc/reference/tdc-parallel-agent-dataset-example.md @@ -24,33 +24,31 @@ An owner uploads the corpus once. Every worker selects the same Filesystem and m On a trusted machine: ```bash -tdc fs create-file-system \ - --file-system-name shared-corpus \ - --wait +umask 077 +tdc fs create-file-system --wait > ./filesystem.json +export TDC_FS_FILE_SYSTEM_ID="$(jq -r '.file_system_id' ./filesystem.json)" +export TDC_FS_TOKEN="$(jq -r '.fs_token' ./filesystem.json)" tdc fs copy-file \ - --file-system-name shared-corpus \ --from-local ./corpus \ --to-remote /datasets/corpus \ --recursive tdc fs find-files \ - --file-system-name shared-corpus \ --path /datasets/corpus \ --file-name-pattern "*.pdf" \ --output text ``` -Transfer the returned FS token through a secret manager. +Transfer the FS token and canonical region code through a secret manager. Delete `filesystem.json` after storing the token securely. ## Step 2. Mount in each worker -Inject the resource token, region, and name into each worker, then run: +Inject `TDC_FS_TOKEN` and `TDC_REGION_CODE` into each worker, then run: ```bash mkdir -p "$HOME/corpus" tdc fs mount-file-system \ - --file-system-name shared-corpus \ --mount-path "$HOME/corpus" \ --remote-path /datasets/corpus \ --read-only diff --git a/ai/tdc/reference/tdc-persistent-agent-state-example.md b/ai/tdc/reference/tdc-persistent-agent-state-example.md index d91d501e2c28b..47b0fbfaae217 100644 --- a/ai/tdc/reference/tdc-persistent-agent-state-example.md +++ b/ai/tdc/reference/tdc-persistent-agent-state-example.md @@ -17,7 +17,7 @@ An agent sandbox can disappear after a timeout, failure, or deployment. Plans, i ## How TiDB Cloud CLI changes the workflow -A trusted machine provisions one Filesystem. Each sandbox receives only the Filesystem token, region code, and name. The agent writes durable task state to the remote namespace and records workflow transitions in a journal. A replacement sandbox can read both without receiving TiDB Cloud control-plane keys. +A trusted machine provisions one Filesystem. Each sandbox receives only the Filesystem token and region code. The token identifies the Filesystem, so the agent can write durable task state to the remote namespace and record workflow transitions in a journal without receiving TiDB Cloud control-plane keys. ## Step 1. Provision the state Filesystem @@ -25,13 +25,12 @@ On a trusted machine: ```bash export TDC_FS_TOKEN="$(tdc fs create-file-system \ - --file-system-name agent-state \ --wait \ --query fs_token \ --output text)" ``` -Store `TDC_FS_TOKEN` in a secret manager. Also record the configured canonical region code and the Filesystem name. +Store `TDC_FS_TOKEN` in a secret manager. Also record the configured canonical region code. The token contains the server-assigned Filesystem ID. ## Step 2. Start the first sandbox @@ -40,7 +39,6 @@ Inject the following environment variables: ```bash export TDC_FS_TOKEN="" export TDC_REGION_CODE="aws-us-east-1" -export TDC_FS_FILE_SYSTEM_NAME="agent-state" ``` Write a plan and create a workflow journal: @@ -62,7 +60,7 @@ tdc fs-journal append-journal-entries \ ## Step 3. Resume in a replacement sandbox -Inject the same three FS variables into the new sandbox, then restore the durable state: +Inject the same two FS variables into the new sandbox, then restore the durable state: ```bash tdc fs read-file --path /tasks/task-42/plan.md diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/tdc/reference/tdc-regions-security-and-limitations.md index 1c018a084a04c..2140512803433 100644 --- a/ai/tdc/reference/tdc-regions-security-and-limitations.md +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -45,7 +45,7 @@ The hosted manifest is authoritative and can change during preview. A profile in | --- | --- | | `tdc configure`, `tdc organization`, all `tdc db` control-plane operations | TiDB Cloud API public/private key | | `tdc fs create-file-system` | TiDB Cloud API key | -| `tdc fs delete-file-system` | TiDB Cloud API key, local resource registration, and owner resource credential | +| `tdc fs delete-file-system` | TiDB Cloud API key and file system ID | | Remote file, layer, pack, mount, Git, journal, and owner vault operations | FS owner token or registered resource credential | | Delegated vault read, list, run, or mount | Scope-appropriate delegated vault token | | Drain and unmount after a successful background mount | Non-secret mount locator in the same `HOME` | @@ -56,7 +56,7 @@ TiDB Cloud API calls use Digest authentication. SQL HTTPS execution uses generat - Create TiDB Cloud API keys with only the organization and project access required for the workflow. Do not reuse a personal administrator key in unattended automation. - Inject automation credentials from a CI secret store or runtime secret manager. Do not place credentials in source control, container images, shell scripts, or command-line arguments that can appear in process listings and shell history. -- Do not copy the complete `~/.tdc/` directory into an agent sandbox. For an existing Filesystem, pass only `TDC_FS_TOKEN`, `TDC_REGION_CODE`, and `TDC_FS_FILE_SYSTEM_NAME`. +- Do not copy the complete `~/.tdc/` directory into an agent sandbox. For an existing Filesystem, pass only `TDC_FS_TOKEN` and `TDC_REGION_CODE`; use `TDC_FS_FILE_SYSTEM_ID` only as an optional assertion. - Treat an FS owner token as full access to that Filesystem. When an agent needs only selected secrets, create a vault grant with the narrowest field scope and shortest practical TTL, and pass the delegated vault token instead. - Use `--read-only` for SQL inspection by untrusted or exploratory agents. Use `--admin` only for DDL or privilege management, and use `--read-write` only when data changes are intended. - Use `--dry-run` before destructive control-plane operations. Keep `~/.tdc/credentials`, resource credentials, and DB SQL credentials owner-readable only. @@ -92,7 +92,7 @@ Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path - SQL execution accepts one statement per invocation. - Read-write is the default SQL role; use explicit role flags in security-sensitive automation. - Journals are append-only and the current public command surface has no journal delete command. -- Filesystem resource list and describe commands operate on the local registry; they are not an organization-wide discovery API. +- Filesystem list and describe commands query the region-scoped remote inventory with TiDB Cloud credentials. They do not aggregate across regions. - Telemetry management commands are intentionally not implemented. Control telemetry through `~/.tdc/.preferences` or `TDC_TELEMETRY`; serverless-function deployment, Homebrew, and Scoop distribution are not implemented. - The TiDB Cloud CLI depends on its installed `tdc-drive9` companion for all public Filesystem runtime behavior. diff --git a/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md b/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md index 38a8f9a91a9bd..6347421d2eea7 100644 --- a/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md +++ b/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md @@ -21,7 +21,7 @@ Local disks do not provide a shared namespace. Commands such as `scp` and archiv ## How TiDB Cloud CLI changes the workflow -Both machines select the same TiDB Cloud Filesystem. Data-plane commands and the mounted path address one remote namespace, so a write from either interface becomes visible through the other after it is flushed. Machine B needs only the Filesystem token, region code, and name; it does not need TiDB Cloud API keys or a copied profile. +Both machines select the same TiDB Cloud Filesystem. Data-plane commands and the mounted path address one remote namespace, so a write from either interface becomes visible through the other after it is flushed. Machine B needs only the Filesystem token and region code; the token identifies the Filesystem, so it does not need TiDB Cloud API keys or a copied profile. ## Prerequisites @@ -32,26 +32,23 @@ Both machines select the same TiDB Cloud Filesystem. Data-plane commands and the ## Step 1. Create the Filesystem on machine A ```bash -export TDC_FS_TOKEN="$(tdc fs create-file-system \ - --file-system-name shared-workspace \ - --wait \ - --query fs_token \ - --output text)" +umask 077 +tdc fs create-file-system --wait > ./filesystem.json +export FILE_SYSTEM_ID="$(jq -r '.file_system_id' ./filesystem.json)" +export TDC_FS_TOKEN="$(jq -r '.fs_token' ./filesystem.json)" printf 'from machine A\n' | tdc fs copy-file \ - --file-system-name shared-workspace \ --from-stdin \ --to-remote /shared/origin.txt ``` -Transfer the token through a secret manager. Also communicate the canonical region code and Filesystem name. +Transfer the token through a secret manager and communicate the canonical region code. Keep `FILE_SYSTEM_ID` on machine A for control-plane operations, then delete `filesystem.json` after storing the token securely. ## Step 2. Configure machine B in memory ```bash export TDC_FS_TOKEN="" export TDC_REGION_CODE="aws-us-east-1" -export TDC_FS_FILE_SYSTEM_NAME="shared-workspace" ``` No `tdc configure` is required. @@ -68,7 +65,6 @@ printf 'from machine B\n' | tdc fs copy-file --from-stdin --to-remote /shared/se ```bash mkdir -p /path/to/shared-workspace tdc fs mount-file-system \ - --file-system-name shared-workspace \ --mount-path /path/to/shared-workspace cat /path/to/shared-workspace/shared/origin.txt @@ -84,14 +80,14 @@ Stop writers and unmount either driver. A graceful FUSE unmount automatically dr ```bash tdc fs unmount-file-system --mount-path /path/to/shared-workspace -unset TDC_FS_TOKEN TDC_REGION_CODE TDC_FS_FILE_SYSTEM_NAME +unset TDC_FS_TOKEN TDC_REGION_CODE ``` On machine A: ```bash tdc fs delete-file-system \ - --file-system-name shared-workspace + --file-system-id "$FILE_SYSTEM_ID" ``` ## Security notes diff --git a/ai/tdc/reference/tdc-troubleshooting.md b/ai/tdc/reference/tdc-troubleshooting.md index 505336b694dd2..53480fd331e5c 100644 --- a/ai/tdc/reference/tdc-troubleshooting.md +++ b/ai/tdc/reference/tdc-troubleshooting.md @@ -44,33 +44,43 @@ If no virtual project appears, confirm the API key's organization and project ac ## Filesystem token is missing -For a clean sandbox, provide all three values: +For a clean sandbox, provide the token and region. `tdc` derives the file system ID from the token: ```bash export TDC_FS_TOKEN="" export TDC_REGION_CODE="aws-us-east-1" -export TDC_FS_FILE_SYSTEM_NAME="workspace" tdc fs check-file-system ``` -The FS token is not the TiDB Cloud API private key. +The FS token is not the TiDB Cloud API private key. `TDC_FS_FILE_SYSTEM_ID` is optional when a token is supplied; set it only when you want `tdc` to verify that a separately distributed ID matches the token. + +If the token is known but is not stored on the current machine, import it and then select the derived ID: + +```bash +# Store a known token without requiring TiDB Cloud API keys. +chmod 600 ./fs-token +tdc fs import-file-system-token --from-file ./fs-token --region aws-us-east-1 +tdc fs list-files --file-system-id --path / +``` + +The current Preview cannot regenerate a lost Filesystem token. A remote Filesystem can still be listed, described, or deleted with TiDB Cloud API keys, but its data cannot be read or mounted until a valid known token is supplied. ## Filesystem selection is missing -List registered resources and select one explicitly: +List remote resources in the configured region with TiDB Cloud API keys and select one explicitly: ```bash tdc fs list-file-systems --output text -tdc fs list-files --file-system-name workspace --path / +tdc fs list-files --file-system-id --path / ``` Or select the Filesystem for subsequent commands in the current shell: ```bash -export TDC_FS_FILE_SYSTEM_NAME="workspace" +export TDC_FS_FILE_SYSTEM_ID="" ``` -The TiDB Cloud CLI intentionally does not infer a Filesystem from the local registry, including when only one resource is registered. +The TiDB Cloud CLI intentionally does not infer a Filesystem from local credential count, including when only one credential exists. Supply its ID or an FS token whose embedded ID can be derived. ## Filesystem region is unsupported @@ -195,7 +205,7 @@ List resources and identify only those created by your workflow. Use describe be ```bash tdc db describe-db-cluster --db-cluster-id "" -tdc fs describe-file-system --file-system-name "" +tdc fs describe-file-system --file-system-id "" ``` Preview supported cleanup: @@ -203,7 +213,7 @@ Preview supported cleanup: ```bash tdc db delete-db-cluster --db-cluster-id "" --dry-run tdc fs delete-file-system \ - --file-system-name "" \ + --file-system-id "" \ --dry-run ``` diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index a66d31659f73f..1700af7d5389d 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -75,25 +75,23 @@ Complete either the Filesystem workflow or the Starter database workflow. ### Option A: Write and read a file -Create a Filesystem and wait until it is ready: +Create a Filesystem, wait until it is ready, and save its server-assigned ID: ```bash -tdc fs create-file-system \ - --file-system-name quickstart-fs \ +export TDC_FS_FILE_SYSTEM_ID="$(tdc fs create-file-system \ --wait \ - --output text + --query file_system_id \ + --output text)" ``` `tdc` stores the Filesystem credential locally. Write and read a file directly: ```bash printf 'hello from tdc\n' | tdc fs copy-file \ - --file-system-name quickstart-fs \ --from-stdin \ --to-remote /hello.txt tdc fs read-file \ - --file-system-name quickstart-fs \ --path /hello.txt ``` @@ -107,7 +105,8 @@ Clean up: ```bash tdc fs delete-file-system \ - --file-system-name quickstart-fs + --file-system-id "$TDC_FS_FILE_SYSTEM_ID" +unset TDC_FS_FILE_SYSTEM_ID ``` ### Option B: Query a Starter database From c6764a86810a1f3a5849e9d346f45cb74cb8b300 Mon Sep 17 00:00:00 2001 From: Cheese Date: Fri, 7 Aug 2026 22:10:51 +0800 Subject: [PATCH 25/29] docs: document explicit database cluster type --- .../commands/db/tdc-db-create-db-cluster.md | 16 ++++++++-------- .../commands/db/tdc-db-list-db-clusters.md | 18 +++++++++--------- ai/tdc/reference/tdc-cli-reference.md | 5 +++-- .../tdc-configuration-and-credentials.md | 4 ++-- ai/tdc/reference/tdc-daily-workflow-example.md | 4 +++- .../reference/tdc-install-configure-update.md | 2 +- ai/tdc/reference/tdc-organization.md | 1 + ai/tdc/reference/tdc-starter-database.md | 18 ++++++++++-------- ai/tdc/reference/tdc-troubleshooting.md | 2 +- ai/tdc/tdc-overview.md | 2 +- ai/tdc/tdc-quick-start.md | 1 + 11 files changed, 40 insertions(+), 33 deletions(-) diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md index b92722a5ccf5b..76f0f9b3fd3a3 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md +++ b/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md @@ -5,7 +5,7 @@ summary: Create a TiDB Cloud Starter cluster. # tdc db create-db-cluster -Creates a Starter cluster. `--db-cluster-type` defaults to `starter`, and `--wait` waits for the cluster to become `ACTIVE`. Project selection uses an explicit `--project-id`, then the configured virtual project, then the TiDB Cloud account default. The TiDB Cloud CLI validates the returned service plan; if verification fails after creation is accepted, it reports the cluster ID and retains the cluster for inspection. +Creates a Starter cluster. The required `--db-cluster-type` must be `starter`; there is no implicit type. `--wait` waits for the cluster to become `ACTIVE`. Project selection uses an explicit `--project-id`, then the configured virtual project, then the TiDB Cloud account default. The TiDB Cloud CLI validates the returned service plan; if verification fails after creation is accepted, it reports the cluster ID and retains the cluster for inspection. > **Note:** > @@ -16,7 +16,7 @@ Creates a Starter cluster. `--db-cluster-type` defaults to `starter`, and `--wai ```text tdc db create-db-cluster --db-cluster-name - [--db-cluster-type ] + --db-cluster-type [--dry-run] [--help] [--monthly-spending-limit-usd-cents ] @@ -28,7 +28,7 @@ tdc db create-db-cluster ## Options - `--db-cluster-name `: Starter DB cluster display name. \[required] -- `--db-cluster-type `: DB cluster type; must be `starter`. \[default: starter] +- `--db-cluster-type `: DB cluster type; must be `starter`. \[required] - `--dry-run`: Validate the request without applying changes. - `--help`: Display help information. - `--monthly-spending-limit-usd-cents `: Monthly spending limit in USD cents; omit to use the API default. @@ -44,35 +44,35 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Wait until the new Starter cluster reaches the ACTIVE state. - tdc db create-db-cluster --db-cluster-name app-db --wait + tdc db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --wait ``` - Create a cluster asynchronously: ```bash # Return after TiDB Cloud accepts creation so another process can poll the cluster. - tdc db create-db-cluster --db-cluster-name background-db + tdc db create-db-cluster --db-cluster-type starter --db-cluster-name background-db ``` - Preview cluster creation: ```bash # Validate the request and resolved defaults without creating a cluster. - tdc db create-db-cluster --db-cluster-name app-db --dry-run + tdc db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --dry-run ``` - Create a cluster in an explicit project: ```bash # Override the configured virtual project for this cluster. - tdc db create-db-cluster --db-cluster-name project-db --project-id "" --wait + tdc db create-db-cluster --db-cluster-type starter --db-cluster-name project-db --project-id "" --wait ``` - Set a monthly spending limit: ```bash # Create a paid Starter cluster with a monthly limit expressed in US dollar cents. - tdc db create-db-cluster --db-cluster-name production-db --monthly-spending-limit-usd-cents 1000 --wait + tdc db create-db-cluster --db-cluster-type starter --db-cluster-name production-db --monthly-spending-limit-usd-cents 1000 --wait ``` ## Related documentation diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md index b8320f6857697..7ba4a2a29a676 100644 --- a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md +++ b/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md @@ -5,7 +5,7 @@ summary: List TiDB Cloud Starter clusters. # tdc db list-db-clusters -Lists verified Starter clusters in the effective region with optional pagination, filtering, ordering, and JMESPath projection. Cross-region, non-Starter, and unverifiable clusters are omitted. The command preserves `next_page_token` after filtering and omits the server `total_size`, which can include resources outside the verified result. +Lists verified Starter clusters in the effective region with pagination, filtering, ordering, and JMESPath projection. The required `--db-cluster-type` must be `starter`. Cross-region, non-Starter, and unverifiable clusters are omitted. The command incrementally fills each result page from TiDB Cloud API pages and returns an opaque tdc `next_page_token`; it omits the server `total_size`, which can include resources outside the verified result. > **Note:** > @@ -15,23 +15,23 @@ Lists verified Starter clusters in the effective region with optional pagination ```text tdc db list-db-clusters + --db-cluster-type [--filter ] [--help] [--order-by ] [--page-size ] [--page-token ] - [--skip ] [--version] ``` ## Options +- `--db-cluster-type `: DB cluster type; must be `starter`. \[required] - `--filter `: Starter API filter expression. - `--help`: Display help information. - `--order-by `: Starter API orderBy expression. -- `--page-size `: Number of clusters to request; 0 uses the API default. -- `--page-token `: Page token returned by a previous list-db-clusters call. -- `--skip `: Number of clusters to skip. +- `--page-size `: Number of verified clusters to return; 0 returns 10 and the maximum is 1000. +- `--page-token `: Opaque tdc page token returned by a previous compatible list-db-clusters call. - `--version`: Display version information. For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). @@ -42,24 +42,24 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return Starter clusters in the profile's configured region as structured JSON. - tdc db list-db-clusters + tdc db list-db-clusters --db-cluster-type starter ``` - List clusters in another region: ```bash # Override the region for this invocation without changing the profile. - tdc --region aws-us-west-2 db list-db-clusters + tdc --region aws-us-west-2 db list-db-clusters --db-cluster-type starter ``` - Select cluster fields: ```bash # Reduce the result to IDs, names, and lifecycle states. - tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name,state:state}' + tdc db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name,state:state}' ``` -The effective region resolves from global `--region`, then `TDC_REGION_CODE`, then the selected profile's `region_code`. User-supplied `--filter` expressions are combined with this mandatory region scope and cannot expand the result to other regions. +The effective region resolves from global `--region`, then `TDC_REGION_CODE`, then the selected profile's `region_code`. User-supplied `--filter` expressions are combined with this mandatory region scope and cannot expand the result to other regions. A page token can be reused only with the same profile, cluster type, region, filter, and ordering. If its replay page changed, restart the listing without `--page-token`. ## Related documentation diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md index dcb50833c82ce..5763211db801b 100644 --- a/ai/tdc/reference/tdc-cli-reference.md +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -128,13 +128,13 @@ Command pages document `--help`, `--version`, and all command-specific options s Structured control-plane commands return JSON by default: ```bash -tdc db list-db-clusters +tdc db list-db-clusters --db-cluster-type starter ``` Use text output for terminal inspection: ```bash -tdc db list-db-clusters --output text +tdc db list-db-clusters --db-cluster-type starter --output text ``` Raw byte-oriented commands such as `tdc fs read-file` and `tdc fs copy-file --to-stdout` write file content directly. @@ -145,6 +145,7 @@ Raw byte-oriented commands such as `tdc fs read-file` and `tdc fs copy-file --to ```bash tdc db list-db-clusters \ + --db-cluster-type starter \ --query 'clusters[].{id:id,name:display_name,state:state}' tdc organization list-projects \ diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md index 3c15f182bcf76..8ccee371b5962 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -179,7 +179,7 @@ This log is local audit/debug data, not telemetry. It can include command names, Disable it for one process: ```bash -TDC_LOGGING=off tdc db list-db-clusters +TDC_LOGGING=off tdc db list-db-clusters --db-cluster-type starter ``` Or create or edit `~/.tdc/.preferences`: @@ -209,7 +209,7 @@ enabled = false Disable it for one process without changing the file: ```bash -TDC_TELEMETRY=off tdc db list-db-clusters +TDC_TELEMETRY=off tdc db list-db-clusters --db-cluster-type starter ``` The TiDB Cloud CLI creates `~/.tdc/.telemetry-installation-id` lazily for the first eligible event and restricts it to the current user where POSIX permissions are available. Delete this file to reset the pseudonymous identity. Telemetry delivery is lossy and never changes command output, errors, or exit status. diff --git a/ai/tdc/reference/tdc-daily-workflow-example.md b/ai/tdc/reference/tdc-daily-workflow-example.md index fd649fbb6f6bf..b016c6ed88fe6 100644 --- a/ai/tdc/reference/tdc-daily-workflow-example.md +++ b/ai/tdc/reference/tdc-daily-workflow-example.md @@ -20,7 +20,7 @@ This example follows a typical operator workflow across TiDB Cloud Starter and T ```bash tdc organization list-projects --output text -tdc db list-db-clusters --output text +tdc db list-db-clusters --db-cluster-type starter --output text tdc fs list-file-systems --output text ``` @@ -28,10 +28,12 @@ tdc fs list-file-systems --output text ```bash tdc db create-db-cluster \ + --db-cluster-type starter \ --db-cluster-name daily-demo \ --dry-run tdc db create-db-cluster \ + --db-cluster-type starter \ --db-cluster-name daily-demo \ --wait ``` diff --git a/ai/tdc/reference/tdc-install-configure-update.md b/ai/tdc/reference/tdc-install-configure-update.md index 35f05c93b84cb..b7f6e43605666 100644 --- a/ai/tdc/reference/tdc-install-configure-update.md +++ b/ai/tdc/reference/tdc-install-configure-update.md @@ -98,7 +98,7 @@ You can also provide `--tdc-public-key`, `--tdc-private-key`, and `--region-code Configuration precedence is command flag, environment variable, then saved profile. The global `--region` overrides only the placement for the current command: ```bash -tdc db list-db-clusters --profile staging --region aws-us-west-2 +tdc db list-db-clusters --db-cluster-type starter --profile staging --region aws-us-west-2 ``` ## Get help and version information diff --git a/ai/tdc/reference/tdc-organization.md b/ai/tdc/reference/tdc-organization.md index c2f1967c26354..59d6d22c48c91 100644 --- a/ai/tdc/reference/tdc-organization.md +++ b/ai/tdc/reference/tdc-organization.md @@ -63,6 +63,7 @@ project_id = "..." ```bash tdc db create-db-cluster \ + --db-cluster-type starter \ --db-cluster-name project-specific-cluster \ --project-id "" ``` diff --git a/ai/tdc/reference/tdc-starter-database.md b/ai/tdc/reference/tdc-starter-database.md index f6aa86f00d1c3..87c9ec9e87b35 100644 --- a/ai/tdc/reference/tdc-starter-database.md +++ b/ai/tdc/reference/tdc-starter-database.md @@ -33,8 +33,8 @@ tdc db | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `create-db-cluster` | Creates a Starter cluster. Requires `--db-cluster-name`; `--db-cluster-type` is optional and defaults to `starter`. Use `--wait` for an `ACTIVE` result. | `tdc db create-db-cluster --db-cluster-name app-db --wait` | -| `list-db-clusters` | Lists Starter clusters in the effective region with pagination, filter, ordering, and query support. | `tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name}'` | +| `create-db-cluster` | Creates a Starter cluster. Requires `--db-cluster-type starter` and `--db-cluster-name`. Use `--wait` for an `ACTIVE` result. | `tdc db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --wait` | +| `list-db-clusters` | Lists Starter clusters in the effective region. Requires `--db-cluster-type starter` and supports pagination, filtering, ordering, and queries. | `tdc db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name}'` | | `describe-db-cluster` | Reads one cluster by `--db-cluster-id`; `--view FULL` requests expanded fields. | `tdc db describe-db-cluster --db-cluster-id "" --view FULL` | | `update-db-cluster` | Changes the name or monthly spending limit of one cluster. Supports `--dry-run`. | `tdc db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2` | | `delete-db-cluster` | Deletes one cluster by ID. Use `--wait` to wait until deletion is observable. | `tdc db delete-db-cluster --db-cluster-id "" --wait` | @@ -58,25 +58,27 @@ Preview and create a Starter cluster: ```bash tdc db create-db-cluster \ + --db-cluster-type starter \ --db-cluster-name demo-cluster \ --dry-run tdc db create-db-cluster \ + --db-cluster-type starter \ --db-cluster-name demo-cluster ``` -An explicit `--project-id` overrides the configured virtual project. If neither is available, TiDB Cloud selects the account's default project. `--db-cluster-type` is optional and defaults to `starter`; the only accepted explicit value is `starter`. `--monthly-spending-limit-usd-cents` is optional; setting it can require a payment method. +An explicit `--project-id` overrides the configured virtual project. If neither is available, TiDB Cloud selects the account's default project. `--db-cluster-type starter` is required for cluster creation and listing; no type is inferred. `--monthly-spending-limit-usd-cents` is optional; setting it can require a payment method. List and filter clusters: ```bash -tdc db list-db-clusters -tdc db list-db-clusters --page-size 20 --order-by "createTime desc" -tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name,state:state}' -tdc --region aws-us-west-2 db list-db-clusters +tdc db list-db-clusters --db-cluster-type starter +tdc db list-db-clusters --db-cluster-type starter --page-size 20 --order-by "createTime desc" +tdc db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name,state:state}' +tdc --region aws-us-west-2 db list-db-clusters --db-cluster-type starter ``` -The list command also accepts `--page-token`, `--filter`, and `--skip`. It always scopes the API request to the effective region, which resolves from global `--region`, then `TDC_REGION_CODE`, then the selected profile. The shared TiDB Cloud API can return multiple service plans or unverifiable resources, so the TiDB Cloud CLI defensively filters each page to verified Starter clusters in that region. It preserves `next_page_token` but omits `total_size`, because the server total can include clusters outside the verified result. A user `--filter` is combined with the mandatory region filter and cannot expand the result to another region. +The list command also accepts `--page-token` and `--filter`. It always scopes the API request to the effective region, which resolves from global `--region`, then `TDC_REGION_CODE`, then the selected profile. The shared TiDB Cloud API can return multiple service plans or unverifiable resources, so the TiDB Cloud CLI scans upstream pages and incrementally fills a tdc result page with verified Starter clusters in that region. Its opaque `next_page_token` binds the profile, type, region, filter, and ordering; it omits `total_size`, because the server total can include clusters outside the verified result. A user `--filter` is combined with the mandatory region filter and cannot expand the result to another region. Describe and update a cluster: diff --git a/ai/tdc/reference/tdc-troubleshooting.md b/ai/tdc/reference/tdc-troubleshooting.md index 505336b694dd2..238b351992435 100644 --- a/ai/tdc/reference/tdc-troubleshooting.md +++ b/ai/tdc/reference/tdc-troubleshooting.md @@ -98,7 +98,7 @@ Do not copy an arbitrary standalone Drive9 binary into place. Quota and capacity errors can mean the organization has reached its free Starter limit. List existing resources before creating another: ```bash -tdc db list-db-clusters --output text +tdc db list-db-clusters --db-cluster-type starter --output text tdc fs list-file-systems --output text ``` diff --git a/ai/tdc/tdc-overview.md b/ai/tdc/tdc-overview.md index d27eada2ac2e5..458894113df60 100644 --- a/ai/tdc/tdc-overview.md +++ b/ai/tdc/tdc-overview.md @@ -52,7 +52,7 @@ The `tdc` executable has a two-level command model: tdc ``` -Examples include `tdc db list-db-clusters`, `tdc fs copy-file`, and `tdc fs-journal verify-journal`. The top-level `tdc configure` and `tdc update` commands configure and maintain the CLI. +Examples include `tdc db list-db-clusters --db-cluster-type starter`, `tdc fs copy-file`, and `tdc fs-journal verify-journal`. The top-level `tdc configure` and `tdc update` commands configure and maintain the CLI. ## TiDB Cloud CLI and Drive9 diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index a66d31659f73f..5dd4814164f37 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -116,6 +116,7 @@ Create a Starter cluster and save its ID: ```bash export TDC_DB_CLUSTER_ID="$(tdc db create-db-cluster \ + --db-cluster-type starter \ --db-cluster-name quickstart-db \ --wait \ --query id \ From 3bb30dbc73205ea815069c0fd9d4fb16f29b0171 Mon Sep 17 00:00:00 2001 From: Cheese Date: Mon, 10 Aug 2026 18:05:33 +0800 Subject: [PATCH 26/29] docs: rename TiDB Cloud CLI command to ti --- TOC-ai.md | 174 ++++++------- ai/_index.md | 52 ++-- .../tdc-fs-git-hydrate-git-workspace.md | 48 ---- .../commands/fs/tdc-fs-list-file-systems.md | 40 --- .../reference/commands/tdc/tdc-configure.md | 58 ----- .../reference/tdc-install-configure-update.md | 180 ------------- ai/tdc/reference/tdc-organization.md | 74 ------ ai/tdc/tdc-overview.md | 102 -------- .../db/ti-db-create-db-cluster-branch.md} | 16 +- .../commands/db/ti-db-create-db-cluster.md} | 22 +- .../commands/db/ti-db-create-db-sql-users.md} | 18 +- .../db/ti-db-delete-db-cluster-branch.md} | 14 +- .../commands/db/ti-db-delete-db-cluster.md} | 16 +- .../db/ti-db-describe-db-cluster-branch.md} | 14 +- .../commands/db/ti-db-describe-db-cluster.md} | 14 +- .../db/ti-db-execute-sql-statement.md} | 20 +- .../db/ti-db-format-db-connection-string.md} | 20 +- .../db/ti-db-list-db-cluster-branches.md} | 14 +- .../commands/db/ti-db-list-db-clusters.md} | 24 +- .../commands/db/ti-db-update-db-cluster.md} | 16 +- .../fs-git/ti-fs-git-add-git-worktree.md} | 20 +- .../fs-git/ti-fs-git-clone-git-workspace.md} | 22 +- .../fs-git/ti-fs-git-hydrate-git-workspace.md | 48 ++++ .../fs-git/ti-fs-git-remove-git-worktree.md} | 20 +- .../ti-fs-journal-append-journal-entries.md} | 22 +- .../ti-fs-journal-create-journal.md} | 20 +- .../ti-fs-journal-read-journal-entries.md} | 20 +- .../ti-fs-journal-search-journal-entries.md} | 22 +- .../ti-fs-journal-verify-journal.md} | 18 +- .../fs-vault/ti-fs-vault-create-grant.md} | 20 +- .../fs-vault/ti-fs-vault-create-secret.md} | 22 +- .../fs-vault/ti-fs-vault-delete-grant.md} | 20 +- .../fs-vault/ti-fs-vault-delete-secret.md} | 18 +- .../ti-fs-vault-list-audit-events.md} | 20 +- .../fs-vault/ti-fs-vault-list-secrets.md} | 22 +- .../fs-vault/ti-fs-vault-mount-vault.md} | 22 +- .../fs-vault/ti-fs-vault-read-secret.md} | 24 +- .../fs-vault/ti-fs-vault-replace-secret.md} | 20 +- .../fs-vault/ti-fs-vault-run-with-secret.md} | 22 +- .../fs-vault/ti-fs-vault-unmount-vault.md} | 16 +- .../commands/fs/ti-fs-check-file-system.md} | 18 +- .../commands/fs/ti-fs-chmod-file.md} | 20 +- .../commands/fs/ti-fs-commit-layer.md} | 18 +- .../reference/commands/fs/ti-fs-copy-file.md} | 30 +-- .../commands/fs/ti-fs-create-directory.md} | 20 +- .../commands/fs/ti-fs-create-file-system.md} | 18 +- .../commands/fs/ti-fs-create-hardlink.md} | 20 +- .../fs/ti-fs-create-layer-checkpoint.md} | 20 +- .../commands/fs/ti-fs-create-layer.md} | 20 +- .../commands/fs/ti-fs-create-symlink.md} | 20 +- .../commands/fs/ti-fs-delete-file-system.md} | 18 +- .../commands/fs/ti-fs-delete-file.md} | 22 +- .../fs/ti-fs-describe-file-system.md} | 14 +- .../commands/fs/ti-fs-describe-file.md} | 20 +- .../commands/fs/ti-fs-describe-layer.md} | 18 +- .../commands/fs/ti-fs-diff-layer.md} | 20 +- .../commands/fs/ti-fs-drain-file-system.md} | 16 +- .../commands/fs/ti-fs-find-files.md} | 22 +- .../commands/fs/ti-fs-list-file-systems.md | 40 +++ .../commands/fs/ti-fs-list-files.md} | 20 +- .../commands/fs/ti-fs-list-layers.md} | 18 +- .../commands/fs/ti-fs-mount-file-system.md} | 30 +-- .../reference/commands/fs/ti-fs-move-file.md} | 20 +- .../commands/fs/ti-fs-pack-file-system.md} | 20 +- .../reference/commands/fs/ti-fs-read-file.md} | 22 +- .../commands/fs/ti-fs-rollback-layer.md} | 18 +- .../commands/fs/ti-fs-search-file-content.md} | 22 +- .../commands/fs/ti-fs-unmount-file-system.md} | 16 +- .../commands/fs/ti-fs-unpack-file-system.md} | 20 +- .../ti-organization-list-projects.md} | 16 +- ai/ti/reference/commands/ti/ti-configure.md | 58 +++++ .../reference/commands/ti/ti-update.md} | 24 +- .../reference/ti-agent-sandbox-example.md} | 38 +-- .../ti-ci-artifact-handoff-example.md} | 24 +- .../reference/ti-cli-reference.md} | 78 +++--- .../ti-configuration-and-credentials.md} | 90 +++---- .../reference/ti-daily-workflow-example.md} | 40 +-- .../reference/ti-filesystem-git.md} | 32 +-- .../reference/ti-filesystem-journal.md} | 38 +-- .../reference/ti-filesystem-vault.md} | 66 ++--- .../reference/ti-filesystem.md} | 246 +++++++++--------- .../ti-git-workspace-for-agents-example.md} | 24 +- .../reference/ti-install-configure-update.md | 190 ++++++++++++++ .../ti-journal-agent-workflow-example.md} | 20 +- ai/ti/reference/ti-organization.md | 74 ++++++ .../ti-parallel-agent-dataset-example.md} | 20 +- .../ti-persistent-agent-state-example.md} | 28 +- .../ti-query-sql-with-roles-example.md} | 26 +- .../ti-regions-security-and-limitations.md} | 24 +- ...are-filesystem-across-machines-example.md} | 36 +-- .../reference/ti-starter-database.md} | 90 +++---- .../reference/ti-troubleshooting.md} | 72 ++--- .../ti-vault-agent-secrets-example.md} | 22 +- ai/ti/ti-overview.md | 102 ++++++++ .../ti-quick-start.md} | 62 ++--- tidb-cloud/cli-reference.md | 2 +- tidb-cloud/get-started-with-cli.md | 2 +- 97 files changed, 1765 insertions(+), 1753 deletions(-) delete mode 100644 ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md delete mode 100644 ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md delete mode 100644 ai/tdc/reference/commands/tdc/tdc-configure.md delete mode 100644 ai/tdc/reference/tdc-install-configure-update.md delete mode 100644 ai/tdc/reference/tdc-organization.md delete mode 100644 ai/tdc/tdc-overview.md rename ai/{tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md => ti/reference/commands/db/ti-db-create-db-cluster-branch.md} (61%) rename ai/{tdc/reference/commands/db/tdc-db-create-db-cluster.md => ti/reference/commands/db/ti-db-create-db-cluster.md} (68%) rename ai/{tdc/reference/commands/db/tdc-db-create-db-sql-users.md => ti/reference/commands/db/ti-db-create-db-sql-users.md} (51%) rename ai/{tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md => ti/reference/commands/db/ti-db-delete-db-cluster-branch.md} (58%) rename ai/{tdc/reference/commands/db/tdc-db-delete-db-cluster.md => ti/reference/commands/db/ti-db-delete-db-cluster.md} (64%) rename ai/{tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md => ti/reference/commands/db/ti-db-describe-db-cluster-branch.md} (57%) rename ai/{tdc/reference/commands/db/tdc-db-describe-db-cluster.md => ti/reference/commands/db/ti-db-describe-db-cluster.md} (57%) rename ai/{tdc/reference/commands/db/tdc-db-execute-sql-statement.md => ti/reference/commands/db/ti-db-execute-sql-statement.md} (63%) rename ai/{tdc/reference/commands/db/tdc-db-format-db-connection-string.md => ti/reference/commands/db/ti-db-format-db-connection-string.md} (67%) rename ai/{tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md => ti/reference/commands/db/ti-db-list-db-cluster-branches.md} (61%) rename ai/{tdc/reference/commands/db/tdc-db-list-db-clusters.md => ti/reference/commands/db/ti-db-list-db-clusters.md} (50%) rename ai/{tdc/reference/commands/db/tdc-db-update-db-cluster.md => ti/reference/commands/db/ti-db-update-db-cluster.md} (63%) rename ai/{tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md => ti/reference/commands/fs-git/ti-fs-git-add-git-worktree.md} (64%) rename ai/{tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md => ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.md} (58%) create mode 100644 ai/ti/reference/commands/fs-git/ti-fs-git-hydrate-git-workspace.md rename ai/{tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md => ti/reference/commands/fs-git/ti-fs-git-remove-git-worktree.md} (53%) rename ai/{tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md => ti/reference/commands/fs-journal/ti-fs-journal-append-journal-entries.md} (62%) rename ai/{tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md => ti/reference/commands/fs-journal/ti-fs-journal-create-journal.md} (60%) rename ai/{tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md => ti/reference/commands/fs-journal/ti-fs-journal-read-journal-entries.md} (56%) rename ai/{tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md => ti/reference/commands/fs-journal/ti-fs-journal-search-journal-entries.md} (64%) rename ai/{tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md => ti/reference/commands/fs-journal/ti-fs-journal-verify-journal.md} (52%) rename ai/{tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md => ti/reference/commands/fs-vault/ti-fs-vault-create-grant.md} (63%) rename ai/{tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md => ti/reference/commands/fs-vault/ti-fs-vault-create-secret.md} (56%) rename ai/{tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md => ti/reference/commands/fs-vault/ti-fs-vault-delete-grant.md} (58%) rename ai/{tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md => ti/reference/commands/fs-vault/ti-fs-vault-delete-secret.md} (55%) rename ai/{tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md => ti/reference/commands/fs-vault/ti-fs-vault-list-audit-events.md} (60%) rename ai/{tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md => ti/reference/commands/fs-vault/ti-fs-vault-list-secrets.md} (51%) rename ai/{tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md => ti/reference/commands/fs-vault/ti-fs-vault-mount-vault.md} (58%) rename ai/{tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md => ti/reference/commands/fs-vault/ti-fs-vault-read-secret.md} (56%) rename ai/{tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md => ti/reference/commands/fs-vault/ti-fs-vault-replace-secret.md} (57%) rename ai/{tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md => ti/reference/commands/fs-vault/ti-fs-vault-run-with-secret.md} (54%) rename ai/{tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md => ti/reference/commands/fs-vault/ti-fs-vault-unmount-vault.md} (56%) rename ai/{tdc/reference/commands/fs/tdc-fs-check-file-system.md => ti/reference/commands/fs/ti-fs-check-file-system.md} (54%) rename ai/{tdc/reference/commands/fs/tdc-fs-chmod-file.md => ti/reference/commands/fs/ti-fs-chmod-file.md} (60%) rename ai/{tdc/reference/commands/fs/tdc-fs-commit-layer.md => ti/reference/commands/fs/ti-fs-commit-layer.md} (56%) rename ai/{tdc/reference/commands/fs/tdc-fs-copy-file.md => ti/reference/commands/fs/ti-fs-copy-file.md} (67%) rename ai/{tdc/reference/commands/fs/tdc-fs-create-directory.md => ti/reference/commands/fs/ti-fs-create-directory.md} (56%) rename ai/{tdc/reference/commands/fs/tdc-fs-create-file-system.md => ti/reference/commands/fs/ti-fs-create-file-system.md} (61%) rename ai/{tdc/reference/commands/fs/tdc-fs-create-hardlink.md => ti/reference/commands/fs/ti-fs-create-hardlink.md} (59%) rename ai/{tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md => ti/reference/commands/fs/ti-fs-create-layer-checkpoint.md} (61%) rename ai/{tdc/reference/commands/fs/tdc-fs-create-layer.md => ti/reference/commands/fs/ti-fs-create-layer.md} (67%) rename ai/{tdc/reference/commands/fs/tdc-fs-create-symlink.md => ti/reference/commands/fs/ti-fs-create-symlink.md} (56%) rename ai/{tdc/reference/commands/fs/tdc-fs-delete-file-system.md => ti/reference/commands/fs/ti-fs-delete-file-system.md} (59%) rename ai/{tdc/reference/commands/fs/tdc-fs-delete-file.md => ti/reference/commands/fs/ti-fs-delete-file.md} (56%) rename ai/{tdc/reference/commands/fs/tdc-fs-describe-file-system.md => ti/reference/commands/fs/ti-fs-describe-file-system.md} (51%) rename ai/{tdc/reference/commands/fs/tdc-fs-describe-file.md => ti/reference/commands/fs/ti-fs-describe-file.md} (50%) rename ai/{tdc/reference/commands/fs/tdc-fs-describe-layer.md => ti/reference/commands/fs/ti-fs-describe-layer.md} (54%) rename ai/{tdc/reference/commands/fs/tdc-fs-diff-layer.md => ti/reference/commands/fs/ti-fs-diff-layer.md} (59%) rename ai/{tdc/reference/commands/fs/tdc-fs-drain-file-system.md => ti/reference/commands/fs/ti-fs-drain-file-system.md} (57%) rename ai/{tdc/reference/commands/fs/tdc-fs-find-files.md => ti/reference/commands/fs/ti-fs-find-files.md} (69%) create mode 100644 ai/ti/reference/commands/fs/ti-fs-list-file-systems.md rename ai/{tdc/reference/commands/fs/tdc-fs-list-files.md => ti/reference/commands/fs/ti-fs-list-files.md} (50%) rename ai/{tdc/reference/commands/fs/tdc-fs-list-layers.md => ti/reference/commands/fs/ti-fs-list-layers.md} (52%) rename ai/{tdc/reference/commands/fs/tdc-fs-mount-file-system.md => ti/reference/commands/fs/ti-fs-mount-file-system.md} (72%) rename ai/{tdc/reference/commands/fs/tdc-fs-move-file.md => ti/reference/commands/fs/ti-fs-move-file.md} (57%) rename ai/{tdc/reference/commands/fs/tdc-fs-pack-file-system.md => ti/reference/commands/fs/ti-fs-pack-file-system.md} (66%) rename ai/{tdc/reference/commands/fs/tdc-fs-read-file.md => ti/reference/commands/fs/ti-fs-read-file.md} (59%) rename ai/{tdc/reference/commands/fs/tdc-fs-rollback-layer.md => ti/reference/commands/fs/ti-fs-rollback-layer.md} (57%) rename ai/{tdc/reference/commands/fs/tdc-fs-search-file-content.md => ti/reference/commands/fs/ti-fs-search-file-content.md} (60%) rename ai/{tdc/reference/commands/fs/tdc-fs-unmount-file-system.md => ti/reference/commands/fs/ti-fs-unmount-file-system.md} (67%) rename ai/{tdc/reference/commands/fs/tdc-fs-unpack-file-system.md => ti/reference/commands/fs/ti-fs-unpack-file-system.md} (66%) rename ai/{tdc/reference/commands/organization/tdc-organization-list-projects.md => ti/reference/commands/organization/ti-organization-list-projects.md} (57%) create mode 100644 ai/ti/reference/commands/ti/ti-configure.md rename ai/{tdc/reference/commands/tdc/tdc-update.md => ti/reference/commands/ti/ti-update.md} (58%) rename ai/{tdc/reference/tdc-agent-sandbox-example.md => ti/reference/ti-agent-sandbox-example.md} (65%) rename ai/{tdc/reference/tdc-ci-artifact-handoff-example.md => ti/reference/ti-ci-artifact-handoff-example.md} (72%) rename ai/{tdc/reference/tdc-cli-reference.md => ti/reference/ti-cli-reference.md} (72%) rename ai/{tdc/reference/tdc-configuration-and-credentials.md => ti/reference/ti-configuration-and-credentials.md} (54%) rename ai/{tdc/reference/tdc-daily-workflow-example.md => ti/reference/ti-daily-workflow-example.md} (69%) rename ai/{tdc/reference/tdc-filesystem-git.md => ti/reference/ti-filesystem-git.md} (70%) rename ai/{tdc/reference/tdc-filesystem-journal.md => ti/reference/ti-filesystem-journal.md} (53%) rename ai/{tdc/reference/tdc-filesystem-vault.md => ti/reference/ti-filesystem-vault.md} (57%) rename ai/{tdc/reference/tdc-filesystem.md => ti/reference/ti-filesystem.md} (59%) rename ai/{tdc/reference/tdc-git-workspace-for-agents-example.md => ti/reference/ti-git-workspace-for-agents-example.md} (70%) create mode 100644 ai/ti/reference/ti-install-configure-update.md rename ai/{tdc/reference/tdc-journal-agent-workflow-example.md => ti/reference/ti-journal-agent-workflow-example.md} (79%) create mode 100644 ai/ti/reference/ti-organization.md rename ai/{tdc/reference/tdc-parallel-agent-dataset-example.md => ti/reference/ti-parallel-agent-dataset-example.md} (75%) rename ai/{tdc/reference/tdc-persistent-agent-state-example.md => ti/reference/ti-persistent-agent-state-example.md} (70%) rename ai/{tdc/reference/tdc-query-sql-with-roles-example.md => ti/reference/ti-query-sql-with-roles-example.md} (73%) rename ai/{tdc/reference/tdc-regions-security-and-limitations.md => ti/reference/ti-regions-security-and-limitations.md} (81%) rename ai/{tdc/reference/tdc-share-filesystem-across-machines-example.md => ti/reference/ti-share-filesystem-across-machines-example.md} (74%) rename ai/{tdc/reference/tdc-starter-database.md => ti/reference/ti-starter-database.md} (57%) rename ai/{tdc/reference/tdc-troubleshooting.md => ti/reference/ti-troubleshooting.md} (69%) rename ai/{tdc/reference/tdc-vault-agent-secrets-example.md => ti/reference/ti-vault-agent-secrets-example.md} (82%) create mode 100644 ai/ti/ti-overview.md rename ai/{tdc/tdc-quick-start.md => ti/ti-quick-start.md} (59%) diff --git a/TOC-ai.md b/TOC-ai.md index 63e9da95ced26..aeaba35e5e5a1 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -7,7 +7,7 @@ - [Get Started with Vector Search via Python](/ai/quickstart-via-python.md) - [Get Started with Vector Search via SQL](/ai/quickstart-via-sql.md) -- [Get Started with TiDB Cloud CLI](/ai/tdc/tdc-quick-start.md) +- [Get Started with TiDB Cloud CLI](/ai/ti/ti-quick-start.md) ## CONCEPTS @@ -84,99 +84,99 @@ - [Vector Search Performance Tuning](/ai/reference/vector-search-improve-performance.md) - [Vector Search Limitations](/ai/reference/vector-search-limitations.md) - TiDB Cloud CLI - - [TiDB Cloud Command Line Interface Overview](/ai/tdc/tdc-overview.md) + - [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) - Guides - - [Install, Configure, and Update TiDB Cloud CLI](/ai/tdc/reference/tdc-install-configure-update.md) - - [TiDB Cloud Organization CLI Command Reference](/ai/tdc/reference/tdc-organization.md) - - [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) - - [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) - - [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) - - [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) - - [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) + - [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) + - [TiDB Cloud Organization CLI Command Reference](/ai/ti/reference/ti-organization.md) + - [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) + - [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) + - [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) + - [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) + - [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) - Command Reference - - [TiDB Cloud CLI Command Reference](/ai/tdc/reference/tdc-cli-reference.md) - - [configure](/ai/tdc/reference/commands/tdc/tdc-configure.md) - - [update](/ai/tdc/reference/commands/tdc/tdc-update.md) + - [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) + - [configure](/ai/ti/reference/commands/ti/ti-configure.md) + - [update](/ai/ti/reference/commands/ti/ti-update.md) - organization - - [list-projects](/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md) + - [list-projects](/ai/ti/reference/commands/organization/ti-organization-list-projects.md) - db - - [create-db-cluster](/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md) - - [list-db-clusters](/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md) - - [describe-db-cluster](/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md) - - [update-db-cluster](/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md) - - [delete-db-cluster](/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md) - - [create-db-cluster-branch](/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md) - - [list-db-cluster-branches](/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md) - - [describe-db-cluster-branch](/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md) - - [delete-db-cluster-branch](/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md) - - [create-db-sql-users](/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md) - - [format-db-connection-string](/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md) - - [execute-sql-statement](/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md) + - [create-db-cluster](/ai/ti/reference/commands/db/ti-db-create-db-cluster.md) + - [list-db-clusters](/ai/ti/reference/commands/db/ti-db-list-db-clusters.md) + - [describe-db-cluster](/ai/ti/reference/commands/db/ti-db-describe-db-cluster.md) + - [update-db-cluster](/ai/ti/reference/commands/db/ti-db-update-db-cluster.md) + - [delete-db-cluster](/ai/ti/reference/commands/db/ti-db-delete-db-cluster.md) + - [create-db-cluster-branch](/ai/ti/reference/commands/db/ti-db-create-db-cluster-branch.md) + - [list-db-cluster-branches](/ai/ti/reference/commands/db/ti-db-list-db-cluster-branches.md) + - [describe-db-cluster-branch](/ai/ti/reference/commands/db/ti-db-describe-db-cluster-branch.md) + - [delete-db-cluster-branch](/ai/ti/reference/commands/db/ti-db-delete-db-cluster-branch.md) + - [create-db-sql-users](/ai/ti/reference/commands/db/ti-db-create-db-sql-users.md) + - [format-db-connection-string](/ai/ti/reference/commands/db/ti-db-format-db-connection-string.md) + - [execute-sql-statement](/ai/ti/reference/commands/db/ti-db-execute-sql-statement.md) - fs - - [create-file-system](/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md) - - [list-file-systems](/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md) - - [describe-file-system](/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md) - - [check-file-system](/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md) - - [delete-file-system](/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md) - - [copy-file](/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md) - - [read-file](/ai/tdc/reference/commands/fs/tdc-fs-read-file.md) - - [list-files](/ai/tdc/reference/commands/fs/tdc-fs-list-files.md) - - [describe-file](/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md) - - [move-file](/ai/tdc/reference/commands/fs/tdc-fs-move-file.md) - - [delete-file](/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md) - - [create-directory](/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md) - - [chmod-file](/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md) - - [create-symlink](/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md) - - [create-hardlink](/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md) - - [search-file-content](/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md) - - [find-files](/ai/tdc/reference/commands/fs/tdc-fs-find-files.md) - - [create-layer](/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md) - - [list-layers](/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md) - - [describe-layer](/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md) - - [diff-layer](/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md) - - [create-layer-checkpoint](/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md) - - [rollback-layer](/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md) - - [commit-layer](/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md) - - [pack-file-system](/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md) - - [unpack-file-system](/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md) - - [mount-file-system](/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md) - - [drain-file-system](/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md) - - [unmount-file-system](/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md) + - [create-file-system](/ai/ti/reference/commands/fs/ti-fs-create-file-system.md) + - [list-file-systems](/ai/ti/reference/commands/fs/ti-fs-list-file-systems.md) + - [describe-file-system](/ai/ti/reference/commands/fs/ti-fs-describe-file-system.md) + - [check-file-system](/ai/ti/reference/commands/fs/ti-fs-check-file-system.md) + - [delete-file-system](/ai/ti/reference/commands/fs/ti-fs-delete-file-system.md) + - [copy-file](/ai/ti/reference/commands/fs/ti-fs-copy-file.md) + - [read-file](/ai/ti/reference/commands/fs/ti-fs-read-file.md) + - [list-files](/ai/ti/reference/commands/fs/ti-fs-list-files.md) + - [describe-file](/ai/ti/reference/commands/fs/ti-fs-describe-file.md) + - [move-file](/ai/ti/reference/commands/fs/ti-fs-move-file.md) + - [delete-file](/ai/ti/reference/commands/fs/ti-fs-delete-file.md) + - [create-directory](/ai/ti/reference/commands/fs/ti-fs-create-directory.md) + - [chmod-file](/ai/ti/reference/commands/fs/ti-fs-chmod-file.md) + - [create-symlink](/ai/ti/reference/commands/fs/ti-fs-create-symlink.md) + - [create-hardlink](/ai/ti/reference/commands/fs/ti-fs-create-hardlink.md) + - [search-file-content](/ai/ti/reference/commands/fs/ti-fs-search-file-content.md) + - [find-files](/ai/ti/reference/commands/fs/ti-fs-find-files.md) + - [create-layer](/ai/ti/reference/commands/fs/ti-fs-create-layer.md) + - [list-layers](/ai/ti/reference/commands/fs/ti-fs-list-layers.md) + - [describe-layer](/ai/ti/reference/commands/fs/ti-fs-describe-layer.md) + - [diff-layer](/ai/ti/reference/commands/fs/ti-fs-diff-layer.md) + - [create-layer-checkpoint](/ai/ti/reference/commands/fs/ti-fs-create-layer-checkpoint.md) + - [rollback-layer](/ai/ti/reference/commands/fs/ti-fs-rollback-layer.md) + - [commit-layer](/ai/ti/reference/commands/fs/ti-fs-commit-layer.md) + - [pack-file-system](/ai/ti/reference/commands/fs/ti-fs-pack-file-system.md) + - [unpack-file-system](/ai/ti/reference/commands/fs/ti-fs-unpack-file-system.md) + - [mount-file-system](/ai/ti/reference/commands/fs/ti-fs-mount-file-system.md) + - [drain-file-system](/ai/ti/reference/commands/fs/ti-fs-drain-file-system.md) + - [unmount-file-system](/ai/ti/reference/commands/fs/ti-fs-unmount-file-system.md) - fs-git - - [clone-git-workspace](/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md) - - [hydrate-git-workspace](/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md) - - [add-git-worktree](/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md) - - [remove-git-worktree](/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md) + - [clone-git-workspace](/ai/ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.md) + - [hydrate-git-workspace](/ai/ti/reference/commands/fs-git/ti-fs-git-hydrate-git-workspace.md) + - [add-git-worktree](/ai/ti/reference/commands/fs-git/ti-fs-git-add-git-worktree.md) + - [remove-git-worktree](/ai/ti/reference/commands/fs-git/ti-fs-git-remove-git-worktree.md) - fs-journal - - [create-journal](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md) - - [append-journal-entries](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md) - - [read-journal-entries](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md) - - [search-journal-entries](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md) - - [verify-journal](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md) + - [create-journal](/ai/ti/reference/commands/fs-journal/ti-fs-journal-create-journal.md) + - [append-journal-entries](/ai/ti/reference/commands/fs-journal/ti-fs-journal-append-journal-entries.md) + - [read-journal-entries](/ai/ti/reference/commands/fs-journal/ti-fs-journal-read-journal-entries.md) + - [search-journal-entries](/ai/ti/reference/commands/fs-journal/ti-fs-journal-search-journal-entries.md) + - [verify-journal](/ai/ti/reference/commands/fs-journal/ti-fs-journal-verify-journal.md) - fs-vault - - [create-secret](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md) - - [replace-secret](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md) - - [read-secret](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md) - - [list-secrets](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md) - - [delete-secret](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md) - - [create-grant](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md) - - [delete-grant](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md) - - [list-audit-events](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md) - - [run-with-secret](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md) - - [mount-vault](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md) - - [unmount-vault](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md) + - [create-secret](/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-secret.md) + - [replace-secret](/ai/ti/reference/commands/fs-vault/ti-fs-vault-replace-secret.md) + - [read-secret](/ai/ti/reference/commands/fs-vault/ti-fs-vault-read-secret.md) + - [list-secrets](/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-secrets.md) + - [delete-secret](/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-secret.md) + - [create-grant](/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-grant.md) + - [delete-grant](/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-grant.md) + - [list-audit-events](/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-audit-events.md) + - [run-with-secret](/ai/ti/reference/commands/fs-vault/ti-fs-vault-run-with-secret.md) + - [mount-vault](/ai/ti/reference/commands/fs-vault/ti-fs-vault-mount-vault.md) + - [unmount-vault](/ai/ti/reference/commands/fs-vault/ti-fs-vault-unmount-vault.md) - Scenarios for Users and Automation - - [Run a Daily TiDB Cloud CLI Workflow](/ai/tdc/reference/tdc-daily-workflow-example.md) - - [Query TiDB Cloud Starter with Explicit SQL Roles](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) - - [Share a TiDB Cloud Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) - - [Hand Off CI Artifacts Between Isolated Jobs with TiDB Cloud Filesystem](/ai/tdc/reference/tdc-ci-artifact-handoff-example.md) + - [Run a Daily TiDB Cloud CLI Workflow](/ai/ti/reference/ti-daily-workflow-example.md) + - [Query TiDB Cloud Starter with Explicit SQL Roles](/ai/ti/reference/ti-query-sql-with-roles-example.md) + - [Share a TiDB Cloud Filesystem Across Machines](/ai/ti/reference/ti-share-filesystem-across-machines-example.md) + - [Hand Off CI Artifacts Between Isolated Jobs with TiDB Cloud Filesystem](/ai/ti/reference/ti-ci-artifact-handoff-example.md) - Scenarios for AI Agents - - [Use TiDB Cloud Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) - - [Persist Agent State Across Disposable Sandboxes with TiDB Cloud Filesystem](/ai/tdc/reference/tdc-persistent-agent-state-example.md) - - [Share a Read-Only Dataset Across Parallel Agents with TiDB Cloud Filesystem](/ai/tdc/reference/tdc-parallel-agent-dataset-example.md) - - [Prepare a Git Workspace for Agents on TiDB Cloud Filesystem](/ai/tdc/reference/tdc-git-workspace-for-agents-example.md) - - [Record an Agent Workflow in a TiDB Cloud Filesystem Journal](/ai/tdc/reference/tdc-journal-agent-workflow-example.md) - - [Delegate TiDB Cloud Filesystem Vault Secrets to an Agent](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) - - [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) - - [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) - - [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) + - [Use TiDB Cloud Filesystem in an Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) + - [Persist Agent State Across Disposable Sandboxes with TiDB Cloud Filesystem](/ai/ti/reference/ti-persistent-agent-state-example.md) + - [Share a Read-Only Dataset Across Parallel Agents with TiDB Cloud Filesystem](/ai/ti/reference/ti-parallel-agent-dataset-example.md) + - [Prepare a Git Workspace for Agents on TiDB Cloud Filesystem](/ai/ti/reference/ti-git-workspace-for-agents-example.md) + - [Record an Agent Workflow in a TiDB Cloud Filesystem Journal](/ai/ti/reference/ti-journal-agent-workflow-example.md) + - [Delegate TiDB Cloud Filesystem Vault Secrets to an Agent](/ai/ti/reference/ti-vault-agent-secrets-example.md) + - [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) + - [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) + - [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) diff --git a/ai/_index.md b/ai/_index.md index c6dc0396e1dc2..5c9e4c0d061a7 100644 --- a/ai/_index.md +++ b/ai/_index.md @@ -20,8 +20,8 @@ Get up and running quickly with TiDB's AI capabilities. | Document | Description | | --- | --- | -| [TiDB Cloud Command Line Interface Overview](/ai/tdc/tdc-overview.md) | Learn when to use the TiDB Cloud CLI, how it differs from the `ticloud` CLI and TiDB Cloud console, and which Starter and Filesystem workflows it supports. | -| [Get Started with TiDB Cloud CLI](/ai/tdc/tdc-quick-start.md) | Install and configure the TiDB Cloud CLI, then complete a first database or Filesystem operation. | +| [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) | Learn when to use the TiDB Cloud CLI, how it differs from the `ticloud` CLI and TiDB Cloud console, and which Starter and Filesystem workflows it supports. | +| [Get Started with TiDB Cloud CLI](/ai/ti/ti-quick-start.md) | Install and configure the TiDB Cloud CLI, then complete a first database or Filesystem operation. | ## Concepts @@ -84,42 +84,42 @@ Technical reference documentation for TiDB's AI and vector search features. ### TiDB Cloud CLI (Preview) -The command reference follows the two-level `tdc` command tree. Every command has a dedicated page with its syntax and examples. Expand **Command Reference** in the documentation navigation to browse commands by family. +The command reference follows the two-level `ti` command tree. Every command has a dedicated page with its syntax and examples. Expand **Command Reference** in the documentation navigation to browse commands by family. #### Command reference | Document | Description | | --- | --- | -| [TiDB Cloud Command Line Interface Overview](/ai/tdc/tdc-overview.md) | Decide when to use the TiDB Cloud CLI and understand its scope relative to `ticloud` and the TiDB Cloud console. | -| [TiDB Cloud CLI Command Reference](/ai/tdc/reference/tdc-cli-reference.md) | Command tree, global flags, output, queries, dry-run, help, errors, aliases, and links to command pages. | -| [`tdc configure`](/ai/tdc/reference/commands/tdc/tdc-configure.md) | Configure a local profile interactively or non-interactively. | -| [`tdc update`](/ai/tdc/reference/commands/tdc/tdc-update.md) | Check for and install release updates. | -| [`tdc organization list-projects`](/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md) | List accessible TiDB Cloud projects. | -| [`tdc db create-db-cluster`](/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md) | Start with the database command reference. | -| [`tdc fs create-file-system`](/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md) | Start with the Filesystem command reference. | -| [`tdc fs-git clone-git-workspace`](/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md) | Start with the Filesystem Git command reference. | -| [`tdc fs-journal create-journal`](/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md) | Start with the Filesystem journal command reference. | -| [`tdc fs-vault create-secret`](/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md) | Start with the Filesystem Vault command reference. | -| [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) | Profiles, precedence, local state, credentials, mount locators, and logs. | -| [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) | Placement, authentication boundaries, platforms, durability, and preview constraints. | -| [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) | Diagnose authentication, quota, SQL, companion, selection, and mount failures. | +| [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) | Decide when to use the TiDB Cloud CLI and understand its scope relative to `ticloud` and the TiDB Cloud console. | +| [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) | Command tree, global flags, output, queries, dry-run, help, errors, aliases, and links to command pages. | +| [`ti configure`](/ai/ti/reference/commands/ti/ti-configure.md) | Configure a local profile interactively or non-interactively. | +| [`ti update`](/ai/ti/reference/commands/ti/ti-update.md) | Check for and install release updates. | +| [`ti organization list-projects`](/ai/ti/reference/commands/organization/ti-organization-list-projects.md) | List accessible TiDB Cloud projects. | +| [`ti db create-db-cluster`](/ai/ti/reference/commands/db/ti-db-create-db-cluster.md) | Start with the database command reference. | +| [`ti fs create-file-system`](/ai/ti/reference/commands/fs/ti-fs-create-file-system.md) | Start with the Filesystem command reference. | +| [`ti fs-git clone-git-workspace`](/ai/ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.md) | Start with the Filesystem Git command reference. | +| [`ti fs-journal create-journal`](/ai/ti/reference/commands/fs-journal/ti-fs-journal-create-journal.md) | Start with the Filesystem journal command reference. | +| [`ti fs-vault create-secret`](/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-secret.md) | Start with the Filesystem Vault command reference. | +| [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) | Profiles, precedence, local state, credentials, mount locators, and logs. | +| [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) | Placement, authentication boundaries, platforms, durability, and preview constraints. | +| [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) | Diagnose authentication, quota, SQL, companion, selection, and mount failures. | #### Scenarios for users and automation | Document | Description | | --- | --- | -| [Daily Workflow](/ai/tdc/reference/tdc-daily-workflow-example.md) | Manage one Starter cluster and Filesystem in a routine operator flow. | -| [Query SQL with Roles](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) | Use explicit read-only, read-write, and admin SQL roles. | -| [Share a Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) | Transfer an owner token securely and verify cross-machine visibility. | -| [Hand Off CI Artifacts Between Jobs](/ai/tdc/reference/tdc-ci-artifact-handoff-example.md) | Persist build output across isolated jobs without copying a complete TiDB Cloud CLI profile. | +| [Daily Workflow](/ai/ti/reference/ti-daily-workflow-example.md) | Manage one Starter cluster and Filesystem in a routine operator flow. | +| [Query SQL with Roles](/ai/ti/reference/ti-query-sql-with-roles-example.md) | Use explicit read-only, read-write, and admin SQL roles. | +| [Share a Filesystem Across Machines](/ai/ti/reference/ti-share-filesystem-across-machines-example.md) | Transfer an owner token securely and verify cross-machine visibility. | +| [Hand Off CI Artifacts Between Jobs](/ai/ti/reference/ti-ci-artifact-handoff-example.md) | Persist build output across isolated jobs without copying a complete TiDB Cloud CLI profile. | #### Scenarios for AI agents | Document | Description | | --- | --- | -| [Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) | Give a clean sandbox Filesystem access without TiDB Cloud API keys. | -| [Persistent Agent State](/ai/tdc/reference/tdc-persistent-agent-state-example.md) | Preserve plans, checkpoints, and results across disposable sandboxes. | -| [Parallel Agent Dataset](/ai/tdc/reference/tdc-parallel-agent-dataset-example.md) | Give multiple agents read-only access to one shared unstructured dataset. | -| [Git Workspace for Agents](/ai/tdc/reference/tdc-git-workspace-for-agents-example.md) | Prepare a mounted Git workspace and isolated linked worktree. | -| [Journal an Agent Workflow](/ai/tdc/reference/tdc-journal-agent-workflow-example.md) | Record structured events and verify their hash chain. | -| [Delegate Vault Secrets](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) | Grant an agent temporary access to one secret field. | +| [Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) | Give a clean sandbox Filesystem access without TiDB Cloud API keys. | +| [Persistent Agent State](/ai/ti/reference/ti-persistent-agent-state-example.md) | Preserve plans, checkpoints, and results across disposable sandboxes. | +| [Parallel Agent Dataset](/ai/ti/reference/ti-parallel-agent-dataset-example.md) | Give multiple agents read-only access to one shared unstructured dataset. | +| [Git Workspace for Agents](/ai/ti/reference/ti-git-workspace-for-agents-example.md) | Prepare a mounted Git workspace and isolated linked worktree. | +| [Journal an Agent Workflow](/ai/ti/reference/ti-journal-agent-workflow-example.md) | Record structured events and verify their hash chain. | +| [Delegate Vault Secrets](/ai/ti/reference/ti-vault-agent-secrets-example.md) | Grant an agent temporary access to one secret field. | diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md b/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md deleted file mode 100644 index 53299166bcb11..0000000000000 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-hydrate-git-workspace.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: tdc fs-git hydrate-git-workspace -summary: Hydrate clean Git objects in a Filesystem Git workspace. ---- - -# tdc fs-git hydrate-git-workspace - -Hydrates clean Git objects for an existing `tdc` Git workspace. - -> **Note:** -> -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. - -## Syntax - -```text -tdc fs-git hydrate-git-workspace - --target-path - [--file-system-name ] - [--fs-token ] - [--help] - [--timeout ] - [--version] -``` - -## Options - -- `--target-path `: Mounted `tdc fs` workspace path. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. -- `--help`: Display help information. -- `--timeout `: Maximum hydrate duration. \[default: `30m0s`] -- `--version`: Display version information. - -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). - -## Examples - -- Finish hydrating a Git workspace: - - ```bash - # Download missing clean Git objects for an existing blobless workspace. - tdc fs-git hydrate-git-workspace --file-system-name workspace --target-path /path/to/workspace/tidb --timeout 30m - ``` - -## Related documentation - -- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md b/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md deleted file mode 100644 index 8932daaa6e1ab..0000000000000 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-file-systems.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: tdc fs list-file-systems -summary: List locally registered TiDB Cloud Filesystems. ---- - -# tdc fs list-file-systems - -Lists Filesystems registered in the selected local profile. - -> **Note:** -> -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. - -## Syntax - -```text -tdc fs list-file-systems - [--help] - [--version] -``` - -## Options - -- `--help`: Display help information. -- `--version`: Display version information. - -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). - -## Examples - -- List locally registered Filesystems: - - ```bash - # Return the Filesystems registered under the selected local profile. - tdc fs list-file-systems - ``` - -## Related documentation - -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/commands/tdc/tdc-configure.md b/ai/tdc/reference/commands/tdc/tdc-configure.md deleted file mode 100644 index d81134f33f52a..0000000000000 --- a/ai/tdc/reference/commands/tdc/tdc-configure.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: tdc configure -summary: Configure a local TiDB Cloud CLI profile interactively or non-interactively. ---- - -# tdc configure - -Configures a local TiDB Cloud CLI profile. Without flags, this is the only interactive TiDB Cloud CLI command. - -> **Note:** -> -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. - -## Syntax - -```text -tdc configure - [--help] - [--non-interactive] - [--region-code ] - [--tdc-private-key ] - [--tdc-public-key ] - [--version] -``` - -## Options - -- `--help`: Display help information. -- `--non-interactive`: Use this option to avoid being prompted for configuration values. You must provide at least three configuration values (`--tdc-public-key`, `--tdc-private-key`, and `--region-code`) when using this option. This is useful when running `tdc` in a script or automated environment. -- `--region-code `: Default region code, for example `aws-us-east-1` or `aws-ap-southeast-1`. -- `--tdc-private-key `: TiDB Cloud API private key. -- `--tdc-public-key `: TiDB Cloud API public key. -- `--version`: Display version information. - -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). - -## Examples - -- Configure `tdc` interactively: - - ```bash - # Enter the default region code and TiDB Cloud API keys when prompted. - tdc configure - ``` - -- Configure `tdc` for automation: - - ```bash - # Supply all required values without interactive prompts. - TDC_REGION_CODE="aws-us-east-1" \ - TDC_PUBLIC_KEY="" \ - TDC_PRIVATE_KEY="" \ - tdc configure --profile ci --non-interactive - ``` - -## Related documentation - -- [Install, Configure, and Update TiDB Cloud CLI](/ai/tdc/reference/tdc-install-configure-update.md) diff --git a/ai/tdc/reference/tdc-install-configure-update.md b/ai/tdc/reference/tdc-install-configure-update.md deleted file mode 100644 index b7f6e43605666..0000000000000 --- a/ai/tdc/reference/tdc-install-configure-update.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: Install, Configure, and Update TiDB Cloud CLI -summary: Install TiDB Cloud CLI releases, configure profiles, check versions, apply updates, and uninstall the CLI. ---- - -# Install, Configure, and Update TiDB Cloud CLI - -This reference documents the supported release installers, top-level configuration and update commands, help and version behavior, and uninstallation. - -> **Note:** -> -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. - -## Command tree - -```text -tdc -├── configure -└── update -``` - -| Command | Required inputs | Main optional inputs | Example | -| --- | --- | --- | --- | -| `tdc configure` | Interactive input, or region and TiDB Cloud API keys in non-interactive mode | `--profile`, `--non-interactive`, `--region-code`, key flags | `tdc configure --profile staging` | -| `tdc update` | None | `--check`, `--fail-if-update-available`, `--dry-run`, `--target-version` | `tdc update --check` | - -Run `tdc configure help` or `tdc update help` for the complete generated flag list. - -## Install TiDB Cloud CLI - -### macOS and Linux - -Run the installer: - -```bash -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: - -```bash -export PATH="$HOME/.tdc/bin:$PATH" -tdc --version -``` - -The installer places `tdc` and its `tdc-drive9` companion in `~/.tdc/bin`. Add the `PATH` export to your shell profile. The installer does not require `sudo` and does not write credentials. - -After installation, the installer displays the anonymous telemetry fields, prohibited data, persistent opt-out path, and process-scoped `TDC_TELEMETRY=off` override. It does not prompt for a telemetry choice or create the optional preferences file. - -### Windows - -Run the installer: - -```powershell -$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: - -```powershell -$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. - -The Windows installer displays the same anonymous telemetry and opt-out notice without creating a preference or installation identity. - -## Configure a profile - -Interactive configuration is the only TiDB Cloud CLI workflow that prompts: - -```bash -tdc configure -``` - -The TiDB Cloud CLI requests a TiDB Cloud API public key, private key, and canonical region code. It validates the key by listing projects and records the unique `tidbx_virtual` project as the profile's default project. - -Configure a named profile: - -```bash -tdc configure --profile staging -``` - -For CI or another non-interactive environment, prefer environment variables: - -```bash -TDC_PUBLIC_KEY="" \ -TDC_PRIVATE_KEY="" \ -TDC_REGION_CODE="aws-us-east-1" \ -tdc configure --profile ci --non-interactive -``` - -You can also provide `--tdc-public-key`, `--tdc-private-key`, and `--region-code`, but secret flags can remain in shell history or process listings. - -Configuration precedence is command flag, environment variable, then saved profile. The global `--region` overrides only the placement for the current command: - -```bash -tdc db list-db-clusters --db-cluster-type starter --profile staging --region aws-us-west-2 -``` - -## Get help and version information - -All command levels support `help`, `--help`, and `--version`: - -```bash -tdc help -tdc fs help -tdc db create-db-cluster help -tdc --version -tdc fs --version -``` - -Required flags appear before optional flags in generated usage. The TiDB Cloud CLI supports long flags only. - -## Update TiDB Cloud CLI - -Check without changing files: - -```bash -tdc update --check -``` - -In automation, fail when an update exists: - -```bash -tdc update --check --fail-if-update-available -``` - -Preview and apply an update: - -```bash -tdc update --dry-run -tdc update -``` - -Install a specific TiDB Cloud CLI release: - -```bash -tdc update --target-version v0.1.2 -``` - -The update command replaces both binaries in the user-owned install directory. An active Filesystem mount keeps running the already loaded companion process. To avoid mixing the old mount runtime with new CLI commands, stop writers and unmount before updating. Graceful unmount automatically flushes and drains pending FUSE work: - -```bash -tdc fs unmount-file-system --mount-path /path/to/workspace -tdc update -``` - -For WebDAV, close writers and unmount. Use the FUSE-only drain command separately only when you need a durability barrier without unmounting. Installations in protected or package-manager-owned locations are not modified. Run the installer once to migrate an older `/usr/local/bin` installation to `~/.tdc/bin`. - -## Uninstall TiDB Cloud CLI - -Remove only the binaries: - -```bash -rm -f "$HOME/.tdc/bin/tdc" "$HOME/.tdc/bin/tdc-drive9" -``` - -On Windows: - -```powershell -Remove-Item "$HOME\.tdc\bin\tdc.exe", "$HOME\.tdc\bin\tdc-drive9.exe" -``` - -Removing binaries preserves profiles, credentials, Filesystem registrations, DB SQL credentials, logs, and mount locators. Remove `~/.tdc/` only when you intend to delete all local TiDB Cloud CLI state: - -```bash -rm -rf "$HOME/.tdc" -``` - -Deleting local state does not delete remote Starter clusters or Filesystem resources. - -## What's next - -- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) diff --git a/ai/tdc/reference/tdc-organization.md b/ai/tdc/reference/tdc-organization.md deleted file mode 100644 index 59d6d22c48c91..0000000000000 --- a/ai/tdc/reference/tdc-organization.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: TiDB Cloud Organization CLI Command Reference -summary: Reference the `tdc organization` command tree, project listing inputs, output, and examples. ---- - -# TiDB Cloud Organization CLI Command Reference - -Use `tdc organization` to inspect the projects accessible to the configured TiDB Cloud API key. - -> **Note:** -> -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. - -## Command tree - -```text -tdc organization -└── list-projects -``` - -`list-projects` requires a configured TiDB Cloud API key. It accepts `--page-size` and `--page-token` for pagination, plus the global output and query flags. - -## Prerequisites - -Run `tdc configure` with a TiDB Cloud API key that can list organization projects. - -## List projects - -```bash -tdc organization list-projects -``` - -The JSON response includes project IDs, names, and `type` values: - -- `tidbx` identifies a regular project; -- `tidbx_virtual` identifies a virtual project used as the default Starter project. - -Request a page size or continue with a returned page token: - -```bash -tdc organization list-projects --page-size 50 -tdc organization list-projects --page-size 50 --page-token "" -``` - -Render a terminal-oriented table or select fields: - -```bash -tdc organization list-projects --output text -tdc organization list-projects --query 'projects[].{id:id,name:name,type:type}' -``` - -## Default virtual project - -`tdc configure` calls the same project-listing API. Configuration succeeds only when it finds exactly one accessible `tidbx_virtual` project, and saves its ID in the selected profile: - -```toml -[default] -region_code = "aws-us-east-1" -project_id = "..." -``` - -`tdc db create-db-cluster` uses this project when `--project-id` is omitted. If the saved ID is removed, cluster creation omits the project label and TiDB Cloud selects the account's default project. Pass an explicit project ID to override either default for one cluster: - -```bash -tdc db create-db-cluster \ - --db-cluster-type starter \ - --db-cluster-name project-specific-cluster \ - --project-id "" -``` - -## What's next - -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/tdc-overview.md b/ai/tdc/tdc-overview.md deleted file mode 100644 index 458894113df60..0000000000000 --- a/ai/tdc/tdc-overview.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: TiDB Cloud Command Line Interface Overview -summary: Learn when to use the TiDB Cloud CLI to manage TiDB Cloud Starter databases and persistent Filesystems for users, automation, and AI agents. ---- - -# TiDB Cloud Command Line Interface Overview - -The TiDB Cloud Command Line Interface—`tdc`—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. - -> **Note:** -> -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. - -## 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. `tdc` is the new CLI for Starter and TiDB Cloud Filesystem. `ticloud` remains the CLI for Essential and also supports existing Starter workflows. - -| Interface | Use it for | Interaction model | -| --- | --- | --- | -| `tdc` (Preview) | New TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows | Predictable commands, JSON output by default, and non-interactive operation except for `tdc configure` | -| `ticloud` | TiDB Cloud Essential and operations not available in the TiDB Cloud CLI, such as import, export, and audit-log commands | Traditional CLI workflows with interactive and non-interactive modes | -| TiDB Cloud console | Visual resource inspection, guided setup, and manual operations | Browser-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 `tdc` executable has a two-level command model: - -```text -tdc -``` - -Examples include `tdc db list-db-clusters --db-cluster-type starter`, `tdc fs copy-file`, and `tdc fs-journal verify-journal`. The top-level `tdc configure` and `tdc update` commands configure and maintain the CLI. - -## TiDB Cloud CLI and Drive9 - -The TiDB Cloud CLI installs a bundled [Drive9](https://github.com/mem9-ai/drive9) companion named `tdc-drive9`. The TiDB Cloud CLI owns profile selection, TiDB Cloud credentials, region and Filesystem selection, output formatting, and `tdc` error behavior. The companion owns Filesystem data-plane semantics, FUSE and WebDAV mounts, layers, pack and unpack, Git workspace acceleration, journals, and vault operations. - -You do not need to install, configure, or invoke Drive9 separately for normal TiDB Cloud CLI workflows. - -## Find the right documentation - -Follow the [Quick Start](/ai/tdc/tdc-quick-start.md) to install the TiDB Cloud CLI and complete your first Starter or Filesystem workflow. Use these guides for task-oriented instructions: - -- [Install, Configure, and Update TiDB Cloud CLI](/ai/tdc/reference/tdc-install-configure-update.md) -- [TiDB Cloud Organization CLI Command Reference](/ai/tdc/reference/tdc-organization.md) -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) -- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) -- [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) - -### Scenario references - -Use scenarios to follow a complete workflow that combines multiple commands and features: - -For users and automation: - -- [Run a Daily TiDB Cloud CLI Workflow](/ai/tdc/reference/tdc-daily-workflow-example.md) -- [Query SQL with Explicit Roles](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) -- [Share a Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) -- [Hand Off CI Artifacts Between Jobs](/ai/tdc/reference/tdc-ci-artifact-handoff-example.md) - -For AI agents: - -- [Use a Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) -- [Persist Agent State Across Sandboxes](/ai/tdc/reference/tdc-persistent-agent-state-example.md) -- [Share a Read-Only Dataset Across Parallel Agents](/ai/tdc/reference/tdc-parallel-agent-dataset-example.md) -- [Prepare a Git Workspace for Agents](/ai/tdc/reference/tdc-git-workspace-for-agents-example.md) -- [Record an Agent Workflow in a Journal](/ai/tdc/reference/tdc-journal-agent-workflow-example.md) -- [Delegate Secrets to an Agent](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) - -### Reference - -- [TiDB Cloud CLI Command Reference](/ai/tdc/reference/tdc-cli-reference.md) -- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) -- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) - -To report a problem or suggest an improvement, create an issue in the [TiDB Cloud CLI GitHub repository](https://github.com/tidbcloud/tdc/issues). diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md b/ai/ti/reference/commands/db/ti-db-create-db-cluster-branch.md similarity index 61% rename from ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md rename to ai/ti/reference/commands/db/ti-db-create-db-cluster-branch.md index 933ef210ced82..9e37e300918ea 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster-branch.md +++ b/ai/ti/reference/commands/db/ti-db-create-db-cluster-branch.md @@ -1,20 +1,20 @@ --- -title: tdc db create-db-cluster-branch +title: ti db create-db-cluster-branch summary: Create a branch for a TiDB Cloud Starter cluster. --- -# tdc db create-db-cluster-branch +# ti db create-db-cluster-branch Creates a branch for one Starter cluster. `--wait` waits for the branch to become `ACTIVE`. The command verifies that the parent cluster is Starter before creating the branch. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db create-db-cluster-branch +ti db create-db-cluster-branch --db-cluster-branch-name --db-cluster-id [--dry-run] @@ -32,7 +32,7 @@ tdc db create-db-cluster-branch - `--version`: Display version information. - `--wait`: Wait until the created branch becomes `ACTIVE` before returning. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -40,16 +40,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Wait until the new database branch can accept connections. - tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name dev --wait + ti db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name dev --wait ``` - Preview branch creation: ```bash # Validate the parent cluster and branch request without creating it. - tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name preview --dry-run + ti db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name preview --dry-run ``` ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md b/ai/ti/reference/commands/db/ti-db-create-db-cluster.md similarity index 68% rename from ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md rename to ai/ti/reference/commands/db/ti-db-create-db-cluster.md index 76f0f9b3fd3a3..9893ce8025fbd 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-cluster.md +++ b/ai/ti/reference/commands/db/ti-db-create-db-cluster.md @@ -1,20 +1,20 @@ --- -title: tdc db create-db-cluster +title: ti db create-db-cluster summary: Create a TiDB Cloud Starter cluster. --- -# tdc db create-db-cluster +# ti db create-db-cluster Creates a Starter cluster. The required `--db-cluster-type` must be `starter`; there is no implicit type. `--wait` waits for the cluster to become `ACTIVE`. Project selection uses an explicit `--project-id`, then the configured virtual project, then the TiDB Cloud account default. The TiDB Cloud CLI validates the returned service plan; if verification fails after creation is accepted, it reports the cluster ID and retains the cluster for inspection. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db create-db-cluster +ti db create-db-cluster --db-cluster-name --db-cluster-type [--dry-run] @@ -36,7 +36,7 @@ tdc db create-db-cluster - `--version`: Display version information. - `--wait`: Wait until the created cluster becomes `ACTIVE` before returning. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -44,37 +44,37 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Wait until the new Starter cluster reaches the ACTIVE state. - tdc db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --wait + ti db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --wait ``` - Create a cluster asynchronously: ```bash # Return after TiDB Cloud accepts creation so another process can poll the cluster. - tdc db create-db-cluster --db-cluster-type starter --db-cluster-name background-db + ti db create-db-cluster --db-cluster-type starter --db-cluster-name background-db ``` - Preview cluster creation: ```bash # Validate the request and resolved defaults without creating a cluster. - tdc db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --dry-run + ti db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --dry-run ``` - Create a cluster in an explicit project: ```bash # Override the configured virtual project for this cluster. - tdc db create-db-cluster --db-cluster-type starter --db-cluster-name project-db --project-id "" --wait + ti db create-db-cluster --db-cluster-type starter --db-cluster-name project-db --project-id "" --wait ``` - Set a monthly spending limit: ```bash # Create a paid Starter cluster with a monthly limit expressed in US dollar cents. - tdc db create-db-cluster --db-cluster-type starter --db-cluster-name production-db --monthly-spending-limit-usd-cents 1000 --wait + ti db create-db-cluster --db-cluster-type starter --db-cluster-name production-db --monthly-spending-limit-usd-cents 1000 --wait ``` ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md b/ai/ti/reference/commands/db/ti-db-create-db-sql-users.md similarity index 51% rename from ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md rename to ai/ti/reference/commands/db/ti-db-create-db-sql-users.md index 8f23c8ba3f184..d8700c05a8167 100644 --- a/ai/tdc/reference/commands/db/tdc-db-create-db-sql-users.md +++ b/ai/ti/reference/commands/db/ti-db-create-db-sql-users.md @@ -1,20 +1,20 @@ --- -title: tdc db create-db-sql-users +title: ti db create-db-sql-users summary: Create TiDB Cloud CLI-managed SQL users for a Starter cluster. --- -# tdc db create-db-sql-users +# ti db create-db-sql-users -Idempotently creates or repairs the read-only, read-write, and admin SQL users managed by `tdc`. The command verifies that the cluster is Starter before calling SQL-user APIs or writing local credentials. +Idempotently creates or repairs the read-only, read-write, and admin SQL users managed by `ti`. The command verifies that the cluster is Starter before calling SQL-user APIs or writing local credentials. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db create-db-sql-users +ti db create-db-sql-users --db-cluster-id [--dry-run] [--help] @@ -28,7 +28,7 @@ tdc db create-db-sql-users - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -36,16 +36,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Create or reconcile the read-only, read-write, and admin SQL users. - tdc db create-db-sql-users --db-cluster-id "" + ti db create-db-sql-users --db-cluster-id "" ``` - Preview SQL user creation: ```bash # Show the three managed roles without changing SQL users or local credentials. - tdc db create-db-sql-users --db-cluster-id "" --dry-run + ti db create-db-sql-users --db-cluster-id "" --dry-run ``` ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md b/ai/ti/reference/commands/db/ti-db-delete-db-cluster-branch.md similarity index 58% rename from ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md rename to ai/ti/reference/commands/db/ti-db-delete-db-cluster-branch.md index 44c68ed0801d0..c5bc5f668abaf 100644 --- a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster-branch.md +++ b/ai/ti/reference/commands/db/ti-db-delete-db-cluster-branch.md @@ -1,20 +1,20 @@ --- -title: tdc db delete-db-cluster-branch +title: ti db delete-db-cluster-branch summary: Delete a branch from a TiDB Cloud Starter cluster. --- -# tdc db delete-db-cluster-branch +# ti db delete-db-cluster-branch Deletes one branch from a Starter cluster. The command verifies that the parent cluster is Starter before reading or deleting the branch. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db delete-db-cluster-branch +ti db delete-db-cluster-branch --db-cluster-branch-id --db-cluster-id [--dry-run] @@ -30,7 +30,7 @@ tdc db delete-db-cluster-branch - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,9 +38,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Delete only the selected branch from its parent Starter cluster. - tdc db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" + ti db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" ``` ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md b/ai/ti/reference/commands/db/ti-db-delete-db-cluster.md similarity index 64% rename from ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md rename to ai/ti/reference/commands/db/ti-db-delete-db-cluster.md index b5ba9b90b0ad1..8fedac716c62c 100644 --- a/ai/tdc/reference/commands/db/tdc-db-delete-db-cluster.md +++ b/ai/ti/reference/commands/db/ti-db-delete-db-cluster.md @@ -1,20 +1,20 @@ --- -title: tdc db delete-db-cluster +title: ti db delete-db-cluster summary: Delete a TiDB Cloud Starter cluster. --- -# tdc db delete-db-cluster +# ti db delete-db-cluster Deletes one Starter cluster. `--wait` waits until deletion is observable. The command verifies the service plan before sending the delete request and rejects non-Starter or unverifiable clusters without sending `DELETE`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db delete-db-cluster +ti db delete-db-cluster --db-cluster-id [--dry-run] [--help] @@ -30,7 +30,7 @@ tdc db delete-db-cluster - `--version`: Display version information. - `--wait`: Wait until the deleted cluster reaches `DELETED` or is no longer accessible. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,16 +38,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Wait until TiDB Cloud reports the cluster deleted or no longer accessible. - tdc db delete-db-cluster --db-cluster-id "" --wait + ti db delete-db-cluster --db-cluster-id "" --wait ``` - Delete a cluster asynchronously: ```bash # Return after TiDB Cloud accepts deletion while cleanup continues remotely. - tdc db delete-db-cluster --db-cluster-id "" + ti db delete-db-cluster --db-cluster-id "" ``` ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md b/ai/ti/reference/commands/db/ti-db-describe-db-cluster-branch.md similarity index 57% rename from ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md rename to ai/ti/reference/commands/db/ti-db-describe-db-cluster-branch.md index 087577cb449d8..71717cf6a1007 100644 --- a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster-branch.md +++ b/ai/ti/reference/commands/db/ti-db-describe-db-cluster-branch.md @@ -1,20 +1,20 @@ --- -title: tdc db describe-db-cluster-branch +title: ti db describe-db-cluster-branch summary: Describe a branch for a TiDB Cloud Starter cluster. --- -# tdc db describe-db-cluster-branch +# ti db describe-db-cluster-branch Describes one branch by cluster ID and branch ID. The command verifies that the parent cluster is Starter before reading the branch. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db describe-db-cluster-branch +ti db describe-db-cluster-branch --db-cluster-branch-id --db-cluster-id [--help] @@ -30,7 +30,7 @@ tdc db describe-db-cluster-branch - `--version`: Display version information. - `--view `: Detail level: `BASIC` or `FULL`. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,9 +38,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return full lifecycle and connection details for one branch. - tdc db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" --view FULL + ti db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" --view FULL ``` ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md b/ai/ti/reference/commands/db/ti-db-describe-db-cluster.md similarity index 57% rename from ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md rename to ai/ti/reference/commands/db/ti-db-describe-db-cluster.md index 3255a33aee89c..84bd40e24bc8b 100644 --- a/ai/tdc/reference/commands/db/tdc-db-describe-db-cluster.md +++ b/ai/ti/reference/commands/db/ti-db-describe-db-cluster.md @@ -1,20 +1,20 @@ --- -title: tdc db describe-db-cluster +title: ti db describe-db-cluster summary: Describe a TiDB Cloud Starter cluster. --- -# tdc db describe-db-cluster +# ti db describe-db-cluster Describes one Starter cluster. Use `--view FULL` to request expanded fields. The command rejects the cluster if its API metadata does not verify it as Starter. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db describe-db-cluster +ti db describe-db-cluster --db-cluster-id [--help] [--version] @@ -28,7 +28,7 @@ tdc db describe-db-cluster - `--version`: Display version information. - `--view `: Detail level: `BASIC` or `FULL`. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -36,9 +36,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return the cluster state, placement, and connection metadata. - tdc db describe-db-cluster --db-cluster-id "" --view FULL + ti db describe-db-cluster --db-cluster-id "" --view FULL ``` ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md b/ai/ti/reference/commands/db/ti-db-execute-sql-statement.md similarity index 63% rename from ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md rename to ai/ti/reference/commands/db/ti-db-execute-sql-statement.md index d6ccb865a371c..965871e872f94 100644 --- a/ai/tdc/reference/commands/db/tdc-db-execute-sql-statement.md +++ b/ai/ti/reference/commands/db/ti-db-execute-sql-statement.md @@ -1,20 +1,20 @@ --- -title: tdc db execute-sql-statement +title: ti db execute-sql-statement summary: Execute one SQL statement against a TiDB Cloud Starter cluster. --- -# tdc db execute-sql-statement +# ti db execute-sql-statement Executes exactly one SQL statement. Read-write is the default role; explicit role selection is recommended. The command verifies that the cluster is Starter before loading credentials or sending an HTTPS or MySQL request. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db execute-sql-statement +ti db execute-sql-statement --db-cluster-id --sql [--admin] @@ -38,7 +38,7 @@ tdc db execute-sql-statement - `--transport `: SQL execution transport: `https` or `mysql`. \[default: https] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -46,30 +46,30 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Use the default prepared role for normal application reads and writes. - tdc db execute-sql-statement --db-cluster-id "" --sql "INSERT INTO app.events(message) VALUES ('ready')" + ti db execute-sql-statement --db-cluster-id "" --sql "INSERT INTO app.events(message) VALUES ('ready')" ``` - Run a read-only query: ```bash # Prevent the statement from using read-write or admin credentials. - tdc db execute-sql-statement --db-cluster-id "" --read-only --sql "SELECT 1 AS ready" --output text + ti db execute-sql-statement --db-cluster-id "" --read-only --sql "SELECT 1 AS ready" --output text ``` - Run an administrative statement: ```bash # Use the admin role for schema creation or privilege management. - tdc db execute-sql-statement --db-cluster-id "" --admin --sql "CREATE DATABASE IF NOT EXISTS app" + ti db execute-sql-statement --db-cluster-id "" --admin --sql "CREATE DATABASE IF NOT EXISTS app" ``` - Use the MySQL fallback transport: ```bash # Open a one-shot MySQL connection when the HTTPS SQL API is unsuitable. - tdc db execute-sql-statement --db-cluster-id "" --transport mysql --sql "SELECT CURRENT_TIMESTAMP" + ti db execute-sql-statement --db-cluster-id "" --transport mysql --sql "SELECT CURRENT_TIMESTAMP" ``` ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md b/ai/ti/reference/commands/db/ti-db-format-db-connection-string.md similarity index 67% rename from ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md rename to ai/ti/reference/commands/db/ti-db-format-db-connection-string.md index 1ea76a810cdc4..3261a82bc5bb4 100644 --- a/ai/tdc/reference/commands/db/tdc-db-format-db-connection-string.md +++ b/ai/ti/reference/commands/db/ti-db-format-db-connection-string.md @@ -1,20 +1,20 @@ --- -title: tdc db format-db-connection-string +title: ti db format-db-connection-string summary: Format a connection string for a TiDB Cloud CLI-managed SQL user. --- -# tdc db format-db-connection-string +# ti db format-db-connection-string Formats stored SQL credentials for read-write, read-only, or admin access. The command verifies that the cluster is Starter before loading its local SQL credentials. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db format-db-connection-string +ti db format-db-connection-string --db-cluster-id [--admin] [--database ] @@ -42,7 +42,7 @@ tdc db format-db-connection-string - `--read-write`: Use prepared `read_write` DB SQL credentials. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -50,30 +50,30 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Use the default application role in tools that accept a MySQL URI. - tdc db format-db-connection-string --db-cluster-id "" --read-write --format mysql-uri + ti db format-db-connection-string --db-cluster-id "" --read-write --format mysql-uri ``` - Format read-only dotenv variables: ```bash # Emit environment assignments for a workload that must not modify data. - tdc db format-db-connection-string --db-cluster-id "" --read-only --format env --env-prefix TIDB_ + ti db format-db-connection-string --db-cluster-id "" --read-only --format env --env-prefix TIDB_ ``` - Format an admin JDBC URL: ```bash # Generate a JDBC connection value with the prepared admin credentials. - tdc db format-db-connection-string --db-cluster-id "" --admin --format jdbc --database app + ti db format-db-connection-string --db-cluster-id "" --admin --format jdbc --database app ``` - Include DATABASE_URL in dotenv output: ```bash # Emit both component variables and a conventional DATABASE_URL value. - tdc db format-db-connection-string --db-cluster-id "" --format env --env-include-database-url + ti db format-db-connection-string --db-cluster-id "" --format env --env-include-database-url ``` ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md b/ai/ti/reference/commands/db/ti-db-list-db-cluster-branches.md similarity index 61% rename from ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md rename to ai/ti/reference/commands/db/ti-db-list-db-cluster-branches.md index 827d670cea3c1..afee7bd7cef00 100644 --- a/ai/tdc/reference/commands/db/tdc-db-list-db-cluster-branches.md +++ b/ai/ti/reference/commands/db/ti-db-list-db-cluster-branches.md @@ -1,20 +1,20 @@ --- -title: tdc db list-db-cluster-branches +title: ti db list-db-cluster-branches summary: List branches for a TiDB Cloud Starter cluster. --- -# tdc db list-db-cluster-branches +# ti db list-db-cluster-branches Lists branches for one Starter cluster, with optional pagination. The command verifies that the parent cluster is Starter before listing branches. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db list-db-cluster-branches +ti db list-db-cluster-branches --db-cluster-id [--help] [--page-size ] @@ -30,7 +30,7 @@ tdc db list-db-cluster-branches - `--page-token `: Page token returned by a previous list-db-cluster-branches call. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,9 +38,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return all branches that belong to the selected Starter cluster. - tdc db list-db-cluster-branches --db-cluster-id "" + ti db list-db-cluster-branches --db-cluster-id "" ``` ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md b/ai/ti/reference/commands/db/ti-db-list-db-clusters.md similarity index 50% rename from ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md rename to ai/ti/reference/commands/db/ti-db-list-db-clusters.md index 7ba4a2a29a676..1906fd10055d2 100644 --- a/ai/tdc/reference/commands/db/tdc-db-list-db-clusters.md +++ b/ai/ti/reference/commands/db/ti-db-list-db-clusters.md @@ -1,20 +1,20 @@ --- -title: tdc db list-db-clusters +title: ti db list-db-clusters summary: List TiDB Cloud Starter clusters. --- -# tdc db list-db-clusters +# ti db list-db-clusters -Lists verified Starter clusters in the effective region with pagination, filtering, ordering, and JMESPath projection. The required `--db-cluster-type` must be `starter`. Cross-region, non-Starter, and unverifiable clusters are omitted. The command incrementally fills each result page from TiDB Cloud API pages and returns an opaque tdc `next_page_token`; it omits the server `total_size`, which can include resources outside the verified result. +Lists verified Starter clusters in the effective region with pagination, filtering, ordering, and JMESPath projection. The required `--db-cluster-type` must be `starter`. Cross-region, non-Starter, and unverifiable clusters are omitted. The command incrementally fills each result page from TiDB Cloud API pages and returns an opaque ti `next_page_token`; it omits the server `total_size`, which can include resources outside the verified result. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db list-db-clusters +ti db list-db-clusters --db-cluster-type [--filter ] [--help] @@ -31,10 +31,10 @@ tdc db list-db-clusters - `--help`: Display help information. - `--order-by `: Starter API orderBy expression. - `--page-size `: Number of verified clusters to return; 0 returns 10 and the maximum is 1000. -- `--page-token `: Opaque tdc page token returned by a previous compatible list-db-clusters call. +- `--page-token `: Opaque ti page token returned by a previous compatible list-db-clusters call. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,25 +42,25 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return Starter clusters in the profile's configured region as structured JSON. - tdc db list-db-clusters --db-cluster-type starter + ti db list-db-clusters --db-cluster-type starter ``` - List clusters in another region: ```bash # Override the region for this invocation without changing the profile. - tdc --region aws-us-west-2 db list-db-clusters --db-cluster-type starter + ti --region aws-us-west-2 db list-db-clusters --db-cluster-type starter ``` - Select cluster fields: ```bash # Reduce the result to IDs, names, and lifecycle states. - tdc db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name,state:state}' + ti db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name,state:state}' ``` -The effective region resolves from global `--region`, then `TDC_REGION_CODE`, then the selected profile's `region_code`. User-supplied `--filter` expressions are combined with this mandatory region scope and cannot expand the result to other regions. A page token can be reused only with the same profile, cluster type, region, filter, and ordering. If its replay page changed, restart the listing without `--page-token`. +The effective region resolves from global `--region`, then `TI_REGION_CODE`, then the selected profile's `region_code`. User-supplied `--filter` expressions are combined with this mandatory region scope and cannot expand the result to other regions. A page token can be reused only with the same profile, cluster type, region, filter, and ordering. If its replay page changed, restart the listing without `--page-token`. ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md b/ai/ti/reference/commands/db/ti-db-update-db-cluster.md similarity index 63% rename from ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md rename to ai/ti/reference/commands/db/ti-db-update-db-cluster.md index 2088d435a6aa7..6beea73b90d6b 100644 --- a/ai/tdc/reference/commands/db/tdc-db-update-db-cluster.md +++ b/ai/ti/reference/commands/db/ti-db-update-db-cluster.md @@ -1,20 +1,20 @@ --- -title: tdc db update-db-cluster +title: ti db update-db-cluster summary: Update a TiDB Cloud Starter cluster. --- -# tdc db update-db-cluster +# ti db update-db-cluster Updates the display name or monthly spending limit of one Starter cluster. The command verifies the service plan before sending the update and rejects non-Starter or unverifiable clusters without sending `PATCH`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc db update-db-cluster +ti db update-db-cluster --db-cluster-id [--db-cluster-name ] [--dry-run] @@ -32,7 +32,7 @@ tdc db update-db-cluster - `--monthly-spending-limit-usd-cents `: Monthly spending limit in USD cents; omit to leave unchanged. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -40,16 +40,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Change the Starter cluster display name without recreating it. - tdc db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2 + ti db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2 ``` - Preview a spending-limit update: ```bash # Validate a new monthly limit without applying the change. - tdc db update-db-cluster --db-cluster-id "" --monthly-spending-limit-usd-cents 1000 --dry-run + ti db update-db-cluster --db-cluster-id "" --monthly-spending-limit-usd-cents 1000 --dry-run ``` ## Related documentation -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md b/ai/ti/reference/commands/fs-git/ti-fs-git-add-git-worktree.md similarity index 64% rename from ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md rename to ai/ti/reference/commands/fs-git/ti-fs-git-add-git-worktree.md index c11706a3f1b5a..35e625fd8179d 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-add-git-worktree.md +++ b/ai/ti/reference/commands/fs-git/ti-fs-git-add-git-worktree.md @@ -1,20 +1,20 @@ --- -title: tdc fs-git add-git-worktree +title: ti fs-git add-git-worktree summary: Add a linked Git worktree in a mounted TiDB Cloud Filesystem. --- -# tdc fs-git add-git-worktree +# ti fs-git add-git-worktree Adds a linked Git worktree from a base workspace. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-git add-git-worktree +ti fs-git add-git-worktree --base-path --worktree-path [--blobless] @@ -38,13 +38,13 @@ tdc fs-git add-git-worktree - `--commit-ish `: Optional commit-ish for the linked worktree. - `--detach`: Create a detached linked worktree. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--hydrate `: Blobless hydrate mode: `auto`, `background`, `sync`, or `off`. \[default: auto] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -52,16 +52,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Give an agent an isolated branch while sharing the base Git object store. - tdc fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-feature --branch-name feature-x + ti fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-feature --branch-name feature-x ``` - Create a detached worktree: ```bash # Inspect a commit without creating or switching a branch. - tdc fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-review --commit-ish origin/main --detach + ti fs-git add-git-worktree --file-system-name workspace --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-review --commit-ish origin/main --detach ``` ## Related documentation -- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md b/ai/ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.md similarity index 58% rename from ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md rename to ai/ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.md index 1700d1d7a96b9..259a4a842aaf4 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-clone-git-workspace.md +++ b/ai/ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.md @@ -1,20 +1,20 @@ --- -title: tdc fs-git clone-git-workspace +title: ti fs-git clone-git-workspace summary: Clone a Git repository into a mounted TiDB Cloud Filesystem. --- -# tdc fs-git clone-git-workspace +# ti fs-git clone-git-workspace Clones a repository into a mounted Filesystem path. Hydration can run synchronously or in the background. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-git clone-git-workspace +ti fs-git clone-git-workspace --repo-url --target-path [--blobless] @@ -32,13 +32,13 @@ tdc fs-git clone-git-workspace - `--target-path `: The mounted file system path to clone into. \[required] - `--blobless`: Create a blobless partial local `.git` and hydrate clean blobs separately. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--hydrate `: Blobless hydrate mode: `auto`, `background`, `sync`, or `off`. \[default: auto] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -46,23 +46,23 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Create a complete Git checkout in the mounted Filesystem path. - tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb + ti fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb ``` - Start a blobless workspace immediately: ```bash # Expose the repository tree while clean Git objects hydrate in the background. - tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate background + ti fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate background ``` - Wait for blobless hydration: ```bash # Keep the clone command running until clean Git objects finish hydrating. - tdc fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate sync + ti fs-git clone-git-workspace --file-system-name workspace --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate sync ``` ## Related documentation -- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/ti/reference/commands/fs-git/ti-fs-git-hydrate-git-workspace.md b/ai/ti/reference/commands/fs-git/ti-fs-git-hydrate-git-workspace.md new file mode 100644 index 0000000000000..fc077e84b85dd --- /dev/null +++ b/ai/ti/reference/commands/fs-git/ti-fs-git-hydrate-git-workspace.md @@ -0,0 +1,48 @@ +--- +title: ti fs-git hydrate-git-workspace +summary: Hydrate clean Git objects in a Filesystem Git workspace. +--- + +# ti fs-git hydrate-git-workspace + +Hydrates clean Git objects for an existing `ti` Git workspace. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-git hydrate-git-workspace + --target-path + [--file-system-name ] + [--fs-token ] + [--help] + [--timeout ] + [--version] +``` + +## Options + +- `--target-path `: Mounted `ti fs` workspace path. \[required] +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--timeout `: Maximum hydrate duration. \[default: `30m0s`] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Finish hydrating a Git workspace: + + ```bash + # Download missing clean Git objects for an existing blobless workspace. + ti fs-git hydrate-git-workspace --file-system-name workspace --target-path /path/to/workspace/tidb --timeout 30m + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md b/ai/ti/reference/commands/fs-git/ti-fs-git-remove-git-worktree.md similarity index 53% rename from ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md rename to ai/ti/reference/commands/fs-git/ti-fs-git-remove-git-worktree.md index 2a4e83c0eb141..174a93aea1a1a 100644 --- a/ai/tdc/reference/commands/fs-git/tdc-fs-git-remove-git-worktree.md +++ b/ai/ti/reference/commands/fs-git/ti-fs-git-remove-git-worktree.md @@ -1,20 +1,20 @@ --- -title: tdc fs-git remove-git-worktree +title: ti fs-git remove-git-worktree summary: Remove a linked Git worktree from a mounted TiDB Cloud Filesystem. --- -# tdc fs-git remove-git-worktree +# ti fs-git remove-git-worktree Removes a linked worktree without recursively deleting shared clean-tree data. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-git remove-git-worktree +ti fs-git remove-git-worktree --worktree-path [--dry-run] [--file-system-name ] @@ -26,15 +26,15 @@ tdc fs-git remove-git-worktree ## Options -- `--worktree-path `: Mounted `tdc fs` path of the linked worktree. \[required] +- `--worktree-path `: Mounted `ti fs` path of the linked worktree. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. - `--force`: Remove even when the linked worktree has local changes. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,9 +42,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Force removal when the isolated worktree still contains local changes. - tdc fs-git remove-git-worktree --file-system-name workspace --worktree-path /path/to/workspace/tidb-feature --force + ti fs-git remove-git-worktree --file-system-name workspace --worktree-path /path/to/workspace/tidb-feature --force ``` ## Related documentation -- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md b/ai/ti/reference/commands/fs-journal/ti-fs-journal-append-journal-entries.md similarity index 62% rename from ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md rename to ai/ti/reference/commands/fs-journal/ti-fs-journal-append-journal-entries.md index 9b57cee986053..2b2ce68afb9e8 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-append-journal-entries.md +++ b/ai/ti/reference/commands/fs-journal/ti-fs-journal-append-journal-entries.md @@ -1,20 +1,20 @@ --- -title: tdc fs-journal append-journal-entries +title: ti fs-journal append-journal-entries summary: Append entries to a Filesystem journal. --- -# tdc fs-journal append-journal-entries +# ti fs-journal append-journal-entries Appends one JSON event or a JSON array to a journal. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-journal append-journal-entries +ti fs-journal append-journal-entries --journal-id [--dry-run] [--entry-json ] @@ -35,8 +35,8 @@ tdc fs-journal append-journal-entries - `--dry-run`: Validate the request without applying changes. - `--entry-json `: One JSON journal entry object; repeatable. - `--entry-type `: Default entry type for entries missing type. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--idempotency-key `: Append idempotency key; generated when omitted. - `--json-array`: Read a JSON array from stdin instead of JSONL. @@ -44,7 +44,7 @@ tdc fs-journal append-journal-entries - `--subject `: Entry subject; repeatable. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -52,23 +52,23 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Record an event object exactly as supplied on the command line. - tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-json '{"type":"task.started"}' + ti fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-json '{"type":"task.started"}' ``` - Append an idempotent typed entry: ```bash # Prevent retries from recording the same completion event twice. - tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-type task.completed --subject issue-42 --idempotency-key issue-42-complete + ti fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --entry-type task.completed --subject issue-42 --idempotency-key issue-42-complete ``` - Append a JSON array from standard input: ```bash # Batch multiple ordered events in a single append operation. - printf '[{"type":"step.started"},{"type":"step.completed"}]' | tdc fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --json-array + printf '[{"type":"step.started"},{"type":"step.completed"}]' | ti fs-journal append-journal-entries --file-system-name workspace --journal-id jrn-demo --json-array ``` ## Related documentation -- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md b/ai/ti/reference/commands/fs-journal/ti-fs-journal-create-journal.md similarity index 60% rename from ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md rename to ai/ti/reference/commands/fs-journal/ti-fs-journal-create-journal.md index d6f9f1302e433..966beceb2d80b 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-create-journal.md +++ b/ai/ti/reference/commands/fs-journal/ti-fs-journal-create-journal.md @@ -1,20 +1,20 @@ --- -title: tdc fs-journal create-journal +title: ti fs-journal create-journal summary: Create an append-only Filesystem journal. --- -# tdc fs-journal create-journal +# ti fs-journal create-journal Creates a journal. If `--journal-id` is omitted, the service generates one. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-journal create-journal +ti fs-journal create-journal [--actor ] [--dry-run] [--file-system-name ] @@ -31,8 +31,8 @@ tdc fs-journal create-journal - `--actor `: Actor in the form `type:id`. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--journal-id `: Journal ID; generated when omitted. - `--journal-kind `: Journal kind. \[default: agent] @@ -40,7 +40,7 @@ tdc fs-journal create-journal - `--title `: Journal title. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -48,16 +48,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Create an append-only journal for one agent task. - tdc fs-journal create-journal --file-system-name workspace --journal-id jrn-demo --journal-kind agent --title "demo task" + ti fs-journal create-journal --file-system-name workspace --journal-id jrn-demo --journal-kind agent --title "demo task" ``` - Create a labeled deployment journal: ```bash # Attach actor and environment metadata for later searches. - tdc fs-journal create-journal --file-system-name workspace --journal-kind deployment --actor agent:tdc --label env=dev + ti fs-journal create-journal --file-system-name workspace --journal-kind deployment --actor agent:ti --label env=dev ``` ## Related documentation -- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md b/ai/ti/reference/commands/fs-journal/ti-fs-journal-read-journal-entries.md similarity index 56% rename from ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md rename to ai/ti/reference/commands/fs-journal/ti-fs-journal-read-journal-entries.md index 6bf6d26229332..c8dfdf58b6f74 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-read-journal-entries.md +++ b/ai/ti/reference/commands/fs-journal/ti-fs-journal-read-journal-entries.md @@ -1,20 +1,20 @@ --- -title: tdc fs-journal read-journal-entries +title: ti fs-journal read-journal-entries summary: Read entries from a Filesystem journal. --- -# tdc fs-journal read-journal-entries +# ti fs-journal read-journal-entries Reads entries from one journal in sequence order. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-journal read-journal-entries +ti fs-journal read-journal-entries --journal-id [--after-seq ] [--file-system-name ] @@ -28,13 +28,13 @@ tdc fs-journal read-journal-entries - `--journal-id `: Journal ID. \[required] - `--after-seq `: Read entries after this sequence. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--limit `: Maximum entries to read. \[default: 100] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,16 +42,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return the first page of ordered entries for a journal. - tdc fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo + ti fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo ``` - Continue after a sequence number: ```bash # Read the next page after the last sequence processed by a consumer. - tdc fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo --after-seq 100 --limit 50 + ti fs-journal read-journal-entries --file-system-name workspace --journal-id jrn-demo --after-seq 100 --limit 50 ``` ## Related documentation -- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md b/ai/ti/reference/commands/fs-journal/ti-fs-journal-search-journal-entries.md similarity index 64% rename from ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md rename to ai/ti/reference/commands/fs-journal/ti-fs-journal-search-journal-entries.md index d07cef283431e..53d1e543ee784 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-search-journal-entries.md +++ b/ai/ti/reference/commands/fs-journal/ti-fs-journal-search-journal-entries.md @@ -1,20 +1,20 @@ --- -title: tdc fs-journal search-journal-entries +title: ti fs-journal search-journal-entries summary: Search Filesystem journals and entries. --- -# tdc fs-journal search-journal-entries +# ti fs-journal search-journal-entries Searches journals and optionally returns matching entries. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-journal search-journal-entries +ti fs-journal search-journal-entries [--actor ] [--cursor ] [--entry-type ] @@ -37,8 +37,8 @@ tdc fs-journal search-journal-entries - `--actor `: Actor in the form `type:id`. - `--cursor `: Pagination cursor. - `--entry-type `: Entry type filter. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--include-entries`: Include full entry payloads in matches. - `--journal-kind `: Journal kind filter. @@ -50,7 +50,7 @@ tdc fs-journal search-journal-entries - `--until `: RFC3339 upper time bound. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -58,23 +58,23 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Find journals containing task-start events and include their payloads. - tdc fs-journal search-journal-entries --file-system-name workspace --entry-type task.started --include-entries + ti fs-journal search-journal-entries --file-system-name workspace --entry-type task.started --include-entries ``` - Search by label and time: ```bash # Limit deployment journal matches to one environment and time window. - tdc fs-journal search-journal-entries --file-system-name workspace --label env=dev --since 2026-07-01T00:00:00Z --limit 100 + ti fs-journal search-journal-entries --file-system-name workspace --label env=dev --since 2026-07-01T00:00:00Z --limit 100 ``` - Search by actor and subject: ```bash # Find events produced by one agent for a specific task subject. - tdc fs-journal search-journal-entries --file-system-name workspace --actor agent:tdc --subject issue-42 --include-entries + ti fs-journal search-journal-entries --file-system-name workspace --actor agent:ti --subject issue-42 --include-entries ``` ## Related documentation -- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) diff --git a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md b/ai/ti/reference/commands/fs-journal/ti-fs-journal-verify-journal.md similarity index 52% rename from ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md rename to ai/ti/reference/commands/fs-journal/ti-fs-journal-verify-journal.md index 5ee9b41519449..c4e8430370e95 100644 --- a/ai/tdc/reference/commands/fs-journal/tdc-fs-journal-verify-journal.md +++ b/ai/ti/reference/commands/fs-journal/ti-fs-journal-verify-journal.md @@ -1,20 +1,20 @@ --- -title: tdc fs-journal verify-journal +title: ti fs-journal verify-journal summary: Verify a Filesystem journal hash chain. --- -# tdc fs-journal verify-journal +# ti fs-journal verify-journal Verifies the integrity of one journal hash chain. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-journal verify-journal +ti fs-journal verify-journal --journal-id [--file-system-name ] [--fs-token ] @@ -25,12 +25,12 @@ tdc fs-journal verify-journal ## Options - `--journal-id `: Journal ID. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,9 +38,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Validate the journal's ordered hash chain and integrity metadata. - tdc fs-journal verify-journal --file-system-name workspace --journal-id jrn-demo + ti fs-journal verify-journal --file-system-name workspace --journal-id jrn-demo ``` ## Related documentation -- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-grant.md similarity index 63% rename from ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md rename to ai/ti/reference/commands/fs-vault/ti-fs-vault-create-grant.md index 35fdacea52aff..9728ac19ca4f3 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-grant.md +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-grant.md @@ -1,20 +1,20 @@ --- -title: tdc fs-vault create-grant +title: ti fs-vault create-grant summary: Create a delegated Filesystem Vault grant. --- -# tdc fs-vault create-grant +# ti fs-vault create-grant Creates a time-limited delegated grant for one agent and scope. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-vault create-grant +ti fs-vault create-grant --agent-id --permission --scope @@ -35,14 +35,14 @@ tdc fs-vault create-grant - `--scope `: Vault scope such as secret or secret/field; repeatable. \[required] - `--ttl `: Grant time to live, for example, `1h`. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--label-hint `: Optional grant label hint. - `--token-only`: Print only the delegated bearer token. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -50,16 +50,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Limit an agent to one secret field for ten minutes. - tdc fs-vault create-grant --file-system-name workspace --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m + ti fs-vault create-grant --file-system-name workspace --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m ``` - Return only the delegated token: ```bash # Produce token-only output for injection into an isolated CI job. - tdc fs-vault create-grant --file-system-name workspace --agent-id ci-agent --scope api-dev/TOKEN --permission read --ttl 5m --token-only + ti fs-vault create-grant --file-system-name workspace --agent-id ci-agent --scope api-dev/TOKEN --permission read --ttl 5m --token-only ``` ## Related documentation -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-secret.md similarity index 56% rename from ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md rename to ai/ti/reference/commands/fs-vault/ti-fs-vault-create-secret.md index d952eff72f9ed..03d8d58eae29c 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-create-secret.md +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-secret.md @@ -1,20 +1,20 @@ --- -title: tdc fs-vault create-secret +title: ti fs-vault create-secret summary: Create a secret in Filesystem Vault. --- -# tdc fs-vault create-secret +# ti fs-vault create-secret Creates a secret from one or more `NAME=value` or `NAME=@file` fields. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-vault create-secret +ti fs-vault create-secret --field --secret-name [--dry-run] @@ -29,12 +29,12 @@ tdc fs-vault create-secret - `--field `: Secret field assignment `key=value`, `key=@file`, or `key=-`; repeatable. \[required] - `--secret-name `: Vault secret name. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,23 +42,23 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Keep the password out of the command line by reading it from a local file. - tdc fs-vault create-secret --file-system-name workspace --secret-name db-prod --field DB_URL=mysql://example --field PASSWORD=@./password.txt + ti fs-vault create-secret --file-system-name workspace --secret-name db-prod --field DB_URL=mysql://example --field PASSWORD=@./password.txt ``` - Read a secret field from standard input: ```bash # Supply a sensitive token through a pipe instead of a process argument. - printf '%s' "$API_TOKEN" | tdc fs-vault create-secret --file-system-name workspace --secret-name api-dev --field TOKEN=- + printf '%s' "$API_TOKEN" | ti fs-vault create-secret --file-system-name workspace --secret-name api-dev --field TOKEN=- ``` - Preview secret creation: ```bash # Validate field assignments without storing secret material. - tdc fs-vault create-secret --file-system-name workspace --secret-name api-dev --field TOKEN=@./token.txt --dry-run + ti fs-vault create-secret --file-system-name workspace --secret-name api-dev --field TOKEN=@./token.txt --dry-run ``` ## Related documentation -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-grant.md similarity index 58% rename from ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md rename to ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-grant.md index 9ac3163cf99ff..041b7faea108a 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-grant.md +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-grant.md @@ -1,20 +1,20 @@ --- -title: tdc fs-vault delete-grant +title: ti fs-vault delete-grant summary: Revoke a delegated Filesystem Vault grant. --- -# tdc fs-vault delete-grant +# ti fs-vault delete-grant Revokes one delegated Filesystem Vault grant. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-vault delete-grant +ti fs-vault delete-grant --grant-id [--dry-run] [--file-system-name ] @@ -29,14 +29,14 @@ tdc fs-vault delete-grant - `--grant-id `: Vault grant ID. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--reason `: Optional revoke reason. -- `--revoked-by `: Actor label for the revoke audit entry. \[default: `tdc`] +- `--revoked-by `: Actor label for the revoke audit entry. \[default: `ti`] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -44,9 +44,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Invalidate the delegated token and record the revocation reason. - tdc fs-vault delete-grant --file-system-name workspace --grant-id "" --reason rotated + ti fs-vault delete-grant --file-system-name workspace --grant-id "" --reason rotated ``` ## Related documentation -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-secret.md similarity index 55% rename from ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md rename to ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-secret.md index af816d9a85c27..6549dac481bc3 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-delete-secret.md +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-secret.md @@ -1,20 +1,20 @@ --- -title: tdc fs-vault delete-secret +title: ti fs-vault delete-secret summary: Delete a secret from Filesystem Vault. --- -# tdc fs-vault delete-secret +# ti fs-vault delete-secret Deletes one Filesystem Vault secret. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-vault delete-secret +ti fs-vault delete-secret --secret-name [--dry-run] [--file-system-name ] @@ -27,12 +27,12 @@ tdc fs-vault delete-secret - `--secret-name `: Vault secret name. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -40,9 +40,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Remove the selected secret and its fields from the Vault. - tdc fs-vault delete-secret --file-system-name workspace --secret-name db-prod + ti fs-vault delete-secret --file-system-name workspace --secret-name db-prod ``` ## Related documentation -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-audit-events.md similarity index 60% rename from ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md rename to ai/ti/reference/commands/fs-vault/ti-fs-vault-list-audit-events.md index 22d58df25248a..d909daa1e1aed 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-audit-events.md +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-audit-events.md @@ -1,20 +1,20 @@ --- -title: tdc fs-vault list-audit-events +title: ti fs-vault list-audit-events summary: List Filesystem Vault audit events. --- -# tdc fs-vault list-audit-events +# ti fs-vault list-audit-events Lists vault audit events with optional agent, secret, and time filters. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-vault list-audit-events +ti fs-vault list-audit-events [--agent-id ] [--file-system-name ] [--fs-token ] @@ -28,15 +28,15 @@ tdc fs-vault list-audit-events ## Options - `--agent-id `: Filter by agent ID. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--limit `: Maximum events to return. \[default: 100] - `--secret-name `: Filter by Vault secret name. - `--since `: Client-side relative time filter, for example, `24h`. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -44,16 +44,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Inspect recent access and mutation events for the selected secret. - tdc fs-vault list-audit-events --file-system-name workspace --secret-name db-prod --limit 20 + ti fs-vault list-audit-events --file-system-name workspace --secret-name db-prod --limit 20 ``` - List recent events for an agent: ```bash # Filter the audit trail to one delegated identity and time range. - tdc fs-vault list-audit-events --file-system-name workspace --agent-id deploy-agent --since 24h + ti fs-vault list-audit-events --file-system-name workspace --agent-id deploy-agent --since 24h ``` ## Related documentation -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-secrets.md similarity index 51% rename from ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md rename to ai/ti/reference/commands/fs-vault/ti-fs-vault-list-secrets.md index 46ac7381cc82f..91d9979a7a103 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-list-secrets.md +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-secrets.md @@ -1,20 +1,20 @@ --- -title: tdc fs-vault list-secrets +title: ti fs-vault list-secrets summary: List secrets visible to a Filesystem Vault credential. --- -# tdc fs-vault list-secrets +# ti fs-vault list-secrets Lists secrets visible to the active owner or delegated credential. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-vault list-secrets +ti fs-vault list-secrets [--file-system-name ] [--fs-token ] [--help] @@ -24,13 +24,13 @@ tdc fs-vault list-secrets ## Options -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. -- `--vault-token `: Delegated `tdc fs-vault` token; prefer `TDC_VAULT_TOKEN`. +- `--vault-token `: Delegated `ti fs-vault` token; prefer `TI_VAULT_TOKEN`. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,16 +38,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return secret metadata without exposing field values. - tdc fs-vault list-secrets --file-system-name workspace + ti fs-vault list-secrets --file-system-name workspace ``` - List secrets visible to a delegated token: ```bash # Restrict the result to secrets within the token's granted scope. - tdc fs-vault list-secrets --file-system-name workspace --vault-token "$TDC_VAULT_TOKEN" + ti fs-vault list-secrets --file-system-name workspace --vault-token "$TI_VAULT_TOKEN" ``` ## Related documentation -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-mount-vault.md similarity index 58% rename from ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md rename to ai/ti/reference/commands/fs-vault/ti-fs-vault-mount-vault.md index dd865a22a85ff..87ccefba90c8b 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-mount-vault.md +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-mount-vault.md @@ -1,20 +1,20 @@ --- -title: tdc fs-vault mount-vault +title: ti fs-vault mount-vault summary: Mount a read-only Filesystem Vault view. --- -# tdc fs-vault mount-vault +# ti fs-vault mount-vault Mounts readable vault fields as a local read-only FUSE filesystem. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-vault mount-vault +ti fs-vault mount-vault --mount-path [--dry-run] [--file-system-name ] @@ -30,15 +30,15 @@ tdc fs-vault mount-vault - `--mount-path `: Local mount path. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. - `--foreground`: Run mount runtime in the foreground until interrupted. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--ready-timeout `: Time to wait for a background mount to become ready. \[default: `30s`] -- `--vault-token `: Delegated `tdc fs-vault` token; prefer `TDC_VAULT_TOKEN`. +- `--vault-token `: Delegated `ti fs-vault` token; prefer `TI_VAULT_TOKEN`. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -46,16 +46,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Expose only the paths allowed by the delegated Vault token. - tdc fs-vault mount-vault --file-system-name workspace --mount-path ./vault --vault-token "$TDC_VAULT_TOKEN" + ti fs-vault mount-vault --file-system-name workspace --mount-path ./vault --vault-token "$TI_VAULT_TOKEN" ``` - Run the Vault mount in the foreground: ```bash # Keep the runtime attached for containers or process supervisors. - tdc fs-vault mount-vault --file-system-name workspace --mount-path ./vault --foreground --ready-timeout 60s + ti fs-vault mount-vault --file-system-name workspace --mount-path ./vault --foreground --ready-timeout 60s ``` ## Related documentation -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-read-secret.md similarity index 56% rename from ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md rename to ai/ti/reference/commands/fs-vault/ti-fs-vault-read-secret.md index e8d0624cea925..44a7c774fee76 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-read-secret.md +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-read-secret.md @@ -1,20 +1,20 @@ --- -title: tdc fs-vault read-secret +title: ti fs-vault read-secret summary: Read a secret from Filesystem Vault. --- -# tdc fs-vault read-secret +# ti fs-vault read-secret Reads a complete secret or one field using an owner or delegated credential. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-vault read-secret +ti fs-vault read-secret --secret-name [--field ] [--file-system-name ] @@ -29,14 +29,14 @@ tdc fs-vault read-secret - `--secret-name `: Vault secret name. \[required] - `--field `: Optional field name to read. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. - `--format `: Read output format: `json`, `raw`, or `env`. \[default: json] -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. -- `--vault-token `: Delegated `tdc fs-vault` token; prefer `TDC_VAULT_TOKEN`. +- `--vault-token `: Delegated `ti fs-vault` token; prefer `TI_VAULT_TOKEN`. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -44,23 +44,23 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Write only the selected field value for direct consumption by a process. - tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field PASSWORD --format raw + ti fs-vault read-secret --file-system-name workspace --secret-name db-prod --field PASSWORD --format raw ``` - Format a field as an environment assignment: ```bash # Emit an exportable environment-variable representation of the field. - tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field DB_URL --format env + ti fs-vault read-secret --file-system-name workspace --secret-name db-prod --field DB_URL --format env ``` - Read with a delegated Vault token: ```bash # Access only the scope granted to an agent without using the owner token. - tdc fs-vault read-secret --file-system-name workspace --secret-name db-prod --field DB_URL --vault-token "$TDC_VAULT_TOKEN" --format raw + ti fs-vault read-secret --file-system-name workspace --secret-name db-prod --field DB_URL --vault-token "$TI_VAULT_TOKEN" --format raw ``` ## Related documentation -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-replace-secret.md similarity index 57% rename from ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md rename to ai/ti/reference/commands/fs-vault/ti-fs-vault-replace-secret.md index d3dfcda169e7d..bed3cd83e1e7d 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-replace-secret.md +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-replace-secret.md @@ -1,20 +1,20 @@ --- -title: tdc fs-vault replace-secret +title: ti fs-vault replace-secret summary: Replace all fields in a Filesystem Vault secret. --- -# tdc fs-vault replace-secret +# ti fs-vault replace-secret Replaces all fields in one secret from files in a local directory. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-vault replace-secret +ti fs-vault replace-secret --from-directory --secret-path [--dry-run] @@ -29,12 +29,12 @@ tdc fs-vault replace-secret - `--from-directory `: Directory whose files become secret fields. \[required] - `--secret-path `: Vault path in the form `/n/vault/`. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,16 +42,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Replace all fields with files loaded from the selected directory. - tdc fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields + ti fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields ``` - Preview secret replacement: ```bash # Validate the replacement source without changing the stored secret. - tdc fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields --dry-run + ti fs-vault replace-secret --file-system-name workspace --secret-path /n/vault/db-prod --from-directory ./secret-fields --dry-run ``` ## Related documentation -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-run-with-secret.md similarity index 54% rename from ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md rename to ai/ti/reference/commands/fs-vault/ti-fs-vault-run-with-secret.md index 13490d86a6ac2..850da0aa09339 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-run-with-secret.md +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-run-with-secret.md @@ -1,20 +1,20 @@ --- -title: tdc fs-vault run-with-secret +title: ti fs-vault run-with-secret summary: Run a process with a Filesystem Vault secret. --- -# tdc fs-vault run-with-secret +# ti fs-vault run-with-secret Runs a command with one secret injected into its environment. Arguments after `--` are passed to the child command. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-vault run-with-secret +ti fs-vault run-with-secret --secret-path [--file-system-name ] [--fs-token ] @@ -26,13 +26,13 @@ tdc fs-vault run-with-secret ## Options - `--secret-path `: Vault path in the form `/n/vault/`. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. -- `--vault-token `: Delegated `tdc fs-vault` token; prefer `TDC_VAULT_TOKEN`. +- `--vault-token `: Delegated `ti fs-vault` token; prefer `TI_VAULT_TOKEN`. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -40,16 +40,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Inject all fields into the child process environment without printing them. - tdc fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- env + ti fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- env ``` - Use an injected field in a shell command: ```bash # Verify that the child process receives DB_URL without exposing its value. - tdc fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- sh -c 'test -n "$DB_URL"' + ti fs-vault run-with-secret --file-system-name workspace --secret-path /n/vault/db-prod -- sh -c 'test -n "$DB_URL"' ``` ## Related documentation -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-unmount-vault.md similarity index 56% rename from ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md rename to ai/ti/reference/commands/fs-vault/ti-fs-vault-unmount-vault.md index 084c13be7ba36..2a90142899df0 100644 --- a/ai/tdc/reference/commands/fs-vault/tdc-fs-vault-unmount-vault.md +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-unmount-vault.md @@ -1,20 +1,20 @@ --- -title: tdc fs-vault unmount-vault +title: ti fs-vault unmount-vault summary: Unmount a Filesystem Vault view. --- -# tdc fs-vault unmount-vault +# ti fs-vault unmount-vault Unmounts a local Filesystem Vault filesystem. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs-vault unmount-vault +ti fs-vault unmount-vault --mount-path [--dry-run] [--force] @@ -30,11 +30,11 @@ tdc fs-vault unmount-vault - `--dry-run`: Validate the request without applying changes. - `--force`: Force-kill the mount process if graceful unmount times out. - `--help`: Display help information. -- `--ignore-absent`: Return success when no `tdc fs-vault` mount state exists for the path. +- `--ignore-absent`: Return success when no `ti fs-vault` mount state exists for the path. - `--timeout `: Time to wait for the mount process to exit. \[default: `30s`] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,9 +42,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Detach the local read-only Vault mount. - tdc fs-vault unmount-vault --mount-path ./vault + ti fs-vault unmount-vault --mount-path ./vault ``` ## Related documentation -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md b/ai/ti/reference/commands/fs/ti-fs-check-file-system.md similarity index 54% rename from ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md rename to ai/ti/reference/commands/fs/ti-fs-check-file-system.md index 83e6b894d5722..e5a335af60ff0 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-check-file-system.md +++ b/ai/ti/reference/commands/fs/ti-fs-check-file-system.md @@ -1,20 +1,20 @@ --- -title: tdc fs check-file-system +title: ti fs check-file-system summary: Check TiDB Cloud Filesystem connectivity. --- -# tdc fs check-file-system +# ti fs check-file-system Checks Filesystem selection, endpoint resolution, credentials, and companion access. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs check-file-system +ti fs check-file-system [--file-system-name ] [--fs-token ] [--help] @@ -23,12 +23,12 @@ tdc fs check-file-system ## Options -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -36,9 +36,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Verify that the selected token can reach and read the Filesystem root. - tdc fs check-file-system --file-system-name workspace + ti fs check-file-system --file-system-name workspace ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md b/ai/ti/reference/commands/fs/ti-fs-chmod-file.md similarity index 60% rename from ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md rename to ai/ti/reference/commands/fs/ti-fs-chmod-file.md index 5da5399eaf6da..6fc2bc9ce405d 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-chmod-file.md +++ b/ai/ti/reference/commands/fs/ti-fs-chmod-file.md @@ -1,20 +1,20 @@ --- -title: tdc fs chmod-file +title: ti fs chmod-file summary: Change file permissions in a TiDB Cloud Filesystem. --- -# tdc fs chmod-file +# ti fs chmod-file -Changes POSIX mode metadata for a remote path. The command alias is `tdc fs chmod`. +Changes POSIX mode metadata for a remote path. The command alias is `ti fs chmod`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs chmod-file +ti fs chmod-file --mode --path [--dry-run] @@ -29,12 +29,12 @@ tdc fs chmod-file - `--mode `: The permission mode as an octal value such as 0644. \[required] - `--path `: File or directory path. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,9 +42,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Restrict the selected file to owner read and write access. - tdc fs chmod-file --file-system-name workspace --path /reports/final.md --mode 0600 + ti fs chmod-file --file-system-name workspace --path /reports/final.md --mode 0600 ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md b/ai/ti/reference/commands/fs/ti-fs-commit-layer.md similarity index 56% rename from ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md rename to ai/ti/reference/commands/fs/ti-fs-commit-layer.md index 25fc65687d622..42aa6e33dda4b 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-commit-layer.md +++ b/ai/ti/reference/commands/fs/ti-fs-commit-layer.md @@ -1,20 +1,20 @@ --- -title: tdc fs commit-layer +title: ti fs commit-layer summary: Commit a TiDB Cloud Filesystem layer. --- -# tdc fs commit-layer +# ti fs commit-layer Applies one layer to its base Filesystem. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs commit-layer +ti fs commit-layer --layer-id [--dry-run] [--file-system-name ] @@ -27,12 +27,12 @@ tdc fs commit-layer - `--layer-id `: Layer ID. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -40,9 +40,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Apply the selected layer's changes to its base Filesystem view. - tdc fs commit-layer --file-system-name workspace --layer-id "" + ti fs commit-layer --file-system-name workspace --layer-id "" ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md b/ai/ti/reference/commands/fs/ti-fs-copy-file.md similarity index 67% rename from ai/tdc/reference/commands/fs/tdc-fs-copy-file.md rename to ai/ti/reference/commands/fs/ti-fs-copy-file.md index a70f1b54076fc..2c45d612a56fa 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-copy-file.md +++ b/ai/ti/reference/commands/fs/ti-fs-copy-file.md @@ -1,20 +1,20 @@ --- -title: tdc fs copy-file +title: ti fs copy-file summary: Copy files to, from, or within a TiDB Cloud Filesystem. --- -# tdc fs copy-file +# ti fs copy-file -Copies files between local paths, remote paths, stdin, and stdout. The command alias is `tdc fs cp`. +Copies files between local paths, remote paths, stdin, and stdout. The command alias is `ti fs cp`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs copy-file +ti fs copy-file [--append] [--create-parents] [--description ] @@ -42,11 +42,11 @@ tdc fs copy-file - `--create-parents`: Create missing local parent directories when copying from a TiDB Cloud file system. - `--description `: The file description for `--to-remote` operation. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. - `--from-local `: The local source path. - `--from-remote `: The source path in the TiDB Cloud file system. - `--from-stdin`: Read from stdin and write to `--to-remote`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--layer-id `: Write the copied file content into a file system layer instead of the base file system. - `--overwrite`: Replace an existing destination file. @@ -58,7 +58,7 @@ tdc fs copy-file - `--to-stdout`: Write `--from-remote` to stdout. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -66,44 +66,44 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Copy a local report into the selected remote Filesystem. - tdc fs copy-file --file-system-name workspace --from-local ./report.md --to-remote /reports/report.md + ti fs copy-file --file-system-name workspace --from-local ./report.md --to-remote /reports/report.md ``` - Download a remote file: ```bash # Create missing local parent directories while downloading the file. - tdc fs copy-file --file-system-name workspace --from-remote /reports/report.md --to-local ./downloads/report.md --create-parents + ti fs copy-file --file-system-name workspace --from-remote /reports/report.md --to-local ./downloads/report.md --create-parents ``` - Copy a remote directory: ```bash # Duplicate a complete directory tree without downloading it locally. - tdc fs copy-file --file-system-name workspace --from-remote /reports --to-remote /archive/reports --recursive + ti fs copy-file --file-system-name workspace --from-remote /reports --to-remote /archive/reports --recursive ``` - Resume a large upload: ```bash # Continue an interrupted local-to-remote transfer instead of restarting it. - tdc fs copy-file --file-system-name workspace --from-local ./large.bin --to-remote /artifacts/large.bin --resume + ti fs copy-file --file-system-name workspace --from-local ./large.bin --to-remote /artifacts/large.bin --resume ``` - Append to a remote log: ```bash # Add local log data to the existing remote object efficiently. - tdc fs copy-file --file-system-name workspace --from-local ./tail.log --to-remote /logs/app.log --append + ti fs copy-file --file-system-name workspace --from-local ./tail.log --to-remote /logs/app.log --append ``` - Stream standard input to the Filesystem: ```bash # Upload generated content without creating an intermediate local file. - printf 'ready\n' | tdc fs copy-file --file-system-name workspace --from-stdin --to-remote /status.txt --tag source=stdin --description "generated status" + printf 'ready\n' | ti fs copy-file --file-system-name workspace --from-stdin --to-remote /status.txt --tag source=stdin --description "generated status" ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md b/ai/ti/reference/commands/fs/ti-fs-create-directory.md similarity index 56% rename from ai/tdc/reference/commands/fs/tdc-fs-create-directory.md rename to ai/ti/reference/commands/fs/ti-fs-create-directory.md index 8d244602b2c82..aa7b9f84140dd 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-directory.md +++ b/ai/ti/reference/commands/fs/ti-fs-create-directory.md @@ -1,20 +1,20 @@ --- -title: tdc fs create-directory +title: ti fs create-directory summary: Create a directory in a TiDB Cloud Filesystem. --- -# tdc fs create-directory +# ti fs create-directory -Creates a remote directory. The command alias is `tdc fs mkdir`. +Creates a remote directory. The command alias is `ti fs mkdir`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs create-directory +ti fs create-directory --path [--dry-run] [--file-system-name ] @@ -28,13 +28,13 @@ tdc fs create-directory - `--path `: The file system path of the directory to create. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--mode `: The directory mode as an octal value such as 0755. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,9 +42,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Create the directory with explicit POSIX permission metadata. - tdc fs create-directory --file-system-name workspace --path /reports/archive --mode 0755 + ti fs create-directory --file-system-name workspace --path /reports/archive --mode 0755 ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md b/ai/ti/reference/commands/fs/ti-fs-create-file-system.md similarity index 61% rename from ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md rename to ai/ti/reference/commands/fs/ti-fs-create-file-system.md index 359e882eaf35b..03921ad4fb8e0 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-file-system.md +++ b/ai/ti/reference/commands/fs/ti-fs-create-file-system.md @@ -1,20 +1,20 @@ --- -title: tdc fs create-file-system +title: ti fs create-file-system summary: Create a TiDB Cloud Filesystem. --- -# tdc fs create-file-system +# ti fs create-file-system Creates a Filesystem. `--wait` waits until data-plane access is ready. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs create-file-system +ti fs create-file-system --file-system-name [--dry-run] [--help] @@ -30,7 +30,7 @@ tdc fs create-file-system - `--version`: Display version information. - `--wait`: Wait until the created file system is active. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,23 +38,23 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Wait until the new Filesystem root is readable before returning. - tdc fs create-file-system --file-system-name workspace --wait + ti fs create-file-system --file-system-name workspace --wait ``` - Create a Filesystem asynchronously: ```bash # Return after provisioning is accepted so work can continue in parallel. - tdc fs create-file-system --file-system-name scratch + ti fs create-file-system --file-system-name scratch ``` - Preview Filesystem creation: ```bash # Validate credentials, placement, and the request without provisioning storage. - tdc fs create-file-system --file-system-name workspace --dry-run + ti fs create-file-system --file-system-name workspace --dry-run ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md b/ai/ti/reference/commands/fs/ti-fs-create-hardlink.md similarity index 59% rename from ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md rename to ai/ti/reference/commands/fs/ti-fs-create-hardlink.md index 02ea2cd74127d..f05f25e215ff8 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-hardlink.md +++ b/ai/ti/reference/commands/fs/ti-fs-create-hardlink.md @@ -1,20 +1,20 @@ --- -title: tdc fs create-hardlink +title: ti fs create-hardlink summary: Create a hard link in a TiDB Cloud Filesystem. --- -# tdc fs create-hardlink +# ti fs create-hardlink -Creates a hard link to an existing remote path. The command alias is `tdc fs hardlink`. +Creates a hard link to an existing remote path. The command alias is `ti fs hardlink`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs create-hardlink +ti fs create-hardlink --link-path --source-path [--dry-run] @@ -29,12 +29,12 @@ tdc fs create-hardlink - `--link-path `: The file path for the hard link being created in the TiDB Cloud file system. \[required] - `--source-path `: The existing file path in the TiDB Cloud file system. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,9 +42,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Expose the same remote file content at a second path. - tdc fs create-hardlink --file-system-name workspace --source-path /reports/final.md --link-path /reports/final-copy.md + ti fs create-hardlink --file-system-name workspace --source-path /reports/final.md --link-path /reports/final-copy.md ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md b/ai/ti/reference/commands/fs/ti-fs-create-layer-checkpoint.md similarity index 61% rename from ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md rename to ai/ti/reference/commands/fs/ti-fs-create-layer-checkpoint.md index afc1543538f5b..2cc1c47f3eeee 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-layer-checkpoint.md +++ b/ai/ti/reference/commands/fs/ti-fs-create-layer-checkpoint.md @@ -1,20 +1,20 @@ --- -title: tdc fs create-layer-checkpoint +title: ti fs create-layer-checkpoint summary: Create a checkpoint in a TiDB Cloud Filesystem layer. --- -# tdc fs create-layer-checkpoint +# ti fs create-layer-checkpoint Creates a checkpoint in one layer. If `--checkpoint-id` is omitted, the service generates one. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs create-layer-checkpoint +ti fs create-layer-checkpoint --layer-id [--checkpoint-id ] [--dry-run] @@ -30,13 +30,13 @@ tdc fs create-layer-checkpoint - `--layer-id `: The layer ID identifying the layer. \[required] - `--checkpoint-id `: Checkpoint ID. Normally it is generated by the service automatically. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--label `: The checkpoint label. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -44,16 +44,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Record the current layer state under a stable checkpoint ID. - tdc fs create-layer-checkpoint --file-system-name workspace --layer-id "" --checkpoint-id before-review + ti fs create-layer-checkpoint --file-system-name workspace --layer-id "" --checkpoint-id before-review ``` - Create an automatically identified checkpoint: ```bash # Let the service assign the checkpoint ID while retaining a human label. - tdc fs create-layer-checkpoint --file-system-name workspace --layer-id "" --label "before review" + ti fs create-layer-checkpoint --file-system-name workspace --layer-id "" --label "before review" ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md b/ai/ti/reference/commands/fs/ti-fs-create-layer.md similarity index 67% rename from ai/tdc/reference/commands/fs/tdc-fs-create-layer.md rename to ai/ti/reference/commands/fs/ti-fs-create-layer.md index 45385251806f1..20abc26d9919f 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-layer.md +++ b/ai/ti/reference/commands/fs/ti-fs-create-layer.md @@ -1,20 +1,20 @@ --- -title: tdc fs create-layer +title: ti fs create-layer summary: Create a layer in a TiDB Cloud Filesystem. --- -# tdc fs create-layer +# ti fs create-layer Creates an isolated change layer over a base root. If `--layer-id` is omitted, the service generates one. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs create-layer +ti fs create-layer --base-root-path [--actor-id ] [--dry-run] @@ -34,15 +34,15 @@ tdc fs create-layer - `--actor-id `: Actor ID identifying the layer owner (for example, the agent name). - `--dry-run`: Validate the request without applying changes. - `--durability-mode `: Layer durability mode; must be `restore-safe`. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--layer-id `: The layer ID. Normally it is generated by the service automatically. - `--layer-name `: The name of the layer. - `--tag `: Tags for the layer, `key=value`; repeatable. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -50,16 +50,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Start an isolated writable view over the selected base root. - tdc fs create-layer --file-system-name workspace --base-root-path /workspace --layer-name agent-task + ti fs create-layer --file-system-name workspace --base-root-path /workspace --layer-name agent-task ``` - Create a restore-safe tagged layer: ```bash # Request durable layer behavior and attach task metadata. - tdc fs create-layer --file-system-name workspace --base-root-path /workspace --durability-mode restore-safe --tag task=review + ti fs create-layer --file-system-name workspace --base-root-path /workspace --durability-mode restore-safe --tag task=review ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md b/ai/ti/reference/commands/fs/ti-fs-create-symlink.md similarity index 56% rename from ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md rename to ai/ti/reference/commands/fs/ti-fs-create-symlink.md index 6b90ce9baa74a..8e6dd4c2b675b 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-create-symlink.md +++ b/ai/ti/reference/commands/fs/ti-fs-create-symlink.md @@ -1,20 +1,20 @@ --- -title: tdc fs create-symlink +title: ti fs create-symlink summary: Create a symbolic link in a TiDB Cloud Filesystem. --- -# tdc fs create-symlink +# ti fs create-symlink -Creates a symbolic link. The command alias is `tdc fs symlink`. +Creates a symbolic link. The command alias is `ti fs symlink`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs create-symlink +ti fs create-symlink --link-path --target [--dry-run] @@ -29,12 +29,12 @@ tdc fs create-symlink - `--link-path `: The file path for the created symbolic link. \[required] - `--target `: The actual file path being linked to. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,9 +42,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Create a relative symbolic link inside the remote namespace. - tdc fs create-symlink --file-system-name workspace --target final.md --link-path /reports/latest.md + ti fs create-symlink --file-system-name workspace --target final.md --link-path /reports/latest.md ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md b/ai/ti/reference/commands/fs/ti-fs-delete-file-system.md similarity index 59% rename from ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md rename to ai/ti/reference/commands/fs/ti-fs-delete-file-system.md index efb8b565611db..39d7dc4face47 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-delete-file-system.md +++ b/ai/ti/reference/commands/fs/ti-fs-delete-file-system.md @@ -1,20 +1,20 @@ --- -title: tdc fs delete-file-system +title: ti fs delete-file-system summary: Delete a TiDB Cloud Filesystem. --- -# tdc fs delete-file-system +# ti fs delete-file-system Requests asynchronous Filesystem deletion and removes its local registration. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs delete-file-system +ti fs delete-file-system --file-system-name [--dry-run] [--fs-token ] @@ -26,11 +26,11 @@ tdc fs delete-file-system - `--file-system-name `: Set the file system name. \[required] - `--dry-run`: Validate the request without applying changes. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,16 +38,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Request asynchronous deletion and remove its local registration after acceptance. - tdc fs delete-file-system --file-system-name workspace + ti fs delete-file-system --file-system-name workspace ``` - Preview Filesystem deletion: ```bash # Validate the selected Filesystem without sending the deletion request. - tdc fs delete-file-system --file-system-name workspace --dry-run + ti fs delete-file-system --file-system-name workspace --dry-run ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md b/ai/ti/reference/commands/fs/ti-fs-delete-file.md similarity index 56% rename from ai/tdc/reference/commands/fs/tdc-fs-delete-file.md rename to ai/ti/reference/commands/fs/ti-fs-delete-file.md index 6c09dbd797fb6..8a3c53d8ddaf2 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-delete-file.md +++ b/ai/ti/reference/commands/fs/ti-fs-delete-file.md @@ -1,20 +1,20 @@ --- -title: tdc fs delete-file +title: ti fs delete-file summary: Delete a file from a TiDB Cloud Filesystem. --- -# tdc fs delete-file +# ti fs delete-file -Deletes a remote file or directory. The command alias is `tdc fs rm`. +Deletes a remote file or directory. The command alias is `ti fs rm`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs delete-file +ti fs delete-file --path [--dry-run] [--file-system-name ] @@ -28,13 +28,13 @@ tdc fs delete-file - `--path `: File or directory path in the TiDB Cloud file system. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--recursive`: Delete a directory recursively. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,16 +42,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Remove one object from the selected Filesystem. - tdc fs delete-file --file-system-name workspace --path /reports/obsolete.md + ti fs delete-file --file-system-name workspace --path /reports/obsolete.md ``` - Delete a directory recursively: ```bash # Remove a directory and all of its descendants in one request. - tdc fs delete-file --file-system-name workspace --path /scratch --recursive + ti fs delete-file --file-system-name workspace --path /scratch --recursive ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md b/ai/ti/reference/commands/fs/ti-fs-describe-file-system.md similarity index 51% rename from ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md rename to ai/ti/reference/commands/fs/ti-fs-describe-file-system.md index daeef296b67c8..3645b78bc99de 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-file-system.md +++ b/ai/ti/reference/commands/fs/ti-fs-describe-file-system.md @@ -1,20 +1,20 @@ --- -title: tdc fs describe-file-system +title: ti fs describe-file-system summary: Describe a locally registered TiDB Cloud Filesystem. --- -# tdc fs describe-file-system +# ti fs describe-file-system Describes one locally registered Filesystem. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs describe-file-system +ti fs describe-file-system --file-system-name [--help] [--version] @@ -26,7 +26,7 @@ tdc fs describe-file-system - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -34,9 +34,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return registration, endpoint, and region details for one Filesystem. - tdc fs describe-file-system --file-system-name workspace + ti fs describe-file-system --file-system-name workspace ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md b/ai/ti/reference/commands/fs/ti-fs-describe-file.md similarity index 50% rename from ai/tdc/reference/commands/fs/tdc-fs-describe-file.md rename to ai/ti/reference/commands/fs/ti-fs-describe-file.md index e9b2b59a04547..f91165c1954a9 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-file.md +++ b/ai/ti/reference/commands/fs/ti-fs-describe-file.md @@ -1,20 +1,20 @@ --- -title: tdc fs describe-file +title: ti fs describe-file summary: Describe a file in a TiDB Cloud Filesystem. --- -# tdc fs describe-file +# ti fs describe-file -Describes metadata for one remote path. The command alias is `tdc fs stat`. +Describes metadata for one remote path. The command alias is `ti fs stat`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs describe-file +ti fs describe-file --path [--file-system-name ] [--fs-token ] @@ -25,12 +25,12 @@ tdc fs describe-file ## Options - `--path `: File or directory path in the TiDB Cloud file system. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,9 +38,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Inspect file size, metadata, tags, and revision information. - tdc fs describe-file --file-system-name workspace --path /reports/report.md + ti fs describe-file --file-system-name workspace --path /reports/report.md ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md b/ai/ti/reference/commands/fs/ti-fs-describe-layer.md similarity index 54% rename from ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md rename to ai/ti/reference/commands/fs/ti-fs-describe-layer.md index 262d717e21959..f4668bd4f5db4 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-describe-layer.md +++ b/ai/ti/reference/commands/fs/ti-fs-describe-layer.md @@ -1,20 +1,20 @@ --- -title: tdc fs describe-layer +title: ti fs describe-layer summary: Describe a layer in a TiDB Cloud Filesystem. --- -# tdc fs describe-layer +# ti fs describe-layer Describes one Filesystem layer. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs describe-layer +ti fs describe-layer --layer-id [--file-system-name ] [--fs-token ] @@ -25,12 +25,12 @@ tdc fs describe-layer ## Options - `--layer-id `: The ID of the specified file system layer. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,9 +38,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Inspect one layer's base root, state, durability, and metadata. - tdc fs describe-layer --file-system-name workspace --layer-id "" + ti fs describe-layer --file-system-name workspace --layer-id "" ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md b/ai/ti/reference/commands/fs/ti-fs-diff-layer.md similarity index 59% rename from ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md rename to ai/ti/reference/commands/fs/ti-fs-diff-layer.md index 627fb2f0c0087..80c3b156c44fe 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-diff-layer.md +++ b/ai/ti/reference/commands/fs/ti-fs-diff-layer.md @@ -1,20 +1,20 @@ --- -title: tdc fs diff-layer +title: ti fs diff-layer summary: Show changes in a TiDB Cloud Filesystem layer. --- -# tdc fs diff-layer +# ti fs diff-layer Lists changes in one layer, optionally up to a sequence number. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs diff-layer +ti fs diff-layer --layer-id [--file-system-name ] [--fs-token ] @@ -26,13 +26,13 @@ tdc fs diff-layer ## Options - `--layer-id `: The ID of the layer. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--max-seq `: The highest layer sequence to include; 0 includes all layers. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -40,16 +40,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return the complete ordered change set for the selected layer. - tdc fs diff-layer --file-system-name workspace --layer-id "" + ti fs diff-layer --file-system-name workspace --layer-id "" ``` - Show an earlier layer view: ```bash # Limit the diff to changes at or before a sequence number. - tdc fs diff-layer --file-system-name workspace --layer-id "" --max-seq 100 + ti fs diff-layer --file-system-name workspace --layer-id "" --max-seq 100 ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md b/ai/ti/reference/commands/fs/ti-fs-drain-file-system.md similarity index 57% rename from ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md rename to ai/ti/reference/commands/fs/ti-fs-drain-file-system.md index 94579e475b812..9e9de63e201ab 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-drain-file-system.md +++ b/ai/ti/reference/commands/fs/ti-fs-drain-file-system.md @@ -1,20 +1,20 @@ --- -title: tdc fs drain-file-system +title: ti fs drain-file-system summary: Drain a mounted TiDB Cloud Filesystem. --- -# tdc fs drain-file-system +# ti fs drain-file-system -Flushes dirty FUSE state while leaving the mount online. The command alias is `tdc fs drain`. +Flushes dirty FUSE state while leaving the mount online. The command alias is `ti fs drain`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs drain-file-system +ti fs drain-file-system --mount-path [--dry-run] [--help] @@ -30,7 +30,7 @@ tdc fs drain-file-system - `--timeout `: The time to wait for dirty handles and pending writes to drain. \[default: `30s`] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,9 +38,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Flush queued FUSE writes while leaving the Filesystem mounted. - tdc fs drain-file-system --mount-path /path/to/workspace --timeout 30s + ti fs drain-file-system --mount-path /path/to/workspace --timeout 30s ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-find-files.md b/ai/ti/reference/commands/fs/ti-fs-find-files.md similarity index 69% rename from ai/tdc/reference/commands/fs/tdc-fs-find-files.md rename to ai/ti/reference/commands/fs/ti-fs-find-files.md index 9703d2219fb54..bee226ace70bb 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-find-files.md +++ b/ai/ti/reference/commands/fs/ti-fs-find-files.md @@ -1,20 +1,20 @@ --- -title: tdc fs find-files +title: ti fs find-files summary: Find files in a TiDB Cloud Filesystem. --- -# tdc fs find-files +# ti fs find-files -Finds remote paths by name, type, tag, size, or modification time. The command alias is `tdc fs find`. +Finds remote paths by name, type, tag, size, or modification time. The command alias is `ti fs find`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs find-files +ti fs find-files [--file-name-pattern ] [--file-system-name ] [--fs-token ] @@ -34,8 +34,8 @@ tdc fs find-files ## Options - `--file-name-pattern `: File name pattern filter, such as `*.md`. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--layer-id `: Search files and directories within a specific file system layer. - `--limit `: Maximum number of results; 0 uses the service default. @@ -48,7 +48,7 @@ tdc fs find-files - `--tag `: Tag filter. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -56,16 +56,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Locate Markdown files recursively under the selected remote path. - tdc fs find-files --file-system-name workspace --path /workspace --file-name-pattern "*.md" + ti fs find-files --file-system-name workspace --path /workspace --file-name-pattern "*.md" ``` - Find files by metadata: ```bash # Select tagged files that also meet a minimum size threshold. - tdc fs find-files --file-system-name workspace --path /workspace --tag stage=review --min-size-bytes 1024 + ti fs find-files --file-system-name workspace --path /workspace --tag stage=review --min-size-bytes 1024 ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-list-file-systems.md b/ai/ti/reference/commands/fs/ti-fs-list-file-systems.md new file mode 100644 index 0000000000000..311b388f55009 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-list-file-systems.md @@ -0,0 +1,40 @@ +--- +title: ti fs list-file-systems +summary: List locally registered TiDB Cloud Filesystems. +--- + +# ti fs list-file-systems + +Lists Filesystems registered in the selected local profile. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs list-file-systems + [--help] + [--version] +``` + +## Options + +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- List locally registered Filesystems: + + ```bash + # Return the Filesystems registered under the selected local profile. + ti fs list-file-systems + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-files.md b/ai/ti/reference/commands/fs/ti-fs-list-files.md similarity index 50% rename from ai/tdc/reference/commands/fs/tdc-fs-list-files.md rename to ai/ti/reference/commands/fs/ti-fs-list-files.md index 8d290b8cd1427..5fc73ab6c10c1 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-files.md +++ b/ai/ti/reference/commands/fs/ti-fs-list-files.md @@ -1,20 +1,20 @@ --- -title: tdc fs list-files +title: ti fs list-files summary: List files in a TiDB Cloud Filesystem. --- -# tdc fs list-files +# ti fs list-files -Lists entries below a remote path. The command alias is `tdc fs ls`. +Lists entries below a remote path. The command alias is `ti fs ls`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs list-files +ti fs list-files [--file-system-name ] [--fs-token ] [--help] @@ -24,13 +24,13 @@ tdc fs list-files ## Options -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--path `: File system directory path. \[default: /] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -38,9 +38,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return the entries under a specific Filesystem path. - tdc fs list-files --file-system-name workspace --path /reports + ti fs list-files --file-system-name workspace --path /reports ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md b/ai/ti/reference/commands/fs/ti-fs-list-layers.md similarity index 52% rename from ai/tdc/reference/commands/fs/tdc-fs-list-layers.md rename to ai/ti/reference/commands/fs/ti-fs-list-layers.md index 5a95b8f19b9f8..8253ee3fe86e7 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-list-layers.md +++ b/ai/ti/reference/commands/fs/ti-fs-list-layers.md @@ -1,20 +1,20 @@ --- -title: tdc fs list-layers +title: ti fs list-layers summary: List layers in a TiDB Cloud Filesystem. --- -# tdc fs list-layers +# ti fs list-layers Lists layers for the selected Filesystem. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs list-layers +ti fs list-layers [--file-system-name ] [--fs-token ] [--help] @@ -23,12 +23,12 @@ tdc fs list-layers ## Options -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -36,9 +36,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return all layers available in the selected Filesystem. - tdc fs list-layers --file-system-name workspace + ti fs list-layers --file-system-name workspace ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md b/ai/ti/reference/commands/fs/ti-fs-mount-file-system.md similarity index 72% rename from ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md rename to ai/ti/reference/commands/fs/ti-fs-mount-file-system.md index 01cc0123e5019..a4a1a48fd510c 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-mount-file-system.md +++ b/ai/ti/reference/commands/fs/ti-fs-mount-file-system.md @@ -1,20 +1,20 @@ --- -title: tdc fs mount-file-system +title: ti fs mount-file-system summary: Mount a TiDB Cloud Filesystem. --- -# tdc fs mount-file-system +# ti fs mount-file-system -Mounts a Filesystem through automatic, FUSE, or WebDAV mode. The command alias is `tdc fs mount`. +Mounts a Filesystem through automatic, FUSE, or WebDAV mode. The command alias is `ti fs mount`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs mount-file-system +ti fs mount-file-system --mount-path [--cache-dir ] [--driver ] @@ -41,14 +41,14 @@ tdc fs mount-file-system ## Options - `--mount-path `: Local mount path. \[required] -- `--cache-dir `: Local FUSE cache directory. If omitted, uses `~/.tdc/cache/mounts/`. +- `--cache-dir `: Local FUSE cache directory. If omitted, uses `~/.ti/cache/mounts/`. - `--driver `: Mount driver: `auto`, `fuse`, or `webdav`. \[default: auto] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. - `--foreground`: Run the mount runtime in the foreground until interrupted. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. -- `--local-root `: Local overlay root. If omitted, uses `~/.tdc/local/fs/`. +- `--local-root `: Local overlay root. If omitted, uses `~/.ti/local/fs/`. - `--mount-profile `: Mount profile: `coding-agent`, `portable`, or `none`. If omitted, uses `none`. - `--no-auto-unpack`: Skip default auto-unpack for portable mount profile before mounting. - `--pack-path `: Local overlay path included by automatic or manual pack. Repeatable. @@ -62,7 +62,7 @@ tdc fs mount-file-system - `--version`: Display version information. - `--write-back-cache`: Persist FUSE writes locally before writing them to the file system on flush. \[default: true] -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -70,30 +70,30 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Let the CLI select the default driver for the current platform. - tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace + ti fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace ``` - Create a read-only FUSE mount: ```bash # Expose the remote namespace through FUSE without permitting writes. - tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver fuse --read-only + ti fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver fuse --read-only ``` - Use WebDAV on macOS without macFUSE: ```bash # Select WebDAV explicitly when a FUSE runtime is unavailable. - tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver webdav + ti fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver webdav ``` - Tune the FUSE read cache: ```bash # Increase cache capacity for repeated reads of medium-sized files. - tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver fuse --read-cache-size-mb 256 --read-cache-max-file-mb 16 + ti fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace --driver fuse --read-cache-size-mb 256 --read-cache-max-file-mb 16 ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-move-file.md b/ai/ti/reference/commands/fs/ti-fs-move-file.md similarity index 57% rename from ai/tdc/reference/commands/fs/tdc-fs-move-file.md rename to ai/ti/reference/commands/fs/ti-fs-move-file.md index 94c21215331a3..9d181938347cf 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-move-file.md +++ b/ai/ti/reference/commands/fs/ti-fs-move-file.md @@ -1,20 +1,20 @@ --- -title: tdc fs move-file +title: ti fs move-file summary: Move a file in a TiDB Cloud Filesystem. --- -# tdc fs move-file +# ti fs move-file -Moves or renames a remote path. The command alias is `tdc fs mv`. +Moves or renames a remote path. The command alias is `ti fs mv`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs move-file +ti fs move-file --from-remote --to-remote [--dry-run] @@ -30,13 +30,13 @@ tdc fs move-file - `--from-remote `: Source file path. \[required] - `--to-remote `: Destination file path. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--overwrite`: Replace an existing destination file. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -44,9 +44,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Rename or relocate an object entirely within the selected Filesystem. - tdc fs move-file --file-system-name workspace --from-remote /draft.md --to-remote /reports/final.md + ti fs move-file --file-system-name workspace --from-remote /draft.md --to-remote /reports/final.md ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md b/ai/ti/reference/commands/fs/ti-fs-pack-file-system.md similarity index 66% rename from ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md rename to ai/ti/reference/commands/fs/ti-fs-pack-file-system.md index 569e2af464f7d..8d8cc7c36278d 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-pack-file-system.md +++ b/ai/ti/reference/commands/fs/ti-fs-pack-file-system.md @@ -1,20 +1,20 @@ --- -title: tdc fs pack-file-system +title: ti fs pack-file-system summary: Pack local Filesystem overlay state. --- -# tdc fs pack-file-system +# ti fs pack-file-system Packs selected local overlay state into a remote archive. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs pack-file-system +ti fs pack-file-system [--archive-path ] [--dry-run] [--file-system-name ] @@ -32,8 +32,8 @@ tdc fs pack-file-system - `--archive-path `: The path for the packed archive. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--local-root `: Local overlay root containing the overlay directory. - `--mount-path `: The local mounted path. @@ -42,7 +42,7 @@ tdc fs pack-file-system - `--remote-root `: The TiDB Cloud file system root represented by the local overlay. \[default: /] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -50,16 +50,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Persist the local overlay associated with an existing mount. - tdc fs pack-file-system --file-system-name workspace --mount-path /path/to/workspace + ti fs pack-file-system --file-system-name workspace --mount-path /path/to/workspace ``` - Pack explicit roots: ```bash # Create a portable archive from selected local and remote roots. - tdc fs pack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable + ti fs pack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-read-file.md b/ai/ti/reference/commands/fs/ti-fs-read-file.md similarity index 59% rename from ai/tdc/reference/commands/fs/tdc-fs-read-file.md rename to ai/ti/reference/commands/fs/ti-fs-read-file.md index e8acff4f9b9a4..08510f9049e70 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-read-file.md +++ b/ai/ti/reference/commands/fs/ti-fs-read-file.md @@ -1,20 +1,20 @@ --- -title: tdc fs read-file +title: ti fs read-file summary: Read a file from a TiDB Cloud Filesystem. --- -# tdc fs read-file +# ti fs read-file -Writes a remote file or byte range to stdout. The command alias is `tdc fs cat`. +Writes a remote file or byte range to stdout. The command alias is `ti fs cat`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs read-file +ti fs read-file --path [--file-system-name ] [--fs-token ] @@ -27,14 +27,14 @@ tdc fs read-file ## Options - `--path `: File path in the selected file system. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--length `: Byte length for a ranged read. - `--offset `: Zero-based byte offset for a ranged read. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -42,16 +42,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Write the remote file contents directly to standard output. - tdc fs read-file --file-system-name workspace --path /reports/report.md + ti fs read-file --file-system-name workspace --path /reports/report.md ``` - Read a byte range: ```bash # Fetch only the requested range from a large remote object. - tdc fs read-file --file-system-name workspace --path /archives/large.bin --offset 1024 --length 4096 + ti fs read-file --file-system-name workspace --path /archives/large.bin --offset 1024 --length 4096 ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md b/ai/ti/reference/commands/fs/ti-fs-rollback-layer.md similarity index 57% rename from ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md rename to ai/ti/reference/commands/fs/ti-fs-rollback-layer.md index 9d13958f844ba..2cedf84692dc5 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-rollback-layer.md +++ b/ai/ti/reference/commands/fs/ti-fs-rollback-layer.md @@ -1,20 +1,20 @@ --- -title: tdc fs rollback-layer +title: ti fs rollback-layer summary: Roll back a TiDB Cloud Filesystem layer. --- -# tdc fs rollback-layer +# ti fs rollback-layer Rolls back changes in one layer without committing them to the base. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs rollback-layer +ti fs rollback-layer --layer-id [--dry-run] [--file-system-name ] @@ -27,12 +27,12 @@ tdc fs rollback-layer - `--layer-id `: The ID of the layer. \[required] - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -40,9 +40,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Discard uncommitted changes and restore the layer's base view. - tdc fs rollback-layer --file-system-name workspace --layer-id "" + ti fs rollback-layer --file-system-name workspace --layer-id "" ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md b/ai/ti/reference/commands/fs/ti-fs-search-file-content.md similarity index 60% rename from ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md rename to ai/ti/reference/commands/fs/ti-fs-search-file-content.md index 8c505137fa4b9..3687db9e6f0c9 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-search-file-content.md +++ b/ai/ti/reference/commands/fs/ti-fs-search-file-content.md @@ -1,20 +1,20 @@ --- -title: tdc fs search-file-content +title: ti fs search-file-content summary: Search file content in a TiDB Cloud Filesystem. --- -# tdc fs search-file-content +# ti fs search-file-content -Searches remote file content, optionally in a layer. The command alias is `tdc fs grep`. +Searches remote file content, optionally in a layer. The command alias is `ti fs grep`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs search-file-content +ti fs search-file-content --pattern [--file-system-name ] [--fs-token ] @@ -28,15 +28,15 @@ tdc fs search-file-content ## Options - `--pattern `: Content search matching pattern. \[required] -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--layer-id `: Search within a file system layer. - `--limit `: Maximum number of search results; 0 uses the service default. - `--path `: File path prefix to be searched. \[default: /] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -44,16 +44,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Find matching text under a remote directory and limit the result count. - tdc fs search-file-content --file-system-name workspace --path /workspace --pattern "TODO" --limit 50 + ti fs search-file-content --file-system-name workspace --path /workspace --pattern "TODO" --limit 50 ``` - Search content in a layer: ```bash # Inspect uncommitted layer content separately from the base Filesystem. - tdc fs search-file-content --file-system-name workspace --path /workspace --pattern "deprecated" --layer-id "" + ti fs search-file-content --file-system-name workspace --path /workspace --pattern "deprecated" --layer-id "" ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md b/ai/ti/reference/commands/fs/ti-fs-unmount-file-system.md similarity index 67% rename from ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md rename to ai/ti/reference/commands/fs/ti-fs-unmount-file-system.md index 93c815c81ab54..7e7c47db5b856 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-unmount-file-system.md +++ b/ai/ti/reference/commands/fs/ti-fs-unmount-file-system.md @@ -1,20 +1,20 @@ --- -title: tdc fs unmount-file-system +title: ti fs unmount-file-system summary: Unmount a TiDB Cloud Filesystem. --- -# tdc fs unmount-file-system +# ti fs unmount-file-system -Gracefully flushes and unmounts a background mount. The command alias is `tdc fs umount`. +Gracefully flushes and unmounts a background mount. The command alias is `ti fs umount`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs unmount-file-system +ti fs unmount-file-system --mount-path [--dry-run] [--force] @@ -38,7 +38,7 @@ tdc fs unmount-file-system - `--timeout `: Time to wait for the mount process to exit. \[default: `30s`] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -46,9 +46,9 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Gracefully flush pending writes and detach the Filesystem mount. - tdc fs unmount-file-system --mount-path /path/to/workspace + ti fs unmount-file-system --mount-path /path/to/workspace ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md b/ai/ti/reference/commands/fs/ti-fs-unpack-file-system.md similarity index 66% rename from ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md rename to ai/ti/reference/commands/fs/ti-fs-unpack-file-system.md index bd838718c79b9..72987a6a964f8 100644 --- a/ai/tdc/reference/commands/fs/tdc-fs-unpack-file-system.md +++ b/ai/ti/reference/commands/fs/ti-fs-unpack-file-system.md @@ -1,20 +1,20 @@ --- -title: tdc fs unpack-file-system +title: ti fs unpack-file-system summary: Restore local Filesystem overlay state. --- -# tdc fs unpack-file-system +# ti fs unpack-file-system Restores local overlay state from a remote archive. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc fs unpack-file-system +ti fs unpack-file-system [--archive-path ] [--dry-run] [--file-system-name ] @@ -32,8 +32,8 @@ tdc fs unpack-file-system - `--archive-path `: The path for the packed archive. - `--dry-run`: Validate the request without applying changes. -- `--file-system-name `: Select the file system. You can also set `TDC_FS_FILE_SYSTEM_NAME`. -- `--fs-token `: Set the file system user token. If omitted, uses `TDC_FS_TOKEN`. +- `--file-system-name `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_NAME`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. - `--help`: Display help information. - `--local-root `: The local overlay root to restore into. - `--mount-path `: The local mounted path. @@ -42,7 +42,7 @@ tdc fs unpack-file-system - `--remote-root `: Find the packed archive under the specified root path when `--archive-path` is omitted. \[default: /] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -50,16 +50,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Restore the portable archive associated with an existing mount. - tdc fs unpack-file-system --file-system-name workspace --mount-path /path/to/workspace + ti fs unpack-file-system --file-system-name workspace --mount-path /path/to/workspace ``` - Unpack explicit roots without replacement: ```bash # Restore missing files while preserving existing destination entries. - tdc fs unpack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable --no-replace + ti fs unpack-file-system --file-system-name workspace --local-root ./overlay --remote-root /workspace --mount-profile portable --no-replace ``` ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md b/ai/ti/reference/commands/organization/ti-organization-list-projects.md similarity index 57% rename from ai/tdc/reference/commands/organization/tdc-organization-list-projects.md rename to ai/ti/reference/commands/organization/ti-organization-list-projects.md index 42f6a371eb5ca..4aae855fb0223 100644 --- a/ai/tdc/reference/commands/organization/tdc-organization-list-projects.md +++ b/ai/ti/reference/commands/organization/ti-organization-list-projects.md @@ -1,20 +1,20 @@ --- -title: tdc organization list-projects +title: ti organization list-projects summary: List TiDB Cloud projects accessible to the configured API key. --- -# tdc organization list-projects +# ti organization list-projects Lists projects accessible to the configured TiDB Cloud API key, with optional pagination. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc organization list-projects +ti organization list-projects [--help] [--page-size ] [--page-token ] @@ -28,7 +28,7 @@ tdc organization list-projects - `--page-token `: Page token returned by a previous list-projects call. - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -36,16 +36,16 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Return the TiDB Cloud projects available to the configured API key. - tdc organization list-projects --page-size 50 + ti organization list-projects --page-size 50 ``` - Select the virtual project ID: ```bash # Use a JMESPath query to return only virtual project IDs. - tdc organization list-projects --query 'projects[?type == `tidbx_virtual`].id' --output text + ti organization list-projects --query 'projects[?type == `tidbx_virtual`].id' --output text ``` ## Related documentation -- [TiDB Cloud Organization CLI Command Reference](/ai/tdc/reference/tdc-organization.md) +- [TiDB Cloud Organization CLI Command Reference](/ai/ti/reference/ti-organization.md) diff --git a/ai/ti/reference/commands/ti/ti-configure.md b/ai/ti/reference/commands/ti/ti-configure.md new file mode 100644 index 0000000000000..ae2e8abc2b6c7 --- /dev/null +++ b/ai/ti/reference/commands/ti/ti-configure.md @@ -0,0 +1,58 @@ +--- +title: ti configure +summary: Configure a local TiDB Cloud CLI profile interactively or non-interactively. +--- + +# ti configure + +Configures a local TiDB Cloud CLI profile. Without flags, this is the only interactive TiDB Cloud CLI command. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti configure + [--help] + [--non-interactive] + [--region-code ] + [--tidb-cloud-private-key ] + [--tidb-cloud-public-key ] + [--version] +``` + +## Options + +- `--help`: Display help information. +- `--non-interactive`: Use this option to avoid being prompted for configuration values. You must provide at least three configuration values (`--tidb-cloud-public-key`, `--tidb-cloud-private-key`, and `--region-code`) when using this option. This is useful when running `ti` in a script or automated environment. +- `--region-code `: Default region code, for example `aws-us-east-1` or `aws-ap-southeast-1`. +- `--tidb-cloud-private-key `: TiDB Cloud API private key. +- `--tidb-cloud-public-key `: TiDB Cloud API public key. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Configure `ti` interactively: + + ```bash + # Enter the default region code and TiDB Cloud API keys when prompted. + ti configure + ``` + +- Configure `ti` for automation: + + ```bash + # Supply all required values without interactive prompts. + TI_REGION_CODE="aws-us-east-1" \ + TIDB_CLOUD_PUBLIC_KEY="" \ + TIDB_CLOUD_PRIVATE_KEY="" \ + ti configure --profile ci --non-interactive + ``` + +## Related documentation + +- [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) diff --git a/ai/tdc/reference/commands/tdc/tdc-update.md b/ai/ti/reference/commands/ti/ti-update.md similarity index 58% rename from ai/tdc/reference/commands/tdc/tdc-update.md rename to ai/ti/reference/commands/ti/ti-update.md index a6200ba7ad45e..372ac3fb10cd5 100644 --- a/ai/tdc/reference/commands/tdc/tdc-update.md +++ b/ai/ti/reference/commands/ti/ti-update.md @@ -1,20 +1,20 @@ --- -title: tdc update +title: ti update summary: Check for or install a TiDB Cloud CLI release update. --- -# tdc update +# ti update -Checks for or installs a TiDB Cloud CLI release update. This command does not read or modify settings, profiles, credentials, operation logs, or other state under `~/.tdc/`. +Checks for or installs a TiDB Cloud CLI release update. This command does not read or modify settings, profiles, credentials, operation logs, or other state under `~/.ti/`. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc update +ti update [--check] [--dry-run] [--fail-if-update-available] @@ -25,14 +25,14 @@ tdc update ## Options -- `--check`: Check whether a newer `tdc` release is available without updating. +- `--check`: Check whether a newer `ti` release is available without updating. - `--dry-run`: Show the update plan without changing the local binary. - `--fail-if-update-available`: With `--check`, exit with code 1 when an update is available. - `--help`: Display help information. -- `--target-version `: Target `tdc` version, such as `latest` or `vX.Y.Z`. \[default: latest] +- `--target-version `: Target `ti` version, such as `latest` or `vX.Y.Z`. \[default: latest] - `--version`: Display version information. -For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-cli-reference.md#global-options). +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). ## Examples @@ -40,23 +40,23 @@ For options shared by all commands, see [Global options](/ai/tdc/reference/tdc-c ```bash # Compare the installed version with the latest GitHub release without changing files. - tdc update --check + ti update --check ``` - Preview an update: ```bash # Show the files and versions that an update would change. - tdc update --dry-run + ti update --dry-run ``` - Install a specific release: ```bash # Replace an eligible installation with the requested release version. - tdc update --target-version + ti update --target-version ``` ## Related documentation -- [Install, Configure, and Update TiDB Cloud CLI](/ai/tdc/reference/tdc-install-configure-update.md) +- [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) diff --git a/ai/tdc/reference/tdc-agent-sandbox-example.md b/ai/ti/reference/ti-agent-sandbox-example.md similarity index 65% rename from ai/tdc/reference/tdc-agent-sandbox-example.md rename to ai/ti/reference/ti-agent-sandbox-example.md index d4d0ce5b614db..c266331ecd208 100644 --- a/ai/tdc/reference/tdc-agent-sandbox-example.md +++ b/ai/ti/reference/ti-agent-sandbox-example.md @@ -9,11 +9,11 @@ This example gives an ephemeral coding agent a durable workspace without copying > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem -Coding agents often start in clean, short-lived sandboxes. The local disk disappears when the sandbox is replaced, but the agent still needs previous artifacts, repository state, and files produced by other workers. Rebuilding that state wastes task time, while copying `~/.tdc/` or injecting TiDB Cloud API keys gives the sandbox control-plane credentials it does not need. +Coding agents often start in clean, short-lived sandboxes. The local disk disappears when the sandbox is replaced, but the agent still needs previous artifacts, repository state, and files produced by other workers. Rebuilding that state wastes task time, while copying `~/.ti/` or injecting TiDB Cloud API keys gives the sandbox control-plane credentials it does not need. ## Limitations of local storage and full cloud credentials @@ -21,18 +21,18 @@ A sandbox-local directory is fast but not durable or shared. Generic object-stor ## How TiDB Cloud CLI changes the workflow -A trusted machine provisions the Filesystem once. The sandbox receives only the Filesystem owner token, region code, and Filesystem name, and can immediately use data-plane, mount, Git, journal, and vault workflows without `tdc configure`. When an agent needs only selected secrets, use a delegated vault token instead of the owner token. +A trusted machine provisions the Filesystem once. The sandbox receives only the Filesystem owner token, region code, and Filesystem name, and can immediately use data-plane, mount, Git, journal, and vault workflows without `ti configure`. When an agent needs only selected secrets, use a delegated vault token instead of the owner token. ## Prerequisites - Install and configure the TiDB Cloud CLI on a trusted machine. -- Install the TiDB Cloud CLI in the sandbox. The release installer includes `tdc-drive9`. +- Install the TiDB Cloud CLI in the sandbox. The release installer includes `ti-drive9`. - Use a secure secret manager or encrypted sandbox input for token transfer. ## Step 1. Provision on the trusted machine ```bash -export TDC_FS_TOKEN="$(tdc fs create-file-system \ +export TI_FS_TOKEN="$(ti fs create-file-system \ --file-system-name agent-sandbox \ --wait \ --query fs_token \ @@ -46,23 +46,23 @@ Record the canonical region code used by the profile, for example `aws-us-east-1 Configure the sandbox secret/environment mechanism with: ```bash -TDC_FS_TOKEN= -TDC_REGION_CODE=aws-us-east-1 -TDC_FS_FILE_SYSTEM_NAME=agent-sandbox +TI_FS_TOKEN= +TI_REGION_CODE=aws-us-east-1 +TI_FS_FILE_SYSTEM_NAME=agent-sandbox ``` -The sandbox does not need `TDC_PUBLIC_KEY`, `TDC_PRIVATE_KEY`, `tdc configure`, or files copied from `~/.tdc/`. +The sandbox does not need `TIDB_CLOUD_PUBLIC_KEY`, `TIDB_CLOUD_PRIVATE_KEY`, `ti configure`, or files copied from `~/.ti/`. ## Step 3. Verify direct access In the sandbox: ```bash -printf 'sandbox ready\n' | tdc fs copy-file \ +printf 'sandbox ready\n' | ti fs copy-file \ --from-stdin \ --to-remote /sandbox/status.txt -tdc fs read-file --path /sandbox/status.txt +ti fs read-file --path /sandbox/status.txt ``` Expected output: @@ -77,7 +77,7 @@ On Linux with FUSE: ```bash mkdir -p "$HOME/workspace" -tdc fs mount-file-system \ +ti fs mount-file-system \ --file-system-name agent-sandbox \ --mount-path "$HOME/workspace" \ --driver fuse @@ -87,31 +87,31 @@ cat "$HOME/workspace/sandbox/status.txt" Using a path under `$HOME` also avoids the default `fusermount3` AppArmor mount-path restriction on Ubuntu 26.04. On macOS, omit `--driver fuse` to use the default WebDAV path. Use FUSE only after installing macFUSE. -After mounting, you can use `tdc fs-git`, `tdc fs-journal`, and owner-authorized `tdc fs-vault` commands with the same FS environment. Give agents a delegated `TDC_VAULT_TOKEN` instead of the owner token when they need only selected secret fields. +After mounting, you can use `ti fs-git`, `ti fs-journal`, and owner-authorized `ti fs-vault` commands with the same FS environment. Give agents a delegated `TI_VAULT_TOKEN` instead of the owner token when they need only selected secret fields. ## Cleanup Stop writers and unmount. A graceful FUSE unmount automatically flushes and drains pending work: ```bash -tdc fs unmount-file-system --mount-path "$HOME/workspace" +ti fs unmount-file-system --mount-path "$HOME/workspace" ``` -Use `tdc fs drain-file-system --mount-path "$HOME/workspace"` separately when you need to verify remote durability while keeping the mount online. Back on the trusted machine: +Use `ti fs drain-file-system --mount-path "$HOME/workspace"` separately when you need to verify remote durability while keeping the mount online. Back on the trusted machine: ```bash -tdc fs delete-file-system \ +ti fs delete-file-system \ --file-system-name agent-sandbox ``` ## Security notes -- Treat `TDC_FS_TOKEN` as an owner credential. +- Treat `TI_FS_TOKEN` as an owner credential. - Do not place it in an image, repository, command flag, or operation log. - Deleting the sandbox does not delete the remote Filesystem. - Graceful unmount drains pending FUSE writes; deleting the sandbox without unmounting does not. ## What's next -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-ci-artifact-handoff-example.md b/ai/ti/reference/ti-ci-artifact-handoff-example.md similarity index 72% rename from ai/tdc/reference/tdc-ci-artifact-handoff-example.md rename to ai/ti/reference/ti-ci-artifact-handoff-example.md index 0e4383e975505..d843425a81647 100644 --- a/ai/tdc/reference/tdc-ci-artifact-handoff-example.md +++ b/ai/ti/reference/ti-ci-artifact-handoff-example.md @@ -9,7 +9,7 @@ This scenario uses a Filesystem as a durable handoff point between isolated CI j > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## The problem @@ -17,16 +17,16 @@ Build and verification jobs often run on different ephemeral machines. Local out ## How TiDB Cloud CLI changes the workflow -The pipeline injects one Filesystem token, region, and name into both jobs. The producer uploads output under a run-specific path, and the consumer downloads or streams that exact path. Neither job needs TiDB Cloud API keys or a copied `~/.tdc/` directory. +The pipeline injects one Filesystem token, region, and name into both jobs. The producer uploads output under a run-specific path, and the consumer downloads or streams that exact path. Neither job needs TiDB Cloud API keys or a copied `~/.ti/` directory. ## Prerequisites Provision a Filesystem on a trusted machine and store these values as protected CI secrets or variables: ```text -TDC_FS_TOKEN -TDC_REGION_CODE -TDC_FS_FILE_SYSTEM_NAME +TI_FS_TOKEN +TI_REGION_CODE +TI_FS_FILE_SYSTEM_NAME ``` Use a CI-generated run identifier such as `RUN_ID` to isolate concurrent pipelines. @@ -37,7 +37,7 @@ Build the artifact, then upload it: ```bash tar -czf app.tar.gz ./dist -tdc fs copy-file \ +ti fs copy-file \ --from-local ./app.tar.gz \ --to-remote "/ci/${RUN_ID}/app.tar.gz" \ --tag pipeline=build \ @@ -49,7 +49,7 @@ tdc fs copy-file \ Download and verify the artifact from another runner: ```bash -tdc fs copy-file \ +ti fs copy-file \ --from-remote "/ci/${RUN_ID}/app.tar.gz" \ --to-local ./app.tar.gz \ --create-parents @@ -60,7 +60,7 @@ tar -tzf app.tar.gz For a command that accepts stdin, avoid an intermediate local file: ```bash -tdc fs copy-file --from-remote "/ci/${RUN_ID}/app.tar.gz" --to-stdout \ +ti fs copy-file --from-remote "/ci/${RUN_ID}/app.tar.gz" --to-stdout \ | tar -tzf - ``` @@ -69,13 +69,13 @@ tdc fs copy-file --from-remote "/ci/${RUN_ID}/app.tar.gz" --to-stdout \ Delete only the run-specific directory after all consumers finish: ```bash -tdc fs delete-file --path "/ci/${RUN_ID}" --recursive +ti fs delete-file --path "/ci/${RUN_ID}" --recursive ``` Use unique run IDs and do not delete the whole Filesystem from an individual job. Filesystem deletion requires the trusted control-plane configuration and should remain a separate owner operation. ## Related reference -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) -- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/ti/reference/ti-cli-reference.md similarity index 72% rename from ai/tdc/reference/tdc-cli-reference.md rename to ai/ti/reference/ti-cli-reference.md index 5763211db801b..a0e1dfbd62b4e 100644 --- a/ai/tdc/reference/tdc-cli-reference.md +++ b/ai/ti/reference/ti-cli-reference.md @@ -5,24 +5,24 @@ summary: Reference global options, output and query behavior, dry-run rules, hel # TiDB Cloud CLI Command Reference -This reference describes behavior shared across the `tdc` command surface. +This reference describes behavior shared across the `ti` command surface. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Syntax ```text -tdc [subcommand] [required options] [optional options] [global options] +ti [subcommand] [required options] [optional options] [global options] ``` -The `tdc` executable accepts long flags only. A one-letter flag such as `-p` is rejected. +The `ti` executable accepts long flags only. A one-letter flag such as `-p` is rejected. ## Command tree ```text -tdc +ti ├── configure ├── update ├── organization @@ -95,12 +95,12 @@ tdc └── unmount-vault ``` -Every operation has a dedicated command page with syntax and examples. Expand **Command Reference** in the documentation navigation and select a command under `tdc`, `organization`, `db`, `fs`, `fs-git`, `fs-journal`, or `fs-vault`. +Every operation has a dedicated command page with syntax and examples. Expand **Command Reference** in the documentation navigation and select a command under `ti`, `organization`, `db`, `fs`, `fs-git`, `fs-journal`, or `fs-vault`. Required options appear before optional options in generated usage. Optional options are enclosed in brackets: ```text -tdc db describe-db-cluster +ti db describe-db-cluster --db-cluster-id [--output ] [--view ] @@ -128,27 +128,27 @@ Command pages document `--help`, `--version`, and all command-specific options s Structured control-plane commands return JSON by default: ```bash -tdc db list-db-clusters --db-cluster-type starter +ti db list-db-clusters --db-cluster-type starter ``` Use text output for terminal inspection: ```bash -tdc db list-db-clusters --db-cluster-type starter --output text +ti db list-db-clusters --db-cluster-type starter --output text ``` -Raw byte-oriented commands such as `tdc fs read-file` and `tdc fs copy-file --to-stdout` write file content directly. +Raw byte-oriented commands such as `ti fs read-file` and `ti fs copy-file --to-stdout` write file content directly. ## JMESPath queries `--query` runs after successful command execution and before output rendering: ```bash -tdc db list-db-clusters \ +ti db list-db-clusters \ --db-cluster-type starter \ --query 'clusters[].{id:id,name:display_name,state:state}' -tdc organization list-projects \ +ti organization list-projects \ --query 'projects[?type == `tidbx_virtual`].id' \ --output text ``` @@ -160,7 +160,7 @@ An invalid expression fails without replacing the command result with partial ou Mutating control-plane commands declare `--dry-run`. The command validates local flags, profile, credentials, region, and request shape, then reports a plan without making the remote mutation. ```bash -tdc db delete-db-cluster \ +ti db delete-db-cluster \ --db-cluster-id "" \ --dry-run ``` @@ -169,32 +169,32 @@ Read-only commands reject `--dry-run`. Dry-run is not a general global simulatio ## Help and version forms -Running `tdc` without a command returns exit code `2` and prints a compact command-tree synopsis to stderr: +Running `ti` without a command returns exit code `2` and prints a compact command-tree synopsis to stderr: ```text -tdc [ERROR]: the following arguments are required: command +ti [ERROR]: the following arguments are required: command The TiDB Cloud Command Line Interface is a unified tool to manage your TiDB Cloud Filesystem (FS) and Starter services. -usage: tdc [] [parameters] +usage: ti [] [parameters] To see help information, you can run: - tdc help - tdc help - tdc help + ti help + ti help + ti help ``` Use an explicit help form to display commands and flags: ```bash -tdc help -tdc db help -tdc db create-db-cluster help -tdc --help -tdc db --help -tdc db create-db-cluster --help -tdc --version -tdc fs --version +ti help +ti db help +ti db create-db-cluster help +ti --help +ti db --help +ti db create-db-cluster --help +ti --version +ti fs --version ``` `help` is a command for navigating the command tree. `--help` is the conventional flag on each command; both intentionally coexist. @@ -204,7 +204,7 @@ tdc fs --version Human-readable errors start with a blank line and use a stable prefix: ```text -tdc [ERROR]: +ti [ERROR]: ``` Errors are written to stderr and successful command output is written to stdout. Usage and configuration failures return a nonzero exit code before remote mutation. Runtime and remote API failures also return nonzero. An interrupted interactive configuration returns exit code `130`. @@ -217,19 +217,19 @@ The following task-oriented guides explain how commands work together. They are | Guide | Purpose | | --- | --- | -| [Install, Configure, and Update](/ai/tdc/reference/tdc-install-configure-update.md) | Install releases, configure profiles, update, and uninstall `tdc` | -| [Organization and Projects](/ai/tdc/reference/tdc-organization.md) | Inspect projects and understand virtual-project selection | -| [Starter Databases and SQL](/ai/tdc/reference/tdc-starter-database.md) | Manage Starter clusters, branches, and SQL | -| [Filesystem](/ai/tdc/reference/tdc-filesystem.md) | Manage Filesystems, files, layers, packs, and mounts | -| [Filesystem Git Workspaces](/ai/tdc/reference/tdc-filesystem-git.md) | Manage Git workspaces on mounted Filesystems | -| [Filesystem Journals](/ai/tdc/reference/tdc-filesystem-journal.md) | Manage verifiable journals | -| [Filesystem Vault](/ai/tdc/reference/tdc-filesystem-vault.md) | Manage secrets and delegated access | +| [Install, Configure, and Update](/ai/ti/reference/ti-install-configure-update.md) | Install releases, configure profiles, update, and uninstall `ti` | +| [Organization and Projects](/ai/ti/reference/ti-organization.md) | Inspect projects and understand virtual-project selection | +| [Starter Databases and SQL](/ai/ti/reference/ti-starter-database.md) | Manage Starter clusters, branches, and SQL | +| [Filesystem](/ai/ti/reference/ti-filesystem.md) | Manage Filesystems, files, layers, packs, and mounts | +| [Filesystem Git Workspaces](/ai/ti/reference/ti-filesystem-git.md) | Manage Git workspaces on mounted Filesystems | +| [Filesystem Journals](/ai/ti/reference/ti-filesystem-journal.md) | Manage verifiable journals | +| [Filesystem Vault](/ai/ti/reference/ti-filesystem-vault.md) | Manage secrets and delegated access | For complete commands and options, run: ```bash -tdc help -tdc help +ti help +ti help ``` ## Filesystem alias mapping @@ -256,5 +256,5 @@ Aliases use the same long flags, authentication, output, query, and error behavi ## Related documentation -- [Install, Configure, and Update TiDB Cloud CLI](/ai/tdc/reference/tdc-install-configure-update.md) -- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/ti/reference/ti-configuration-and-credentials.md similarity index 54% rename from ai/tdc/reference/tdc-configuration-and-credentials.md rename to ai/ti/reference/ti-configuration-and-credentials.md index 8ccee371b5962..7731c74103330 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/ti/reference/ti-configuration-and-credentials.md @@ -5,26 +5,26 @@ summary: Reference TiDB Cloud CLI profiles, precedence rules, local state paths, # TiDB Cloud CLI Configuration and Credentials -`tdc` stores all product-owned local state under `~/.tdc/` and separates non-sensitive configuration from credentials. +`ti` stores all product-owned local state under `~/.ti/` and separates non-sensitive configuration from credentials. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Main files ```toml -# ~/.tdc/config +# ~/.ti/config [default] region_code = "aws-us-east-1" project_id = "..." ``` ```toml -# ~/.tdc/credentials +# ~/.ti/credentials [default] -tdc_public_key = "..." -tdc_private_key = "..." +tidb_cloud_public_key = "..." +tidb_cloud_private_key = "..." ``` The credentials file uses owner-only permissions where the platform supports POSIX modes. @@ -32,7 +32,7 @@ The credentials file uses owner-only permissions where the platform supports POS Global preferences are separate from profiles and credentials: ```toml -# ~/.tdc/.preferences +# ~/.ti/.preferences schema_version = 1 [logging] @@ -44,14 +44,14 @@ max_files = 5 enabled = false ``` -The dot-prefixed preferences file is optional, hidden from ordinary directory listings, and applies to every profile. Fresh installs and `tdc configure` do not create it. Reading a user-created file does not rewrite its permissions, comments, or formatting. +The dot-prefixed preferences file is optional, hidden from ordinary directory listings, and applies to every profile. Fresh installs and `ti configure` do not create it. Reading a user-created file does not rewrite its permissions, comments, or formatting. ## Profile selection The profile namespace is selected in this order: 1. explicit `--profile`; -2. `TDC_PROFILE`; +2. `TI_PROFILE`; 3. `default`. An explicit empty profile is invalid. @@ -60,15 +60,17 @@ An explicit empty profile is invalid. Credential selection is: -1. `TDC_PUBLIC_KEY` and `TDC_PRIVATE_KEY`, when either is set; -2. the selected section of `~/.tdc/credentials`. +1. `TIDB_CLOUD_PUBLIC_KEY` and `TIDB_CLOUD_PRIVATE_KEY`, when either is set; +2. the selected section of `~/.ti/credentials`. -Both environment values are required together. `tdc` never mixes one environment half with one file half. +Both environment values are required together. `ti` never mixes one environment half with one file half. + +During the v0.2.x transition, the CLI accepts the corresponding legacy `TDC_*` environment variable only when the canonical variable is absent. If both are set to different values, the command fails before changing local or remote state. New configuration writes only the canonical names shown on this page. Placement selection is: 1. explicit global `--region`; -2. `TDC_REGION_CODE`; +2. `TI_REGION_CODE`; 3. profile `region_code`. Command flags, environment inputs, saved configuration, and command defaults are resolved per field. Values can therefore come from different levels when they do not form an atomic pair such as the API key pair. @@ -78,10 +80,10 @@ Command flags, environment inputs, saved configuration, and command defaults are Starter create selects a project in this order: 1. explicit non-empty `--project-id`; -2. profile `project_id` discovered by `tdc configure`; +2. profile `project_id` discovered by `ti configure`; 3. omit the project label and let TiDB Cloud select the account's default project. -An explicitly empty `--project-id` is invalid. When no project ID is available, `tdc` omits the project label entirely rather than sending an empty value. +An explicitly empty `--project-id` is invalid. When no project ID is available, `ti` omits the project label entirely rather than sending an empty value. Other DB commands identify resources by cluster or branch ID and do not use `project_id`. Filesystem commands do not consume the DB project default. @@ -90,8 +92,8 @@ Other DB commands identify resources by cluster or branch ID and do not use `pro One profile can register multiple Filesystems. Resource state is isolated from the main profile configuration: ```text -~/.tdc/fs_resources///config -~/.tdc/fs_resources///credentials +~/.ti/fs_resources///config +~/.ti/fs_resources///credentials ``` The resource config contains the stored Filesystem name, tenant ID, cloud provider, region code, and creation time. The credentials file contains only the owner `api_key` and uses owner-only permissions. @@ -99,37 +101,37 @@ The resource config contains the stored Filesystem name, tenant ID, cloud provid Resource selection is: 1. explicit `--file-system-name`; -2. `TDC_FS_FILE_SYSTEM_NAME`; +2. `TI_FS_FILE_SYSTEM_NAME`; 3. fail with `fs.missing_file_system_name`. -`tdc` never infers a Filesystem from a saved default or from the number of registered resources. Use `--file-system-name` for one command or `TDC_FS_FILE_SYSTEM_NAME` for a shell, sandbox, or automation environment. +`ti` never infers a Filesystem from a saved default or from the number of registered resources. Use `--file-system-name` for one command or `TI_FS_FILE_SYSTEM_NAME` for a shell, sandbox, or automation environment. FS owner credential selection for remote `fs`, `fs-git`, `fs-journal`, and owner `fs-vault` operations is: 1. explicit `--fs-token`; -2. `TDC_FS_TOKEN`; +2. `TI_FS_TOKEN`; 3. selected resource credential. -Prefer `TDC_FS_TOKEN` over a flag because flags can remain in shell history or process listings. +Prefer `TI_FS_TOKEN` over a flag because flags can remain in shell history or process listings. ## Config-free Filesystem inputs A clean sandbox can use: ```bash -export TDC_FS_TOKEN="" -export TDC_REGION_CODE="aws-us-east-1" -export TDC_FS_FILE_SYSTEM_NAME="workspace" +export TI_FS_TOKEN="" +export TI_REGION_CODE="aws-us-east-1" +export TI_FS_FILE_SYSTEM_NAME="workspace" ``` -These values form an in-memory namespace only. `tdc` does not write them to `~/.tdc/`. Provisioning and deletion still require TiDB Cloud API credentials; deletion also requires the local resource registration. +These values form an in-memory namespace only. `ti` does not write them to `~/.ti/`. Provisioning and deletion still require TiDB Cloud API credentials; deletion also requires the local resource registration. ## DB SQL credentials Generated SQL credentials are cluster-scoped: ```text -~/.tdc/db_users//credentials +~/.ti/db_users//credentials ``` ```toml @@ -146,32 +148,32 @@ username = "..." password = "..." ``` -`tdc db create-db-sql-users` creates or repairs these stable users. They are not stored in the main credentials file. +`ti db create-db-sql-users` creates or repairs these stable users. They are not stored in the main credentials file. ## Companion state and mount locators Each registered Filesystem has an isolated companion home: ```text -~/.tdc/drive9-home/// +~/.ti/drive9-home/// ``` -Do not edit this state or a standalone `~/.drive9` configuration for `tdc` workflows. +Do not edit this state or a standalone `~/.drive9` configuration for `ti` workflows. A successful background FS or vault mount writes a non-secret locator: ```text -~/.tdc/mounts/.locator.json +~/.ti/mounts/.locator.json ``` The locator records the placement and companion-home information required for drain and unmount from the same `HOME`. It does not contain the FS token. Successful unmount removes it. ## Operation logs -`tdc` writes redacted local JSON Lines events to: +`ti` writes redacted local JSON Lines events to: ```text -~/.tdc/logs/tdc.jsonl +~/.ti/logs/ti.jsonl ``` This log is local audit/debug data, not telemetry. It can include command names, flag names, profile and region, duration, exit and stable error codes, HTTP method/status, operation, and request ID. It excludes flag values, SQL, file paths and contents, payloads, connection strings, and credentials. @@ -179,10 +181,10 @@ This log is local audit/debug data, not telemetry. It can include command names, Disable it for one process: ```bash -TDC_LOGGING=off tdc db list-db-clusters --db-cluster-type starter +TI_LOGGING=off ti db list-db-clusters --db-cluster-type starter ``` -Or create or edit `~/.tdc/.preferences`: +Or create or edit `~/.ti/.preferences`: ```toml schema_version = 1 @@ -193,13 +195,13 @@ enabled = false Environment values `off`, `false`, `0`, and `no` disable logging; `on`, `true`, `1`, and `yes` enable it. Environment takes precedence over settings. Invalid settings disable operation logging without failing the requested command. -Existing installations that stored `[logging]` in `~/.tdc/config` migrate those values to `~/.tdc/.preferences` automatically. The migration preserves profiles and credentials. `tdc update` does not read or write settings, profiles, credentials, operation logs, or other state under `~/.tdc/`. +Existing installations that stored `[logging]` in `~/.ti/config` migrate those values to `~/.ti/.preferences` automatically. The migration preserves profiles and credentials. `ti update` does not read or write settings, profiles, credentials, operation logs, or other state under `~/.ti/`. ## Anonymous telemetry Release builds send one best-effort completion event for eligible commands to the TiDB Cloud CLI telemetry service. The event contains the canonical command and explicitly supplied flag names, stable exit and error codes, duration, region, CLI version, OS, architecture, install source, and a random pseudonymous installation ID. It does not contain flag values, credentials, tokens, SQL text, file paths or contents, command output, API payloads, profile names, or cloud resource IDs. -Development builds and recognized CI environments default to disabled. Help, version, commandless usage, and every `tdc update` mode are always excluded. Disable telemetry persistently by adding the following global preference: +Development builds and recognized CI environments default to disabled. Help, version, commandless usage, and every `ti update` mode are always excluded. Disable telemetry persistently by adding the following global preference: ```toml [telemetry] @@ -209,17 +211,17 @@ enabled = false Disable it for one process without changing the file: ```bash -TDC_TELEMETRY=off tdc db list-db-clusters --db-cluster-type starter +TI_TELEMETRY=off ti db list-db-clusters --db-cluster-type starter ``` -The TiDB Cloud CLI creates `~/.tdc/.telemetry-installation-id` lazily for the first eligible event and restricts it to the current user where POSIX permissions are available. Delete this file to reset the pseudonymous identity. Telemetry delivery is lossy and never changes command output, errors, or exit status. +The TiDB Cloud CLI creates `~/.ti/.telemetry-installation-id` lazily for the first eligible event and restricts it to the current user where POSIX permissions are available. Delete this file to reset the pseudonymous identity. Telemetry delivery is lossy and never changes command output, errors, or exit status. -An integration can attach explicit process-scoped metadata without changing a profile or command. `TDC_TELEMETRY_TAG` accepts a UTF-8 string up to 128 bytes. `TDC_TELEMETRY_EXTRA` accepts one complete JSON value up to 2 KiB after compaction. Invalid, prohibited, deeply nested, or oversized metadata is omitted without affecting the command. Do not include credentials, tokens, SQL, paths, personal data, profile names, or cloud resource IDs in either value: +An integration can attach explicit process-scoped metadata without changing a profile or command. `TI_TELEMETRY_TAG` accepts a UTF-8 string up to 128 bytes. `TI_TELEMETRY_EXTRA` accepts one complete JSON value up to 2 KiB after compaction. Invalid, prohibited, deeply nested, or oversized metadata is omitted without affecting the command. Do not include credentials, tokens, SQL, paths, personal data, profile names, or cloud resource IDs in either value: ```bash -TDC_TELEMETRY_TAG="e2b-preview" \ -TDC_TELEMETRY_EXTRA='{"campaign":"launch","runtime":"e2b"}' \ -tdc fs list-files --file-system-name workspace --path / +TI_TELEMETRY_TAG="e2b-preview" \ +TI_TELEMETRY_EXTRA='{"campaign":"launch","runtime":"e2b"}' \ +ti fs list-files --file-system-name workspace --path / ``` ## Sensitive values @@ -235,5 +237,5 @@ Do not put them in source control, tickets, logs, command examples, or unprotect ## Related documentation -- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) -- [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-daily-workflow-example.md b/ai/ti/reference/ti-daily-workflow-example.md similarity index 69% rename from ai/tdc/reference/tdc-daily-workflow-example.md rename to ai/ti/reference/ti-daily-workflow-example.md index b016c6ed88fe6..38e074f94ddbe 100644 --- a/ai/tdc/reference/tdc-daily-workflow-example.md +++ b/ai/ti/reference/ti-daily-workflow-example.md @@ -9,30 +9,30 @@ This example follows a typical operator workflow across TiDB Cloud Starter and T > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Prerequisites -- Install `tdc` and run `tdc configure`. +- Install `ti` and run `ti configure`. - Ensure your organization has capacity for one Starter cluster and one Filesystem. ## Step 1. Inspect the active account ```bash -tdc organization list-projects --output text -tdc db list-db-clusters --db-cluster-type starter --output text -tdc fs list-file-systems --output text +ti organization list-projects --output text +ti db list-db-clusters --db-cluster-type starter --output text +ti fs list-file-systems --output text ``` ## Step 2. Create a Starter cluster ```bash -tdc db create-db-cluster \ +ti db create-db-cluster \ --db-cluster-type starter \ --db-cluster-name daily-demo \ --dry-run -tdc db create-db-cluster \ +ti db create-db-cluster \ --db-cluster-type starter \ --db-cluster-name daily-demo \ --wait @@ -41,7 +41,7 @@ tdc db create-db-cluster \ Record the returned cluster ID. Because `--wait` was set, the create command returns after the cluster is active. You can inspect it again later: ```bash -tdc db describe-db-cluster \ +ti db describe-db-cluster \ --db-cluster-id "" \ --output text ``` @@ -49,8 +49,8 @@ tdc db describe-db-cluster \ ## Step 3. Verify SQL access ```bash -tdc db create-db-sql-users --db-cluster-id "" -tdc db execute-sql-statement \ +ti db create-db-sql-users --db-cluster-id "" +ti db execute-sql-statement \ --db-cluster-id "" \ --read-only \ --sql "SELECT CURRENT_TIMESTAMP AS checked_at" \ @@ -60,15 +60,15 @@ tdc db execute-sql-statement \ ## Step 4. Create and use a Filesystem ```bash -tdc fs create-file-system \ +ti fs create-file-system \ --file-system-name daily-workspace -printf 'daily workflow\n' | tdc fs copy-file \ +printf 'daily workflow\n' | ti fs copy-file \ --file-system-name daily-workspace \ --from-stdin \ --to-remote /notes/today.txt -tdc fs list-files \ +ti fs list-files \ --file-system-name daily-workspace \ --path /notes \ --output text @@ -81,23 +81,23 @@ The file in `/notes/today.txt` verifies that the explicitly selected resource is Unmount active filesystems before applying an update. A check is always non-mutating: ```bash -tdc update --check +ti update --check ``` Apply an update when appropriate: ```bash -tdc update --dry-run -tdc update +ti update --dry-run +ti update ``` ## Cleanup ```bash -tdc fs delete-file-system \ +ti fs delete-file-system \ --file-system-name daily-workspace -tdc db delete-db-cluster \ +ti db delete-db-cluster \ --db-cluster-id "" ``` @@ -111,5 +111,5 @@ Deleting local TiDB Cloud CLI configuration is not a substitute for deleting rem ## What's next -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/tdc-filesystem-git.md b/ai/ti/reference/ti-filesystem-git.md similarity index 70% rename from ai/tdc/reference/tdc-filesystem-git.md rename to ai/ti/reference/ti-filesystem-git.md index a76b214ae0cc9..8e34605c55187 100644 --- a/ai/tdc/reference/tdc-filesystem-git.md +++ b/ai/ti/reference/ti-filesystem-git.md @@ -1,20 +1,20 @@ --- title: TiDB Cloud Filesystem Git CLI Command Reference -summary: Reference every `tdc fs-git` command for cloning, hydrating, and managing linked Git worktrees. +summary: Reference every `ti fs-git` command for cloning, hydrating, and managing linked Git worktrees. --- # TiDB Cloud Filesystem Git CLI Command Reference -`tdc fs-git` accelerates Git workspace setup on mounted TiDB Cloud Filesystem paths. It augments Git; you continue to use ordinary `git` commands for status, edit, add, commit, fetch, and push. +`ti fs-git` accelerates Git workspace setup on mounted TiDB Cloud Filesystem paths. It augments Git; you continue to use ordinary `git` commands for status, edit, add, commit, fetch, and push. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree ```text -tdc fs-git +ti fs-git ├── clone-git-workspace ├── hydrate-git-workspace ├── add-git-worktree @@ -23,10 +23,10 @@ tdc fs-git | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `clone-git-workspace` | Clones into a mounted Filesystem path. `--blobless` and `--hydrate background` expose the tree before all clean data finishes hydrating. | `tdc fs-git clone-git-workspace --repo-url https://github.com/pingcap/tidb.git --target-path /workspace/tidb --blobless --hydrate background` | -| `hydrate-git-workspace` | Materializes clean Git data for an existing fast or blobless workspace. | `tdc fs-git hydrate-git-workspace --target-path /workspace/tidb --timeout 30m` | -| `add-git-worktree` | Creates a linked worktree from a base workspace. | `tdc fs-git add-git-worktree --base-path /workspace/tidb --worktree-path /workspace/feature --branch-name feature-x` | -| `remove-git-worktree` | Removes a linked worktree; dirty worktrees require explicit `--force`. | `tdc fs-git remove-git-worktree --worktree-path /workspace/feature` | +| `clone-git-workspace` | Clones into a mounted Filesystem path. `--blobless` and `--hydrate background` expose the tree before all clean data finishes hydrating. | `ti fs-git clone-git-workspace --repo-url https://github.com/pingcap/tidb.git --target-path /workspace/tidb --blobless --hydrate background` | +| `hydrate-git-workspace` | Materializes clean Git data for an existing fast or blobless workspace. | `ti fs-git hydrate-git-workspace --target-path /workspace/tidb --timeout 30m` | +| `add-git-worktree` | Creates a linked worktree from a base workspace. | `ti fs-git add-git-worktree --base-path /workspace/tidb --worktree-path /workspace/feature --branch-name feature-x` | +| `remove-git-worktree` | Removes a linked worktree; dirty worktrees require explicit `--force`. | `ti fs-git remove-git-worktree --worktree-path /workspace/feature` | ## Prerequisites @@ -37,7 +37,7 @@ tdc fs-git ## Clone a workspace ```bash -tdc fs-git clone-git-workspace \ +ti fs-git clone-git-workspace \ --repo-url https://github.com/pingcap/tidb.git \ --target-path /path/to/workspace/tidb ``` @@ -45,7 +45,7 @@ tdc fs-git clone-git-workspace \ For a large repository, create a blobless workspace and hydrate in the background: ```bash -tdc fs-git clone-git-workspace \ +ti fs-git clone-git-workspace \ --repo-url https://github.com/pingcap/tidb.git \ --target-path /path/to/workspace/tidb \ --blobless \ @@ -59,7 +59,7 @@ The command returns after registering the workspace, so the file tree becomes av ## Hydrate an existing workspace ```bash -tdc fs-git hydrate-git-workspace \ +ti fs-git hydrate-git-workspace \ --target-path /path/to/workspace/tidb \ --timeout 30m ``` @@ -69,7 +69,7 @@ Hydration materializes clean Git objects for a fast or blobless workspace. It do ## Add a linked worktree ```bash -tdc fs-git add-git-worktree \ +ti fs-git add-git-worktree \ --base-path /path/to/workspace/tidb \ --worktree-path /path/to/workspace/tidb-feature \ --branch-name feature-x @@ -88,14 +88,14 @@ git -C /path/to/workspace/tidb-feature commit -m "Implement feature x" ## Remove a worktree ```bash -tdc fs-git remove-git-worktree \ +ti fs-git remove-git-worktree \ --worktree-path /path/to/workspace/tidb-feature ``` The command refuses a dirty worktree by default. Use `--force` only after deciding that local changes can be discarded: ```bash -tdc fs-git remove-git-worktree \ +ti fs-git remove-git-worktree \ --worktree-path /path/to/workspace/tidb-feature \ --force ``` @@ -112,5 +112,5 @@ The default coding-agent mount profile keeps `.git` and rebuildable generated fi ## What's next -- [Prepare a Git Workspace for Agents](/ai/tdc/reference/tdc-git-workspace-for-agents-example.md) -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [Prepare a Git Workspace for Agents](/ai/ti/reference/ti-git-workspace-for-agents-example.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/tdc-filesystem-journal.md b/ai/ti/reference/ti-filesystem-journal.md similarity index 53% rename from ai/tdc/reference/tdc-filesystem-journal.md rename to ai/ti/reference/ti-filesystem-journal.md index 6bfc9c2d6d976..5fec8effa418d 100644 --- a/ai/tdc/reference/tdc-filesystem-journal.md +++ b/ai/ti/reference/ti-filesystem-journal.md @@ -1,20 +1,20 @@ --- title: TiDB Cloud Filesystem Journal CLI Command Reference -summary: Reference every `tdc fs-journal` command for creating, appending, reading, searching, and verifying journals. +summary: Reference every `ti fs-journal` command for creating, appending, reading, searching, and verifying journals. --- # TiDB Cloud Filesystem Journal CLI Command Reference -`tdc fs-journal` provides an append-only, verifiable ledger for agent and workflow events. Unlike a mutable text file, a journal assigns ordered sequence numbers, supports structured search, and maintains a hash chain that can detect alteration. +`ti fs-journal` provides an append-only, verifiable ledger for agent and workflow events. Unlike a mutable text file, a journal assigns ordered sequence numbers, supports structured search, and maintains a hash chain that can detect alteration. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree ```text -tdc fs-journal +ti fs-journal ├── create-journal ├── append-journal-entries ├── read-journal-entries @@ -24,24 +24,24 @@ tdc fs-journal | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `create-journal` | Creates a journal with an optional caller-provided ID, kind, actor, title, and labels. | `tdc fs-journal create-journal --journal-kind agent --title "review task" --actor agent:reviewer` | -| `append-journal-entries` | Appends JSON entries from repeatable flags, JSON Lines stdin, or a JSON array. | `tdc fs-journal append-journal-entries --journal-id jrn-demo --entry-json '{"type":"task.started"}'` | -| `read-journal-entries` | Reads ordered entries after a sequence number. | `tdc fs-journal read-journal-entries --journal-id jrn-demo --after-seq 0 --limit 100` | -| `search-journal-entries` | Searches journals and entries by type, kind, actor, status, subject, label, or time. | `tdc fs-journal search-journal-entries --entry-type task.started --include-entries` | -| `verify-journal` | Recalculates and verifies one journal's ordered hash chain. | `tdc fs-journal verify-journal --journal-id jrn-demo --output text` | +| `create-journal` | Creates a journal with an optional caller-provided ID, kind, actor, title, and labels. | `ti fs-journal create-journal --journal-kind agent --title "review task" --actor agent:reviewer` | +| `append-journal-entries` | Appends JSON entries from repeatable flags, JSON Lines stdin, or a JSON array. | `ti fs-journal append-journal-entries --journal-id jrn-demo --entry-json '{"type":"task.started"}'` | +| `read-journal-entries` | Reads ordered entries after a sequence number. | `ti fs-journal read-journal-entries --journal-id jrn-demo --after-seq 0 --limit 100` | +| `search-journal-entries` | Searches journals and entries by type, kind, actor, status, subject, label, or time. | `ti fs-journal search-journal-entries --entry-type task.started --include-entries` | +| `verify-journal` | Recalculates and verifies one journal's ordered hash chain. | `ti fs-journal verify-journal --journal-id jrn-demo --output text` | ## Prerequisites -Select a Filesystem through a profile or provide `TDC_FS_TOKEN`, `TDC_REGION_CODE`, and `TDC_FS_FILE_SYSTEM_NAME`. +Select a Filesystem through a profile or provide `TI_FS_TOKEN`, `TI_REGION_CODE`, and `TI_FS_FILE_SYSTEM_NAME`. ## Create a journal ```bash -tdc fs-journal create-journal \ +ti fs-journal create-journal \ --journal-id jrn-demo \ --journal-kind agent \ --title "demo task" \ - --actor agent:tdc \ + --actor agent:ti \ --label env=dev ``` @@ -52,10 +52,10 @@ tdc fs-journal create-journal \ Append one or more JSON objects: ```bash -tdc fs-journal append-journal-entries \ +ti fs-journal append-journal-entries \ --journal-id jrn-demo \ --entry-json '{"type":"task.started","status":"running"}' \ - --entry-json '{"type":"tool.called","tool":"tdc"}' + --entry-json '{"type":"tool.called","tool":"ti"}' ``` Use `--entry-type` as a default for entries without `type`, and add `--source` or repeatable `--subject` metadata. `--idempotency-key` makes a retry deterministic; the CLI generates one when omitted. @@ -67,7 +67,7 @@ For pipelines, send JSON Lines on stdin, or use `--json-array` for a JSON array. Read entries after a sequence: ```bash -tdc fs-journal read-journal-entries \ +ti fs-journal read-journal-entries \ --journal-id jrn-demo \ --after-seq 0 \ --limit 100 @@ -76,7 +76,7 @@ tdc fs-journal read-journal-entries \ Search across journals: ```bash -tdc fs-journal search-journal-entries \ +ti fs-journal search-journal-entries \ --entry-type task.started \ --journal-kind agent \ --label env=dev \ @@ -88,7 +88,7 @@ Search also supports status, actor, subject, `--since`, `--until`, `--limit`, an ## Verify integrity ```bash -tdc fs-journal verify-journal \ +ti fs-journal verify-journal \ --journal-id jrn-demo \ --output text ``` @@ -97,5 +97,5 @@ Verification recalculates the ordered hash chain and reports whether the entries ## What's next -- [Record an Agent Workflow in a Journal](/ai/tdc/reference/tdc-journal-agent-workflow-example.md) -- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [Record an Agent Workflow in a Journal](/ai/ti/reference/ti-journal-agent-workflow-example.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-filesystem-vault.md b/ai/ti/reference/ti-filesystem-vault.md similarity index 57% rename from ai/tdc/reference/tdc-filesystem-vault.md rename to ai/ti/reference/ti-filesystem-vault.md index 5b6cade6937d8..92e746a8483a2 100644 --- a/ai/tdc/reference/tdc-filesystem-vault.md +++ b/ai/ti/reference/ti-filesystem-vault.md @@ -1,20 +1,20 @@ --- title: TiDB Cloud Filesystem Vault CLI Command Reference -summary: Reference every `tdc fs-vault` command for secrets, grants, audit events, process injection, and read-only mounts. +summary: Reference every `ti fs-vault` command for secrets, grants, audit events, process injection, and read-only mounts. --- # TiDB Cloud Filesystem Vault CLI Command Reference -`tdc fs-vault` stores structured secrets and delegates limited, expiring access to agents. Owner operations use the Filesystem owner credential; delegated reads use a vault token scoped to selected secrets or fields. +`ti fs-vault` stores structured secrets and delegates limited, expiring access to agents. Owner operations use the Filesystem owner credential; delegated reads use a vault token scoped to selected secrets or fields. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree ```text -tdc fs-vault +ti fs-vault ├── create-secret ├── replace-secret ├── read-secret @@ -30,17 +30,17 @@ tdc fs-vault | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `create-secret` | Creates a structured secret from repeatable literal, file, or stdin fields. | `tdc fs-vault create-secret --secret-name db-prod --field PASSWORD=@./password.txt` | -| `replace-secret` | Replaces all fields from files in one directory. | `tdc fs-vault replace-secret --secret-path /n/vault/db-prod --from-directory ./secret-fields` | -| `read-secret` | Reads all fields or one field as structured, raw, or environment output. | `tdc fs-vault read-secret --secret-name db-prod --field DB_URL --format raw` | -| `list-secrets` | Lists secrets visible to the active owner or delegated credential. | `tdc fs-vault list-secrets` | -| `delete-secret` | Deletes one owner-visible secret. | `tdc fs-vault delete-secret --secret-name db-prod` | -| `create-grant` | Creates a scoped, expiring delegated token for one agent. | `tdc fs-vault create-grant --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m` | -| `delete-grant` | Revokes one grant by ID. | `tdc fs-vault delete-grant --grant-id "" --reason completed` | -| `list-audit-events` | Lists vault access events using secret, agent, time, and limit filters. | `tdc fs-vault list-audit-events --secret-name db-prod --limit 20` | -| `run-with-secret` | Runs a child command with secret fields injected as environment variables. | `tdc fs-vault run-with-secret --secret-path /n/vault/db-prod -- ./deploy.sh` | -| `mount-vault` | Mounts delegated readable fields as a local read-only FUSE filesystem. | `tdc fs-vault mount-vault --mount-path /path/to/vault --vault-token "$TDC_VAULT_TOKEN"` | -| `unmount-vault` | Unmounts a local vault mount. | `tdc fs-vault unmount-vault --mount-path /path/to/vault` | +| `create-secret` | Creates a structured secret from repeatable literal, file, or stdin fields. | `ti fs-vault create-secret --secret-name db-prod --field PASSWORD=@./password.txt` | +| `replace-secret` | Replaces all fields from files in one directory. | `ti fs-vault replace-secret --secret-path /n/vault/db-prod --from-directory ./secret-fields` | +| `read-secret` | Reads all fields or one field as structured, raw, or environment output. | `ti fs-vault read-secret --secret-name db-prod --field DB_URL --format raw` | +| `list-secrets` | Lists secrets visible to the active owner or delegated credential. | `ti fs-vault list-secrets` | +| `delete-secret` | Deletes one owner-visible secret. | `ti fs-vault delete-secret --secret-name db-prod` | +| `create-grant` | Creates a scoped, expiring delegated token for one agent. | `ti fs-vault create-grant --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m` | +| `delete-grant` | Revokes one grant by ID. | `ti fs-vault delete-grant --grant-id "" --reason completed` | +| `list-audit-events` | Lists vault access events using secret, agent, time, and limit filters. | `ti fs-vault list-audit-events --secret-name db-prod --limit 20` | +| `run-with-secret` | Runs a child command with secret fields injected as environment variables. | `ti fs-vault run-with-secret --secret-path /n/vault/db-prod -- ./deploy.sh` | +| `mount-vault` | Mounts delegated readable fields as a local read-only FUSE filesystem. | `ti fs-vault mount-vault --mount-path /path/to/vault --vault-token "$TI_VAULT_TOKEN"` | +| `unmount-vault` | Unmounts a local vault mount. | `ti fs-vault unmount-vault --mount-path /path/to/vault` | ## Prerequisites @@ -51,7 +51,7 @@ Select a Filesystem through a profile or the config-free FS environment variable Create a secret with repeatable fields: ```bash -tdc fs-vault create-secret \ +ti fs-vault create-secret \ --secret-name db-prod \ --field DB_URL=mysql://example \ --field PASSWORD=@./password.txt @@ -62,7 +62,7 @@ tdc fs-vault create-secret \ Replace all fields with files from a directory: ```bash -tdc fs-vault replace-secret \ +ti fs-vault replace-secret \ --secret-path /n/vault/db-prod \ --from-directory ./secret-fields ``` @@ -70,16 +70,16 @@ tdc fs-vault replace-secret \ ## Read, list, and delete ```bash -tdc fs-vault list-secrets -tdc fs-vault read-secret --secret-name db-prod -tdc fs-vault read-secret --secret-name db-prod --field DB_URL --format raw -tdc fs-vault read-secret --secret-name db-prod --field DB_URL --format env +ti fs-vault list-secrets +ti fs-vault read-secret --secret-name db-prod +ti fs-vault read-secret --secret-name db-prod --field DB_URL --format raw +ti fs-vault read-secret --secret-name db-prod --field DB_URL --format env ``` Delete an owner-visible secret: ```bash -tdc fs-vault delete-secret --secret-name db-prod +ti fs-vault delete-secret --secret-name db-prod ``` Raw and environment output contains plaintext. Direct it only to the intended process. @@ -89,7 +89,7 @@ Raw and environment output contains plaintext. Direct it only to the intended pr Create a short-lived read grant and capture its token: ```bash -export TDC_VAULT_TOKEN="$(tdc fs-vault create-grant \ +export TI_VAULT_TOKEN="$(ti fs-vault create-grant \ --agent-id deploy-agent \ --scope db-prod/DB_URL \ --permission read \ @@ -102,18 +102,18 @@ Scopes are repeatable. `--label-hint` can add non-secret operator context. Use the delegated token: ```bash -tdc fs-vault read-secret \ +ti fs-vault read-secret \ --secret-name db-prod \ --field DB_URL \ --format raw ``` -`TDC_VAULT_TOKEN` is preferred over `--vault-token` because command-line values can remain in process listings or shell history. +`TI_VAULT_TOKEN` is preferred over `--vault-token` because command-line values can remain in process listings or shell history. ## Inject a secret into a process ```bash -tdc fs-vault run-with-secret \ +ti fs-vault run-with-secret \ --secret-path /n/vault/db-prod \ -- env ``` @@ -123,13 +123,13 @@ The child receives secret fields as environment variables. Avoid commands that p ## Audit and revoke ```bash -tdc fs-vault list-audit-events \ +ti fs-vault list-audit-events \ --secret-name db-prod \ --agent-id deploy-agent \ --since 24h \ --limit 20 -tdc fs-vault delete-grant \ +ti fs-vault delete-grant \ --grant-id "" \ --revoked-by operator \ --reason rotated @@ -143,9 +143,9 @@ On macOS or Linux with FUSE support: ```bash mkdir -p /path/to/vault -tdc fs-vault mount-vault \ +ti fs-vault mount-vault \ --mount-path /path/to/vault \ - --vault-token "$TDC_VAULT_TOKEN" + --vault-token "$TI_VAULT_TOKEN" ``` The mount is read-only. `--foreground` keeps it attached to the terminal, and `--ready-timeout` changes the background readiness wait. @@ -153,7 +153,7 @@ The mount is read-only. `--foreground` keeps it attached to the terminal, and `- Unmount: ```bash -tdc fs-vault unmount-vault --mount-path /path/to/vault +ti fs-vault unmount-vault --mount-path /path/to/vault ``` Unmount also supports `--timeout`, `--force`, and `--ignore-absent`. Vault mount is unavailable on Windows and requires FUSE support; direct `read-secret` and `run-with-secret` do not require a mount. @@ -168,5 +168,5 @@ Unmount also supports `--timeout`, `--force`, and `--ignore-absent`. Vault mount ## What's next -- [Delegate Secrets to an Agent](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) -- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [Delegate Secrets to an Agent](/ai/ti/reference/ti-vault-agent-secrets-example.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/tdc/reference/tdc-filesystem.md b/ai/ti/reference/ti-filesystem.md similarity index 59% rename from ai/tdc/reference/tdc-filesystem.md rename to ai/ti/reference/ti-filesystem.md index ad22207fe6ab8..e8985527c1788 100644 --- a/ai/tdc/reference/tdc-filesystem.md +++ b/ai/ti/reference/ti-filesystem.md @@ -1,20 +1,20 @@ --- title: TiDB Cloud Filesystem CLI Command Reference -summary: Reference every `tdc fs` command for Filesystem resources, files, layers, packs, and mounts. +summary: Reference every `ti fs` command for Filesystem resources, files, layers, packs, and mounts. --- # TiDB Cloud Filesystem CLI Command Reference -Use `tdc fs` to provision TiDB Cloud Filesystem resources and access their data from commands or local mounts. +Use `ti fs` to provision TiDB Cloud Filesystem resources and access their data from commands or local mounts. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree ```text -tdc fs +ti fs ├── create-file-system ├── list-file-systems ├── describe-file-system @@ -52,75 +52,75 @@ tdc fs | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `create-file-system` | Provisions a Filesystem. Requires `--file-system-name`; `--wait` waits until data-plane access is ready. | `tdc fs create-file-system --file-system-name workspace --wait` | -| `list-file-systems` | Lists resources registered in the selected local profile. | `tdc fs list-file-systems --output text` | -| `describe-file-system` | Reads one locally registered resource by name. | `tdc fs describe-file-system --file-system-name workspace` | -| `check-file-system` | Verifies resource selection, endpoint resolution, credentials, and companion access. | `tdc fs check-file-system --file-system-name workspace` | -| `delete-file-system` | Requests asynchronous deletion and removes its local registration. Requires TiDB Cloud credentials and the owner resource credential. | `tdc fs delete-file-system --file-system-name workspace` | +| `create-file-system` | Provisions a Filesystem. Requires `--file-system-name`; `--wait` waits until data-plane access is ready. | `ti fs create-file-system --file-system-name workspace --wait` | +| `list-file-systems` | Lists resources registered in the selected local profile. | `ti fs list-file-systems --output text` | +| `describe-file-system` | Reads one locally registered resource by name. | `ti fs describe-file-system --file-system-name workspace` | +| `check-file-system` | Verifies resource selection, endpoint resolution, credentials, and companion access. | `ti fs check-file-system --file-system-name workspace` | +| `delete-file-system` | Requests asynchronous deletion and removes its local registration. Requires TiDB Cloud credentials and the owner resource credential. | `ti fs delete-file-system --file-system-name workspace` | ### Data and namespace commands | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `copy-file` | Uploads, downloads, streams, appends, resumes, or recursively copies local and remote paths. | `tdc fs copy-file --from-local ./report.md --to-remote /reports/report.md` | -| `read-file` | Writes a complete file or byte range to stdout. | `tdc fs read-file --path /reports/report.md --offset 0 --length 1024` | -| `list-files` | Lists entries under a remote path. | `tdc fs list-files --path /reports --output text` | -| `describe-file` | Returns metadata for one remote path. | `tdc fs describe-file --path /reports/report.md` | -| `move-file` | Moves or renames one remote path. | `tdc fs move-file --from-remote /draft.md --to-remote /reports/final.md` | -| `delete-file` | Deletes one remote path; `--recursive` is required for non-empty directories. | `tdc fs delete-file --path /scratch --recursive` | -| `create-directory` | Creates a remote directory and optionally sets its mode. | `tdc fs create-directory --path /reports/archive --mode 0755` | -| `chmod-file` | Changes remote POSIX mode metadata. | `tdc fs chmod-file --path /reports/final.md --mode 0600` | -| `create-symlink` | Creates a symbolic link with a target string and link path. | `tdc fs create-symlink --target final.md --link-path /reports/latest.md` | -| `create-hardlink` | Creates a hard link from an existing remote path. | `tdc fs create-hardlink --source-path /reports/final.md --link-path /reports/final-copy.md` | -| `search-file-content` | Searches file contents below a path, optionally within a layer. | `tdc fs search-file-content --path /reports --pattern "TODO"` | -| `find-files` | Finds paths by name, type, tags, size, or timestamps. | `tdc fs find-files --path /reports --file-name-pattern "*.md" --tag stage=review` | +| `copy-file` | Uploads, downloads, streams, appends, resumes, or recursively copies local and remote paths. | `ti fs copy-file --from-local ./report.md --to-remote /reports/report.md` | +| `read-file` | Writes a complete file or byte range to stdout. | `ti fs read-file --path /reports/report.md --offset 0 --length 1024` | +| `list-files` | Lists entries under a remote path. | `ti fs list-files --path /reports --output text` | +| `describe-file` | Returns metadata for one remote path. | `ti fs describe-file --path /reports/report.md` | +| `move-file` | Moves or renames one remote path. | `ti fs move-file --from-remote /draft.md --to-remote /reports/final.md` | +| `delete-file` | Deletes one remote path; `--recursive` is required for non-empty directories. | `ti fs delete-file --path /scratch --recursive` | +| `create-directory` | Creates a remote directory and optionally sets its mode. | `ti fs create-directory --path /reports/archive --mode 0755` | +| `chmod-file` | Changes remote POSIX mode metadata. | `ti fs chmod-file --path /reports/final.md --mode 0600` | +| `create-symlink` | Creates a symbolic link with a target string and link path. | `ti fs create-symlink --target final.md --link-path /reports/latest.md` | +| `create-hardlink` | Creates a hard link from an existing remote path. | `ti fs create-hardlink --source-path /reports/final.md --link-path /reports/final-copy.md` | +| `search-file-content` | Searches file contents below a path, optionally within a layer. | `ti fs search-file-content --path /reports --pattern "TODO"` | +| `find-files` | Finds paths by name, type, tags, size, or timestamps. | `ti fs find-files --path /reports --file-name-pattern "*.md" --tag stage=review` | ### Layer and portability commands | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `create-layer` | Creates an isolated change layer over `--base-root-path`; returns a generated layer ID when one is not supplied. | `tdc fs create-layer --base-root-path /workspace --layer-name task` | -| `list-layers` | Lists layers for the selected Filesystem. | `tdc fs list-layers --output text` | -| `describe-layer` | Reads one layer by ID. | `tdc fs describe-layer --layer-id ""` | -| `diff-layer` | Lists changes recorded in one layer. | `tdc fs diff-layer --layer-id ""` | -| `create-layer-checkpoint` | Records a named checkpoint for a layer. | `tdc fs create-layer-checkpoint --layer-id "" --checkpoint-id before-review` | -| `rollback-layer` | Restores a layer to its rollback state without committing it to the base. | `tdc fs rollback-layer --layer-id ""` | -| `commit-layer` | Applies a layer's changes to the base Filesystem. | `tdc fs commit-layer --layer-id ""` | -| `pack-file-system` | Stores selected local overlay state in a remote archive. | `tdc fs pack-file-system --mount-path /path/to/workspace` | -| `unpack-file-system` | Restores local overlay state from a remote archive. | `tdc fs unpack-file-system --mount-path /path/to/workspace` | +| `create-layer` | Creates an isolated change layer over `--base-root-path`; returns a generated layer ID when one is not supplied. | `ti fs create-layer --base-root-path /workspace --layer-name task` | +| `list-layers` | Lists layers for the selected Filesystem. | `ti fs list-layers --output text` | +| `describe-layer` | Reads one layer by ID. | `ti fs describe-layer --layer-id ""` | +| `diff-layer` | Lists changes recorded in one layer. | `ti fs diff-layer --layer-id ""` | +| `create-layer-checkpoint` | Records a named checkpoint for a layer. | `ti fs create-layer-checkpoint --layer-id "" --checkpoint-id before-review` | +| `rollback-layer` | Restores a layer to its rollback state without committing it to the base. | `ti fs rollback-layer --layer-id ""` | +| `commit-layer` | Applies a layer's changes to the base Filesystem. | `ti fs commit-layer --layer-id ""` | +| `pack-file-system` | Stores selected local overlay state in a remote archive. | `ti fs pack-file-system --mount-path /path/to/workspace` | +| `unpack-file-system` | Restores local overlay state from a remote archive. | `ti fs unpack-file-system --mount-path /path/to/workspace` | ### Mount commands | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `mount-file-system` | Mounts a resource through automatic, FUSE, or WebDAV mode. Requires `--mount-path`; select the resource with a flag or environment variable. | `tdc fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace` | -| `drain-file-system` | Flushes pending FUSE work while leaving the mount online. | `tdc fs drain-file-system --mount-path /path/to/workspace --timeout 30s` | -| `unmount-file-system` | Gracefully flushes and unmounts a background FUSE or WebDAV mount. | `tdc fs unmount-file-system --mount-path /path/to/workspace` | +| `mount-file-system` | Mounts a resource through automatic, FUSE, or WebDAV mode. Requires `--mount-path`; select the resource with a flag or environment variable. | `ti fs mount-file-system --file-system-name workspace --mount-path /path/to/workspace` | +| `drain-file-system` | Flushes pending FUSE work while leaving the mount online. | `ti fs drain-file-system --mount-path /path/to/workspace --timeout 30s` | +| `unmount-file-system` | Gracefully flushes and unmounts a background FUSE or WebDAV mount. | `ti fs unmount-file-system --mount-path /path/to/workspace` | ## Prerequisites -- Run `tdc configure` before provisioning or deleting a Filesystem. -- Install `tdc` with the release installer so the `tdc-drive9` companion is next to the `tdc` binary. +- Run `ti configure` before provisioning or deleting a Filesystem. +- Install `ti` with the release installer so the `ti-drive9` companion is next to the `ti` binary. - Treat the returned FS owner token as a secret. -Data-plane commands can instead use an existing Filesystem with `TDC_FS_TOKEN`, `TDC_REGION_CODE`, and `TDC_FS_FILE_SYSTEM_NAME`, without TiDB Cloud API keys. +Data-plane commands can instead use an existing Filesystem with `TI_FS_TOKEN`, `TI_REGION_CODE`, and `TI_FS_FILE_SYSTEM_NAME`, without TiDB Cloud API keys. ## Manage Filesystem resources Create a resource and wait until data-plane access is ready: ```bash -tdc fs create-file-system \ +ti fs create-file-system \ --file-system-name workspace \ --wait ``` -Without `--wait`, `tdc` returns after Drive9 accepts provisioning. With the flag, `tdc` waits up to 10 minutes until the root is readable through the public Drive9 data-plane CLI. A failed wait leaves the resource and locally stored credential intact. +Without `--wait`, `ti` returns after Drive9 accepts provisioning. With the flag, `ti` waits up to 10 minutes until the root is readable through the public Drive9 data-plane CLI. A failed wait leaves the resource and locally stored credential intact. The JSON response includes `fs_token`. Capture it without displaying the complete result: ```bash -export TDC_FS_TOKEN="$(tdc fs create-file-system \ +export TI_FS_TOKEN="$(ti fs create-file-system \ --file-system-name sandbox \ --wait \ --query fs_token \ @@ -130,70 +130,70 @@ export TDC_FS_TOKEN="$(tdc fs create-file-system \ List and describe locally registered resources: ```bash -tdc fs list-file-systems -tdc fs describe-file-system --file-system-name workspace +ti fs list-file-systems +ti fs describe-file-system --file-system-name workspace ``` Select a resource for subsequent commands in the current shell: ```bash -export TDC_FS_FILE_SYSTEM_NAME="workspace" +export TI_FS_FILE_SYSTEM_NAME="workspace" ``` Check the selected resource and companion: ```bash -tdc fs check-file-system --file-system-name workspace +ti fs check-file-system --file-system-name workspace ``` Delete a resource only after removing data you need: ```bash -tdc fs delete-file-system \ +ti fs delete-file-system \ --file-system-name workspace ``` -Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and a locally registered resource; an FS token alone cannot delete the resource. Drive9 deletion is asynchronous, so a successfully accepted request reports `status: "deleting"` while `tdc` removes the selected local registry entry and credential. +Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and a locally registered resource; an FS token alone cannot delete the resource. Drive9 deletion is asynchronous, so a successfully accepted request reports `status: "deleting"` while `ti` removes the selected local registry entry and credential. ## Select one of multiple Filesystems One profile can own multiple resources. Selection precedence is: 1. `--file-system-name`; -2. `TDC_FS_FILE_SYSTEM_NAME`; +2. `TI_FS_FILE_SYSTEM_NAME`; 3. fail with `fs.missing_file_system_name`. -`tdc` does not infer a resource from the profile registry, even when only one resource is registered. This makes scripts deterministic when resources are added or removed. +`ti` does not infer a resource from the profile registry, even when only one resource is registered. This makes scripts deterministic when resources are added or removed. ## Copy and read data Upload, download, and copy remotely: ```bash -tdc fs copy-file --from-local ./README.md --to-remote /workspace/README.md -tdc fs copy-file --from-remote /workspace/README.md --to-local ./README.copy.md --create-parents -tdc fs copy-file --from-remote /workspace/README.md --to-remote /archive/README.md +ti fs copy-file --from-local ./README.md --to-remote /workspace/README.md +ti fs copy-file --from-remote /workspace/README.md --to-local ./README.copy.md --create-parents +ti fs copy-file --from-remote /workspace/README.md --to-remote /archive/README.md ``` Use `--overwrite` to replace an existing target, `--resume` for a supported interrupted upload or download, and `--recursive` for directories: ```bash -tdc fs copy-file --from-local ./src --to-remote /workspace/src --recursive -tdc fs copy-file --from-local ./large.bin --to-remote /workspace/large.bin --resume +ti fs copy-file --from-local ./src --to-remote /workspace/src --recursive +ti fs copy-file --from-local ./large.bin --to-remote /workspace/large.bin --resume ``` Append and stream: ```bash -tdc fs copy-file --from-local ./tail.log --to-remote /logs/app.log --append -printf 'hello\n' | tdc fs copy-file --from-stdin --to-remote /workspace/stdin.txt -tdc fs copy-file --from-remote /workspace/stdin.txt --to-stdout +ti fs copy-file --from-local ./tail.log --to-remote /logs/app.log --append +printf 'hello\n' | ti fs copy-file --from-stdin --to-remote /workspace/stdin.txt +ti fs copy-file --from-remote /workspace/stdin.txt --to-stdout ``` Add metadata during upload: ```bash -tdc fs copy-file \ +ti fs copy-file \ --from-local ./report.md \ --to-remote /workspace/report.md \ --tag owner=agent \ @@ -204,22 +204,22 @@ tdc fs copy-file \ Read a complete file or a byte range: ```bash -tdc fs read-file --path /workspace/report.md -tdc fs read-file --path /workspace/large.bin --offset 1024 --length 4096 +ti fs read-file --path /workspace/report.md +ti fs read-file --path /workspace/large.bin --offset 1024 --length 4096 ``` ## Inspect and modify the namespace ```bash -tdc fs list-files --path /workspace -tdc fs describe-file --path /workspace/report.md -tdc fs create-directory --path /workspace/archive --mode 0755 -tdc fs move-file --from-remote /workspace/report.md --to-remote /workspace/archive/report.md -tdc fs chmod-file --path /workspace/archive/report.md --mode 0600 -tdc fs create-symlink --target archive/report.md --link-path /workspace/report.link -tdc fs create-hardlink --source-path /workspace/archive/report.md --link-path /workspace/report.hard -tdc fs delete-file --path /workspace/report.link -tdc fs delete-file --path /workspace/archive --recursive +ti fs list-files --path /workspace +ti fs describe-file --path /workspace/report.md +ti fs create-directory --path /workspace/archive --mode 0755 +ti fs move-file --from-remote /workspace/report.md --to-remote /workspace/archive/report.md +ti fs chmod-file --path /workspace/archive/report.md --mode 0600 +ti fs create-symlink --target archive/report.md --link-path /workspace/report.link +ti fs create-hardlink --source-path /workspace/archive/report.md --link-path /workspace/report.hard +ti fs delete-file --path /workspace/report.link +ti fs delete-file --path /workspace/archive --recursive ``` Mutating namespace commands support `--dry-run`. @@ -227,8 +227,8 @@ Mutating namespace commands support `--dry-run`. Search content and metadata: ```bash -tdc fs search-file-content --path /workspace --pattern "TODO" --limit 50 -tdc fs find-files --path /workspace --file-name-pattern "*.md" --tag stage=review +ti fs search-file-content --path /workspace --pattern "TODO" --limit 50 +ti fs find-files --path /workspace --file-name-pattern "*.md" --tag stage=review ``` `find-files` also supports resource type, time, size, and result-limit filters. Both search commands accept `--layer-id`. @@ -238,7 +238,7 @@ tdc fs find-files --path /workspace --file-name-pattern "*.md" --tag stage=revie A layer records changes over a base root before you commit or discard them: ```bash -tdc fs create-layer \ +ti fs create-layer \ --base-root-path /workspace \ --layer-name agent-task \ --durability-mode restore-safe \ @@ -248,15 +248,15 @@ tdc fs create-layer \ Use the returned layer ID: ```bash -tdc fs copy-file \ +ti fs copy-file \ --from-local ./proposal.md \ --to-remote /workspace/proposal.md \ --layer-id "" -tdc fs list-layers -tdc fs describe-layer --layer-id "" -tdc fs diff-layer --layer-id "" -tdc fs create-layer-checkpoint \ +ti fs list-layers +ti fs describe-layer --layer-id "" +ti fs diff-layer --layer-id "" +ti fs create-layer-checkpoint \ --layer-id "" \ --checkpoint-id before-review \ --label "before review" @@ -265,8 +265,8 @@ tdc fs create-layer-checkpoint \ Finish the layer by rolling it back or committing it: ```bash -tdc fs rollback-layer --layer-id "" -tdc fs commit-layer --layer-id "" +ti fs rollback-layer --layer-id "" +ti fs commit-layer --layer-id "" ``` These two commands represent alternative outcomes for the same work; do not run both in sequence in a real workflow. @@ -276,8 +276,8 @@ These two commands represent alternative outcomes for the same work; do not run FUSE mount profiles can route selected paths to local overlay storage. Pack those paths to a remote archive before moving to another machine: ```bash -tdc fs pack-file-system --mount-path /path/to/workspace -tdc fs unpack-file-system --mount-path /path/to/workspace +ti fs pack-file-system --mount-path /path/to/workspace +ti fs unpack-file-system --mount-path /path/to/workspace ``` Without an active mount, provide `--local-root`, `--remote-root`, and `--mount-profile`. `--archive-path` selects the remote archive, repeatable `--path` limits pack contents, and `--no-replace` makes unpack merge rather than replace manifest paths. @@ -288,7 +288,7 @@ Create the local mount path and mount in the background: ```bash mkdir -p /path/to/workspace -tdc fs mount-file-system \ +ti fs mount-file-system \ --file-system-name workspace \ --mount-path /path/to/workspace ``` @@ -305,21 +305,21 @@ The default `--driver auto` is platform-specific. `--remote-path` exposes a subt ### Mount in Docker and Docker Compose -Installing FUSE3 inside an image does not enable mounts by itself. The Docker host must provide `/dev/fuse`, and the container must receive permission to perform the mount. The following Dockerfile installs the required Ubuntu package and `tdc` without storing any cloud or Filesystem credentials in the image: +Installing FUSE3 inside an image does not enable mounts by itself. The Docker host must provide `/dev/fuse`, and the container must receive permission to perform the mount. The following Dockerfile installs the required Ubuntu package and `ti` without storing any cloud or Filesystem credentials in the image: ```dockerfile FROM ubuntu:24.04 -ARG TDC_VERSION=latest +ARG TI_VERSION=latest RUN apt-get update \ && apt-get install -y --no-install-recommends ca-certificates curl fuse3 \ && rm -rf /var/lib/apt/lists/* -RUN curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh \ - | sh -s -- --yes --version "${TDC_VERSION}" +RUN curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh \ + | sh -s -- --yes --version "${TI_VERSION}" -ENV PATH="/root/.tdc/bin:${PATH}" +ENV PATH="/root/.ti/bin:${PATH}" RUN mkdir -p /workspace @@ -329,24 +329,24 @@ CMD ["bash"] Build the image, then pass the Filesystem owner token, canonical region code, and Filesystem name at runtime: ```bash -docker build -t tdc-fuse . +docker build -t ti-fuse . docker run --rm -it \ --device /dev/fuse \ --cap-add SYS_ADMIN \ --security-opt apparmor=unconfined \ - --env TDC_FS_TOKEN \ - --env TDC_REGION_CODE \ - --env TDC_FS_FILE_SYSTEM_NAME \ - tdc-fuse + --env TI_FS_TOKEN \ + --env TI_REGION_CODE \ + --env TI_FS_FILE_SYSTEM_NAME \ + ti-fuse ``` The three environment variables must already exist in the host shell. Inside the container, mount and use the Filesystem normally: ```bash -tdc fs mount --mount-path /workspace +ti fs mount --mount-path /workspace printf 'hello from Docker\n' > /workspace/hello.txt -tdc fs umount --mount-path /workspace +ti fs umount --mount-path /workspace ``` Use the equivalent runtime settings in `compose.yaml`: @@ -357,7 +357,7 @@ services: build: context: . args: - TDC_VERSION: latest + TI_VERSION: latest devices: - /dev/fuse:/dev/fuse cap_add: @@ -365,9 +365,9 @@ services: security_opt: - apparmor=unconfined environment: - TDC_FS_TOKEN: ${TDC_FS_TOKEN} - TDC_REGION_CODE: ${TDC_REGION_CODE} - TDC_FS_FILE_SYSTEM_NAME: ${TDC_FS_FILE_SYSTEM_NAME} + TI_FS_TOKEN: ${TI_FS_TOKEN} + TI_REGION_CODE: ${TI_REGION_CODE} + TI_FS_FILE_SYSTEM_NAME: ${TI_FS_FILE_SYSTEM_NAME} stdin_open: true tty: true ``` @@ -382,12 +382,12 @@ docker compose run --rm agent > **Warning:** > -> `SYS_ADMIN` and an unconfined AppArmor profile weaken container isolation. Use them only for a dedicated, trusted agent container. Rootless Docker and managed container platforms might prohibit these settings; use `tdc fs` data-plane commands without a mount when FUSE cannot be granted. The mount exists in the container mount namespace and disappears when the container stops, so wait for graceful unmount to succeed before stopping a container that might have pending writes. +> `SYS_ADMIN` and an unconfined AppArmor profile weaken container isolation. Use them only for a dedicated, trusted agent container. Rootless Docker and managed container platforms might prohibit these settings; use `ti fs` data-plane commands without a mount when FUSE cannot be granted. The mount exists in the container mount namespace and disappears when the container stops, so wait for graceful unmount to succeed before stopping a container that might have pending writes. macOS intentionally keeps WebDAV as the automatic choice even when macFUSE is installed. To use FUSE, install a supported release from the [official macFUSE site](https://macfuse.github.io/), complete any approval or restart requested by its installer, and run: ```bash -tdc fs mount-file-system \ +ti fs mount-file-system \ --file-system-name workspace \ --mount-path /path/to/workspace \ --driver fuse @@ -396,11 +396,11 @@ tdc fs mount-file-system \ Explicit FUSE supports cache controls: ```bash -tdc fs mount-file-system \ +ti fs mount-file-system \ --file-system-name workspace \ --mount-path /path/to/workspace \ --driver fuse \ - --cache-dir "$HOME/.tdc/cache/workspace" \ + --cache-dir "$HOME/.ti/cache/workspace" \ --read-cache-size-mb 256 \ --read-cache-max-file-mb 16 \ --read-cache-ttl 30s @@ -414,7 +414,7 @@ Prefer an allowed mount path: ```bash mkdir -p "$HOME/workspace" -tdc fs mount-file-system \ +ti fs mount-file-system \ --file-system-name workspace \ --mount-path "$HOME/workspace" ``` @@ -424,7 +424,7 @@ For a system-level path, `/mnt/workspace` is allowed by the default profile: ```bash sudo mkdir -p /mnt/workspace sudo chown "$(id -u):$(id -g)" /mnt/workspace -tdc fs mount-file-system \ +ti fs mount-file-system \ --file-system-name workspace \ --mount-path /mnt/workspace ``` @@ -443,21 +443,21 @@ The default mount profile is `coding-agent`, which keeps common development stat Stop writers and close open files before cleanup. A normal unmount performs a graceful shutdown: the companion flushes open handles and pending FUSE write-back work, waits for its upload queues, and then exits. You do not need to run drain first: ```bash -tdc fs unmount-file-system \ +ti fs unmount-file-system \ --mount-path /path/to/workspace ``` Use drain when you need an explicit durability barrier while keeping a FUSE mount online, for example before handing the mount to another process or checking remote visibility: ```bash -tdc fs drain-file-system \ +ti fs drain-file-system \ --mount-path /path/to/workspace \ --timeout 30s ``` Drain flushes dirty handles and waits for pending writes, but the mount remains available and can accept new writes afterward. It is not supported for WebDAV. `unmount-file-system` also supports `--timeout`, `--force`, `--ignore-absent`, `--pack-archive-path`, and `--no-auto-pack`. -A successful background mount writes a non-secret locator under `~/.tdc/mounts/`. Drain and unmount can use that locator from the same `HOME` without `TDC_FS_TOKEN` or `TDC_REGION_CODE`. +A successful background mount writes a non-secret locator under `~/.ti/mounts/`. Drain and unmount can use that locator from the same `HOME` without `TI_FS_TOKEN` or `TI_REGION_CODE`. > **Warning:** > @@ -469,24 +469,24 @@ Aliases change only the command name. All flags remain long and identical to the | Alias | Canonical command | | --- | --- | -| `tdc fs cp` | `tdc fs copy-file` | -| `tdc fs cat` | `tdc fs read-file` | -| `tdc fs ls` | `tdc fs list-files` | -| `tdc fs stat` | `tdc fs describe-file` | -| `tdc fs mv` | `tdc fs move-file` | -| `tdc fs rm` | `tdc fs delete-file` | -| `tdc fs mkdir` | `tdc fs create-directory` | -| `tdc fs chmod` | `tdc fs chmod-file` | -| `tdc fs symlink` | `tdc fs create-symlink` | -| `tdc fs hardlink` | `tdc fs create-hardlink` | -| `tdc fs grep` | `tdc fs search-file-content` | -| `tdc fs find` | `tdc fs find-files` | -| `tdc fs mount` | `tdc fs mount-file-system` | -| `tdc fs drain` | `tdc fs drain-file-system` | -| `tdc fs umount` | `tdc fs unmount-file-system` | +| `ti fs cp` | `ti fs copy-file` | +| `ti fs cat` | `ti fs read-file` | +| `ti fs ls` | `ti fs list-files` | +| `ti fs stat` | `ti fs describe-file` | +| `ti fs mv` | `ti fs move-file` | +| `ti fs rm` | `ti fs delete-file` | +| `ti fs mkdir` | `ti fs create-directory` | +| `ti fs chmod` | `ti fs chmod-file` | +| `ti fs symlink` | `ti fs create-symlink` | +| `ti fs hardlink` | `ti fs create-hardlink` | +| `ti fs grep` | `ti fs search-file-content` | +| `ti fs find` | `ti fs find-files` | +| `ti fs mount` | `ti fs mount-file-system` | +| `ti fs drain` | `ti fs drain-file-system` | +| `ti fs umount` | `ti fs unmount-file-system` | ## What's next -- [Use a Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) -- [Share a Filesystem Across Machines](/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md) -- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) +- [Use a Filesystem in an Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) +- [Share a Filesystem Across Machines](/ai/ti/reference/ti-share-filesystem-across-machines-example.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/tdc/reference/tdc-git-workspace-for-agents-example.md b/ai/ti/reference/ti-git-workspace-for-agents-example.md similarity index 70% rename from ai/tdc/reference/tdc-git-workspace-for-agents-example.md rename to ai/ti/reference/ti-git-workspace-for-agents-example.md index 4b87bd1756ad5..9b10bd8d6e891 100644 --- a/ai/tdc/reference/tdc-git-workspace-for-agents-example.md +++ b/ai/ti/reference/ti-git-workspace-for-agents-example.md @@ -9,7 +9,7 @@ This example removes a large repository clone from the critical path of starting > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem @@ -21,7 +21,7 @@ A normal clone blocks until the initial object transfer and checkout finish. A n ## How TiDB Cloud CLI changes the workflow -`tdc fs-git clone-git-workspace --blobless --hydrate background` registers the Git workspace and exposes its file tree before all clean blobs finish downloading. The command returns so the agent can inspect paths and start working while `tdc` hydrates the clean tree and local Git object database in the background. Reads that arrive before hydration completes fall back to Git's lazy fetch for correctness. Ordinary Git remains responsible for edits, commits, fetches, and pushes. +`ti fs-git clone-git-workspace --blobless --hydrate background` registers the Git workspace and exposes its file tree before all clean blobs finish downloading. The command returns so the agent can inspect paths and start working while `ti` hydrates the clean tree and local Git object database in the background. Reads that arrive before hydration completes fall back to Git's lazy fetch for correctness. Ordinary Git remains responsible for edits, commits, fetches, and pushes. ## Prerequisites @@ -33,7 +33,7 @@ A normal clone blocks until the initial object transfer and checkout finish. A n ```bash mkdir -p /path/to/workspace -tdc fs mount-file-system \ +ti fs mount-file-system \ --mount-path /path/to/workspace \ --driver fuse ``` @@ -41,7 +41,7 @@ tdc fs mount-file-system \ ## Step 2. Create the workspace and hydrate in the background ```bash -tdc fs-git clone-git-workspace \ +ti fs-git clone-git-workspace \ --repo-url https://github.com/pingcap/tidb.git \ --target-path /path/to/workspace/tidb \ --blobless \ @@ -58,7 +58,7 @@ git -C /path/to/workspace/tidb status Before a deterministic benchmark or before draining the mount, you can wait for hydration explicitly: ```bash -tdc fs-git hydrate-git-workspace \ +ti fs-git hydrate-git-workspace \ --target-path /path/to/workspace/tidb \ --timeout 30m ``` @@ -66,7 +66,7 @@ tdc fs-git hydrate-git-workspace \ ## Step 3. Create an agent worktree ```bash -tdc fs-git add-git-worktree \ +ti fs-git add-git-worktree \ --base-path /path/to/workspace/tidb \ --worktree-path /path/to/workspace/tidb-agent-task \ --branch-name agent-task @@ -83,21 +83,21 @@ Commit or push required changes before removing the worktree. ## Cleanup ```bash -tdc fs-git remove-git-worktree \ +ti fs-git remove-git-worktree \ --worktree-path /path/to/workspace/tidb-agent-task -tdc fs unmount-file-system --mount-path /path/to/workspace +ti fs unmount-file-system --mount-path /path/to/workspace ``` -Use `--force` for worktree removal only when uncommitted changes can be discarded. Filesystem unmount performs a graceful drain automatically; use `tdc fs drain-file-system` separately only when you need to flush remote work without unmounting. +Use `--force` for worktree removal only when uncommitted changes can be discarded. Filesystem unmount performs a graceful drain automatically; use `ti fs drain-file-system` separately only when you need to flush remote work without unmounting. ## Security and durability notes -- Repository credentials are managed by Git, not `tdc`. +- Repository credentials are managed by Git, not `ti`. - The coding-agent profile keeps `.git` and ignored generated files locally for performance. - Preserve or pack local overlay state before deleting an ephemeral machine when it cannot be rebuilt. ## What's next -- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/tdc/reference/tdc-filesystem-git.md) -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/ti-install-configure-update.md b/ai/ti/reference/ti-install-configure-update.md new file mode 100644 index 0000000000000..85d2848b3388f --- /dev/null +++ b/ai/ti/reference/ti-install-configure-update.md @@ -0,0 +1,190 @@ +--- +title: Install, Configure, and Update TiDB Cloud CLI +summary: Install TiDB Cloud CLI releases, configure profiles, check versions, apply updates, and uninstall the CLI. +--- + +# Install, Configure, and Update TiDB Cloud CLI + +This reference documents the supported release installers, top-level configuration and update commands, help and version behavior, and uninstallation. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Command tree + +```text +ti +├── configure +└── update +``` + +| Command | Required inputs | Main optional inputs | Example | +| --- | --- | --- | --- | +| `ti configure` | Interactive input, or region and TiDB Cloud API keys in non-interactive mode | `--profile`, `--non-interactive`, `--region-code`, key flags | `ti configure --profile staging` | +| `ti update` | None | `--check`, `--fail-if-update-available`, `--dry-run`, `--target-version` | `ti update --check` | + +Run `ti configure help` or `ti update help` for the complete generated flag list. + +## Install TiDB Cloud CLI + +### macOS and Linux + +Run the installer: + +```bash +curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh -s -- --yes +``` + +After installation, add `ti` to the current shell and verify it: + +```bash +export PATH="$HOME/.ti/bin:$PATH" +ti --version +``` + +The installer places `ti` and its `ti-drive9` companion in `~/.ti/bin`. Add the `PATH` export to your shell profile. The installer does not require `sudo` and does not write credentials. + +After installation, the installer displays the anonymous telemetry fields, prohibited data, persistent opt-out path, and process-scoped `TI_TELEMETRY=off` override. It does not prompt for a telemetry choice or create the optional preferences file. + +### Windows + +Run the installer: + +```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 +``` + +After installation, add `ti` to the current PowerShell session and verify it: + +```powershell +$env:Path = "$HOME\.ti\bin;$env:Path" +ti --version +``` + +Add `$HOME\.ti\bin` to your user `PATH` to keep `ti` available in new PowerShell sessions. + +The Windows installer displays the same anonymous telemetry and opt-out notice without creating a preference or installation identity. + +## Configure a profile + +Interactive configuration is the only TiDB Cloud CLI workflow that prompts: + +```bash +ti configure +``` + +The TiDB Cloud CLI requests a TiDB Cloud API public key, private key, and canonical region code. It validates the key by listing projects and records the unique `tidbx_virtual` project as the profile's default project. + +Configure a named profile: + +```bash +ti configure --profile staging +``` + +For CI or another non-interactive environment, prefer environment variables: + +```bash +TIDB_CLOUD_PUBLIC_KEY="" \ +TIDB_CLOUD_PRIVATE_KEY="" \ +TI_REGION_CODE="aws-us-east-1" \ +ti configure --profile ci --non-interactive +``` + +You can also provide `--tidb-cloud-public-key`, `--tidb-cloud-private-key`, and `--region-code`, but secret flags can remain in shell history or process listings. + +Configuration precedence is command flag, environment variable, then saved profile. The global `--region` overrides only the placement for the current command: + +```bash +ti db list-db-clusters --db-cluster-type starter --profile staging --region aws-us-west-2 +``` + +## Get help and version information + +All command levels support `help`, `--help`, and `--version`: + +```bash +ti help +ti fs help +ti db create-db-cluster help +ti --version +ti fs --version +``` + +Required flags appear before optional flags in generated usage. The TiDB Cloud CLI supports long flags only. + +## Update TiDB Cloud CLI + +Check without changing files: + +```bash +ti update --check +``` + +In automation, fail when an update exists: + +```bash +ti update --check --fail-if-update-available +``` + +Preview and apply an update: + +```bash +ti update --dry-run +ti update +``` + +Install a specific TiDB Cloud CLI release: + +```bash +ti update --target-version v0.1.2 +``` + +The update command replaces both binaries in the user-owned install directory. An active Filesystem mount keeps running the already loaded companion process. To avoid mixing the old mount runtime with new CLI commands, stop writers and unmount before updating. Graceful unmount automatically flushes and drains pending FUSE work: + +```bash +ti fs unmount-file-system --mount-path /path/to/workspace +ti update +``` + +For WebDAV, close writers and unmount. Use the FUSE-only drain command separately only when you need a durability barrier without unmounting. Installations in protected or package-manager-owned locations are not modified. Run the installer once to migrate an older `/usr/local/bin` installation to `~/.ti/bin`. + +## Migrate from tdc v0.1.x + +The `ti` installer and the first non-update `ti` command migrate supported local state from `~/.tdc/` to `~/.ti/` when `~/.tdc/` exists and `~/.ti/` does not. The migration includes profiles, TiDB Cloud API credentials, global preferences, the telemetry installation identity, DB SQL credentials, and Filesystem registrations and credentials. It preserves `~/.tdc/` as a rollback copy and does not copy binaries, logs, caches, local overlays, mount locators, or companion runtime state. A hidden owner-only marker under `~/.ti/` records that the old and new directories coexist because migration completed successfully. + +Before installing `ti`, unmount active tdc Filesystem and Vault mounts. The migration refuses to proceed while an old mount is active because copying runtime state cannot transfer a live FUSE or WebDAV process safely. + +If both directories were created independently, or the migration marker is absent, invalid, or points to a different source, `ti` stops without merging or overwriting either directory. Move or remove the directory that is not your intended source of truth, and then run the command again. Do not combine credential or Filesystem registry directories manually. + +During the v0.2.x transition, `ti` accepts legacy `TDC_*` environment variables only when the corresponding canonical variable is absent. If both forms are set to different values, the command fails before changing local or remote state. New automation should use `TI_*` and `TIDB_CLOUD_*` variables. Legacy environment variable support is removed in v0.3.0. + +## Uninstall TiDB Cloud CLI + +Remove only the binaries: + +```bash +rm -f "$HOME/.ti/bin/ti" "$HOME/.ti/bin/ti-drive9" +``` + +On Windows: + +```powershell +Remove-Item "$HOME\.ti\bin\ti.exe", "$HOME\.ti\bin\ti-drive9.exe" +``` + +Removing binaries preserves profiles, credentials, Filesystem registrations, DB SQL credentials, logs, and mount locators. Remove `~/.ti/` only when you intend to delete all local TiDB Cloud CLI state: + +```bash +rm -rf "$HOME/.ti" +``` + +Deleting local state does not delete remote Starter clusters or Filesystem resources. + +## What's next + +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/tdc/reference/tdc-journal-agent-workflow-example.md b/ai/ti/reference/ti-journal-agent-workflow-example.md similarity index 79% rename from ai/tdc/reference/tdc-journal-agent-workflow-example.md rename to ai/ti/reference/ti-journal-agent-workflow-example.md index f7d6c0b0f16ed..0bf91750e457e 100644 --- a/ai/tdc/reference/tdc-journal-agent-workflow-example.md +++ b/ai/ti/reference/ti-journal-agent-workflow-example.md @@ -9,7 +9,7 @@ This example records an agent task as a structured, ordered, and verifiable even > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem @@ -30,7 +30,7 @@ Select a Filesystem through a configured profile or FS token environment. ## Step 1. Create the journal ```bash -tdc fs-journal create-journal \ +ti fs-journal create-journal \ --journal-id jrn-agent-demo \ --journal-kind agent \ --title "dependency update" \ @@ -42,12 +42,12 @@ tdc fs-journal create-journal \ ## Step 2. Append workflow events ```bash -tdc fs-journal append-journal-entries \ +ti fs-journal append-journal-entries \ --journal-id jrn-agent-demo \ --idempotency-key dependency-update-start \ --entry-json '{"type":"task.started","status":"running"}' -tdc fs-journal append-journal-entries \ +ti fs-journal append-journal-entries \ --journal-id jrn-agent-demo \ --entry-json '{"type":"test.finished","status":"passed","suite":"unit"}' \ --entry-json '{"type":"task.finished","status":"completed"}' @@ -56,13 +56,13 @@ tdc fs-journal append-journal-entries \ ## Step 3. Read and search ```bash -tdc fs-journal read-journal-entries \ +ti fs-journal read-journal-entries \ --journal-id jrn-agent-demo \ --after-seq 0 \ --limit 100 \ --output text -tdc fs-journal search-journal-entries \ +ti fs-journal search-journal-entries \ --entry-type task.finished \ --status completed \ --label repository=demo \ @@ -74,7 +74,7 @@ The ordered result should include the start, test, and completion events. ## Step 4. Verify integrity ```bash -tdc fs-journal verify-journal \ +ti fs-journal verify-journal \ --journal-id jrn-agent-demo \ --output text ``` @@ -83,7 +83,7 @@ A successful result confirms the stored sequence and hash chain are consistent. ## Cleanup -Journals are append-only and currently have no delete command in the public `tdc` command surface. Use a synthetic journal ID and retain it as workflow evidence. Delete the containing Filesystem only when its complete contents are no longer needed. +Journals are append-only and currently have no delete command in the public `ti` command surface. Use a synthetic journal ID and retain it as workflow evidence. Delete the containing Filesystem only when its complete contents are no longer needed. ## Security notes @@ -92,5 +92,5 @@ Journals are append-only and currently have no delete command in the public `tdc ## What's next -- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) -- [Delegate Secrets to an Agent](/ai/tdc/reference/tdc-vault-agent-secrets-example.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) +- [Delegate Secrets to an Agent](/ai/ti/reference/ti-vault-agent-secrets-example.md) diff --git a/ai/ti/reference/ti-organization.md b/ai/ti/reference/ti-organization.md new file mode 100644 index 0000000000000..dbaeec96d29cd --- /dev/null +++ b/ai/ti/reference/ti-organization.md @@ -0,0 +1,74 @@ +--- +title: TiDB Cloud Organization CLI Command Reference +summary: Reference the `ti organization` command tree, project listing inputs, output, and examples. +--- + +# TiDB Cloud Organization CLI Command Reference + +Use `ti organization` to inspect the projects accessible to the configured TiDB Cloud API key. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Command tree + +```text +ti organization +└── list-projects +``` + +`list-projects` requires a configured TiDB Cloud API key. It accepts `--page-size` and `--page-token` for pagination, plus the global output and query flags. + +## Prerequisites + +Run `ti configure` with a TiDB Cloud API key that can list organization projects. + +## List projects + +```bash +ti organization list-projects +``` + +The JSON response includes project IDs, names, and `type` values: + +- `tidbx` identifies a regular project; +- `tidbx_virtual` identifies a virtual project used as the default Starter project. + +Request a page size or continue with a returned page token: + +```bash +ti organization list-projects --page-size 50 +ti organization list-projects --page-size 50 --page-token "" +``` + +Render a terminal-oriented table or select fields: + +```bash +ti organization list-projects --output text +ti organization list-projects --query 'projects[].{id:id,name:name,type:type}' +``` + +## Default virtual project + +`ti configure` calls the same project-listing API. Configuration succeeds only when it finds exactly one accessible `tidbx_virtual` project, and saves its ID in the selected profile: + +```toml +[default] +region_code = "aws-us-east-1" +project_id = "..." +``` + +`ti db create-db-cluster` uses this project when `--project-id` is omitted. If the saved ID is removed, cluster creation omits the project label and TiDB Cloud selects the account's default project. Pass an explicit project ID to override either default for one cluster: + +```bash +ti db create-db-cluster \ + --db-cluster-type starter \ + --db-cluster-name project-specific-cluster \ + --project-id "" +``` + +## What's next + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-parallel-agent-dataset-example.md b/ai/ti/reference/ti-parallel-agent-dataset-example.md similarity index 75% rename from ai/tdc/reference/tdc-parallel-agent-dataset-example.md rename to ai/ti/reference/ti-parallel-agent-dataset-example.md index 9fdec6030c75f..0213f64cd5090 100644 --- a/ai/tdc/reference/tdc-parallel-agent-dataset-example.md +++ b/ai/ti/reference/ti-parallel-agent-dataset-example.md @@ -9,7 +9,7 @@ This scenario gives multiple short-lived workers one shared corpus without copyi > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## The problem @@ -24,17 +24,17 @@ An owner uploads the corpus once. Every worker selects the same Filesystem and m On a trusted machine: ```bash -tdc fs create-file-system \ +ti fs create-file-system \ --file-system-name shared-corpus \ --wait -tdc fs copy-file \ +ti fs copy-file \ --file-system-name shared-corpus \ --from-local ./corpus \ --to-remote /datasets/corpus \ --recursive -tdc fs find-files \ +ti fs find-files \ --file-system-name shared-corpus \ --path /datasets/corpus \ --file-name-pattern "*.pdf" \ @@ -49,7 +49,7 @@ Inject the resource token, region, and name into each worker, then run: ```bash mkdir -p "$HOME/corpus" -tdc fs mount-file-system \ +ti fs mount-file-system \ --file-system-name shared-corpus \ --mount-path "$HOME/corpus" \ --remote-path /datasets/corpus \ @@ -65,18 +65,18 @@ find "$HOME/corpus" -type f -name '*.pdf' -print Unmount before terminating the worker: ```bash -tdc fs unmount-file-system --mount-path "$HOME/corpus" +ti fs unmount-file-system --mount-path "$HOME/corpus" ``` ## Operational notes - `--read-only` prevents writes through that mount. The underlying FS owner token remains an owner credential and is not a read-only security token. -- Do not let workers use direct mutating `tdc fs` commands when the workflow requires read-only behavior. +- Do not let workers use direct mutating `ti fs` commands when the workflow requires read-only behavior. - Partition result paths by agent or run ID if workers write to the same output Filesystem. - On platforms where FUSE or WebDAV mounting is unavailable, use `read-file`, `find-files`, and `copy-file --to-local` directly. ## Related reference -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [Use a Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) -- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [Use a Filesystem in an Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/tdc/reference/tdc-persistent-agent-state-example.md b/ai/ti/reference/ti-persistent-agent-state-example.md similarity index 70% rename from ai/tdc/reference/tdc-persistent-agent-state-example.md rename to ai/ti/reference/ti-persistent-agent-state-example.md index d91d501e2c28b..4778310d9a4eb 100644 --- a/ai/tdc/reference/tdc-persistent-agent-state-example.md +++ b/ai/ti/reference/ti-persistent-agent-state-example.md @@ -9,7 +9,7 @@ This scenario keeps an agent's durable state in TiDB Cloud Filesystem while its > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## The problem @@ -24,38 +24,38 @@ A trusted machine provisions one Filesystem. Each sandbox receives only the File On a trusted machine: ```bash -export TDC_FS_TOKEN="$(tdc fs create-file-system \ +export TI_FS_TOKEN="$(ti fs create-file-system \ --file-system-name agent-state \ --wait \ --query fs_token \ --output text)" ``` -Store `TDC_FS_TOKEN` in a secret manager. Also record the configured canonical region code and the Filesystem name. +Store `TI_FS_TOKEN` in a secret manager. Also record the configured canonical region code and the Filesystem name. ## Step 2. Start the first sandbox Inject the following environment variables: ```bash -export TDC_FS_TOKEN="" -export TDC_REGION_CODE="aws-us-east-1" -export TDC_FS_FILE_SYSTEM_NAME="agent-state" +export TI_FS_TOKEN="" +export TI_REGION_CODE="aws-us-east-1" +export TI_FS_FILE_SYSTEM_NAME="agent-state" ``` Write a plan and create a workflow journal: ```bash printf '%s\n' '# Plan' '1. inspect' '2. change' '3. verify' \ - | tdc fs copy-file --from-stdin --to-remote /tasks/task-42/plan.md + | ti fs copy-file --from-stdin --to-remote /tasks/task-42/plan.md -tdc fs-journal create-journal \ +ti fs-journal create-journal \ --journal-id task-42 \ --journal-kind agent \ --title "task 42" \ --actor agent:worker-1 -tdc fs-journal append-journal-entries \ +ti fs-journal append-journal-entries \ --journal-id task-42 \ --entry-json '{"type":"task.checkpoint","step":"inspection-complete"}' ``` @@ -65,8 +65,8 @@ tdc fs-journal append-journal-entries \ Inject the same three FS variables into the new sandbox, then restore the durable state: ```bash -tdc fs read-file --path /tasks/task-42/plan.md -tdc fs-journal read-journal-entries --journal-id task-42 --after-seq 0 +ti fs read-file --path /tasks/task-42/plan.md +ti fs-journal read-journal-entries --journal-id task-42 --after-seq 0 ``` Continue writing results under the same task path. Use a unique task ID so parallel agents do not overwrite each other's files. @@ -79,6 +79,6 @@ Continue writing results under the same task path. Use a unique task ID so paral ## Related reference -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/tdc/reference/tdc-filesystem-journal.md) -- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-query-sql-with-roles-example.md b/ai/ti/reference/ti-query-sql-with-roles-example.md similarity index 73% rename from ai/tdc/reference/tdc-query-sql-with-roles-example.md rename to ai/ti/reference/ti-query-sql-with-roles-example.md index 945efc1657456..fd8cccf3d2d5b 100644 --- a/ai/tdc/reference/tdc-query-sql-with-roles-example.md +++ b/ai/ti/reference/ti-query-sql-with-roles-example.md @@ -9,7 +9,7 @@ This example lets an agent perform schema, data, and verification work while mak > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem @@ -21,17 +21,17 @@ TiDB supports SQL privileges, but a conventional client session uses the privile ## How TiDB Cloud CLI changes the workflow -`tdc db create-db-sql-users` creates stable read-only, read-write, and admin identities and stores their credentials locally. Each `execute-sql-statement` invocation selects one role explicitly, uses the corresponding credential, and executes one statement. The agent can therefore use admin for schema changes, read-write for data changes, and read-only for verification without handling passwords directly. +`ti db create-db-sql-users` creates stable read-only, read-write, and admin identities and stores their credentials locally. Each `execute-sql-statement` invocation selects one role explicitly, uses the corresponding credential, and executes one statement. The agent can therefore use admin for schema changes, read-write for data changes, and read-only for verification without handling passwords directly. ## Prerequisites -- Configure `tdc`. +- Configure `ti`. - Select an active Starter cluster ID. ## Step 1. Prepare users ```bash -tdc db create-db-sql-users \ +ti db create-db-sql-users \ --db-cluster-id "" ``` @@ -40,12 +40,12 @@ The command is idempotent and creates or repairs `read_only`, `read_write`, and ## Step 2. Use admin for schema changes ```bash -tdc db execute-sql-statement \ +ti db execute-sql-statement \ --db-cluster-id "" \ --admin \ --sql "CREATE DATABASE IF NOT EXISTS role_demo" -tdc db execute-sql-statement \ +ti db execute-sql-statement \ --db-cluster-id "" \ --admin \ --database role_demo \ @@ -55,7 +55,7 @@ tdc db execute-sql-statement \ ## Step 3. Use read-write for data changes ```bash -tdc db execute-sql-statement \ +ti db execute-sql-statement \ --db-cluster-id "" \ --read-write \ --database role_demo \ @@ -65,7 +65,7 @@ tdc db execute-sql-statement \ ## Step 4. Use read-only for verification ```bash -tdc db execute-sql-statement \ +ti db execute-sql-statement \ --db-cluster-id "" \ --read-only \ --database role_demo \ @@ -81,7 +81,7 @@ Write the output directly to a protected local file instead of displaying it: ```bash umask 077 -tdc db format-db-connection-string \ +ti db format-db-connection-string \ --db-cluster-id "" \ --read-only \ --database role_demo \ @@ -94,7 +94,7 @@ Do not commit `.env.tidb`. ## Cleanup ```bash -tdc db execute-sql-statement \ +ti db execute-sql-statement \ --db-cluster-id "" \ --admin \ --sql "DROP DATABASE role_demo" @@ -105,11 +105,11 @@ rm -f .env.tidb ## Security notes - Use the least privileged explicit role for each statement. -- `tdc` accepts one SQL statement per invocation. +- `ti` accepts one SQL statement per invocation. - HTTPS is the default transport; `--transport mysql` is an explicit fallback. - Connection strings and environment output contain credentials. ## What's next -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/ti/reference/ti-regions-security-and-limitations.md similarity index 81% rename from ai/tdc/reference/tdc-regions-security-and-limitations.md rename to ai/ti/reference/ti-regions-security-and-limitations.md index 1c018a084a04c..b9c393e1a6cc9 100644 --- a/ai/tdc/reference/tdc-regions-security-and-limitations.md +++ b/ai/ti/reference/ti-regions-security-and-limitations.md @@ -9,7 +9,7 @@ This reference describes current placement, authentication, platform, and previe > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## TiDB Cloud regions @@ -43,9 +43,9 @@ The hosted manifest is authoritative and can change during preview. A profile in | Operation | Required credential | | --- | --- | -| `tdc configure`, `tdc organization`, all `tdc db` control-plane operations | TiDB Cloud API public/private key | -| `tdc fs create-file-system` | TiDB Cloud API key | -| `tdc fs delete-file-system` | TiDB Cloud API key, local resource registration, and owner resource credential | +| `ti configure`, `ti organization`, all `ti db` control-plane operations | TiDB Cloud API public/private key | +| `ti fs create-file-system` | TiDB Cloud API key | +| `ti fs delete-file-system` | TiDB Cloud API key, local resource registration, and owner resource credential | | Remote file, layer, pack, mount, Git, journal, and owner vault operations | FS owner token or registered resource credential | | Delegated vault read, list, run, or mount | Scope-appropriate delegated vault token | | Drain and unmount after a successful background mount | Non-secret mount locator in the same `HOME` | @@ -56,10 +56,10 @@ TiDB Cloud API calls use Digest authentication. SQL HTTPS execution uses generat - Create TiDB Cloud API keys with only the organization and project access required for the workflow. Do not reuse a personal administrator key in unattended automation. - Inject automation credentials from a CI secret store or runtime secret manager. Do not place credentials in source control, container images, shell scripts, or command-line arguments that can appear in process listings and shell history. -- Do not copy the complete `~/.tdc/` directory into an agent sandbox. For an existing Filesystem, pass only `TDC_FS_TOKEN`, `TDC_REGION_CODE`, and `TDC_FS_FILE_SYSTEM_NAME`. +- Do not copy the complete `~/.ti/` directory into an agent sandbox. For an existing Filesystem, pass only `TI_FS_TOKEN`, `TI_REGION_CODE`, and `TI_FS_FILE_SYSTEM_NAME`. - Treat an FS owner token as full access to that Filesystem. When an agent needs only selected secrets, create a vault grant with the narrowest field scope and shortest practical TTL, and pass the delegated vault token instead. - Use `--read-only` for SQL inspection by untrusted or exploratory agents. Use `--admin` only for DDL or privilege management, and use `--read-write` only when data changes are intended. -- Use `--dry-run` before destructive control-plane operations. Keep `~/.tdc/credentials`, resource credentials, and DB SQL credentials owner-readable only. +- Use `--dry-run` before destructive control-plane operations. Keep `~/.ti/credentials`, resource credentials, and DB SQL credentials owner-readable only. - Grant Docker access to `/dev/fuse`, `SYS_ADMIN`, and an unconfined AppArmor profile only to dedicated, trusted containers. These settings reduce container isolation. - Review local operation logs before sharing diagnostics. The logs exclude SQL text, paths, payloads, and credential values, but command names, flag names, profile and region metadata, status codes, and operational timing can still be sensitive. @@ -73,7 +73,7 @@ TiDB Cloud API calls use Digest authentication. SQL HTTPS execution uses generat FUSE and WebDAV are implemented by the bundled [Drive9](https://github.com/mem9-ai/drive9) companion. The TiDB Cloud CLI does not fall back to a separate native mount implementation. -Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path under `$HOME` or `/mnt`; `/workspace` requires an explicit local AppArmor rule even when `tdc` runs as root. +Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path under `$HOME` or `/mnt`; `/workspace` requires an explicit local AppArmor rule even when `ti` runs as root. ## Durability limitations @@ -93,11 +93,11 @@ Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path - Read-write is the default SQL role; use explicit role flags in security-sensitive automation. - Journals are append-only and the current public command surface has no journal delete command. - Filesystem resource list and describe commands operate on the local registry; they are not an organization-wide discovery API. -- Telemetry management commands are intentionally not implemented. Control telemetry through `~/.tdc/.preferences` or `TDC_TELEMETRY`; serverless-function deployment, Homebrew, and Scoop distribution are not implemented. -- The TiDB Cloud CLI depends on its installed `tdc-drive9` companion for all public Filesystem runtime behavior. +- Telemetry management commands are intentionally not implemented. Control telemetry through `~/.ti/.preferences` or `TI_TELEMETRY`; serverless-function deployment, Homebrew, and Scoop distribution are not implemented. +- The TiDB Cloud CLI depends on its installed `ti-drive9` companion for all public Filesystem runtime behavior. ## Related documentation -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) -- [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md b/ai/ti/reference/ti-share-filesystem-across-machines-example.md similarity index 74% rename from ai/tdc/reference/tdc-share-filesystem-across-machines-example.md rename to ai/ti/reference/ti-share-filesystem-across-machines-example.md index 38a8f9a91a9bd..06fe227956da1 100644 --- a/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md +++ b/ai/ti/reference/ti-share-filesystem-across-machines-example.md @@ -9,7 +9,7 @@ This example gives agents or users on two machines one shared workspace without > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem @@ -25,20 +25,20 @@ Both machines select the same TiDB Cloud Filesystem. Data-plane commands and the ## Prerequisites -- Machine A has configured `tdc`. -- Both machines have `tdc` installed. +- Machine A has configured `ti`. +- Both machines have `ti` installed. - You have a secure secret-transfer channel. ## Step 1. Create the Filesystem on machine A ```bash -export TDC_FS_TOKEN="$(tdc fs create-file-system \ +export TI_FS_TOKEN="$(ti fs create-file-system \ --file-system-name shared-workspace \ --wait \ --query fs_token \ --output text)" -printf 'from machine A\n' | tdc fs copy-file \ +printf 'from machine A\n' | ti fs copy-file \ --file-system-name shared-workspace \ --from-stdin \ --to-remote /shared/origin.txt @@ -49,31 +49,31 @@ Transfer the token through a secret manager. Also communicate the canonical regi ## Step 2. Configure machine B in memory ```bash -export TDC_FS_TOKEN="" -export TDC_REGION_CODE="aws-us-east-1" -export TDC_FS_FILE_SYSTEM_NAME="shared-workspace" +export TI_FS_TOKEN="" +export TI_REGION_CODE="aws-us-east-1" +export TI_FS_FILE_SYSTEM_NAME="shared-workspace" ``` -No `tdc configure` is required. +No `ti configure` is required. ## Step 3. Verify direct visibility on machine B ```bash -tdc fs read-file --path /shared/origin.txt -printf 'from machine B\n' | tdc fs copy-file --from-stdin --to-remote /shared/second.txt +ti fs read-file --path /shared/origin.txt +printf 'from machine B\n' | ti fs copy-file --from-stdin --to-remote /shared/second.txt ``` ## Step 4. Verify mount and data-plane visibility ```bash mkdir -p /path/to/shared-workspace -tdc fs mount-file-system \ +ti fs mount-file-system \ --file-system-name shared-workspace \ --mount-path /path/to/shared-workspace cat /path/to/shared-workspace/shared/origin.txt printf 'written through mount\n' > /path/to/shared-workspace/shared/mounted.txt -tdc fs read-file --path /shared/mounted.txt +ti fs read-file --path /shared/mounted.txt ``` The first read proves data-plane writes are visible through the mount. The final read proves mount writes are visible through the data plane after they are flushed. @@ -83,14 +83,14 @@ The first read proves data-plane writes are visible through the mount. The final Stop writers and unmount either driver. A graceful FUSE unmount automatically drains pending work: ```bash -tdc fs unmount-file-system --mount-path /path/to/shared-workspace -unset TDC_FS_TOKEN TDC_REGION_CODE TDC_FS_FILE_SYSTEM_NAME +ti fs unmount-file-system --mount-path /path/to/shared-workspace +unset TI_FS_TOKEN TI_REGION_CODE TI_FS_FILE_SYSTEM_NAME ``` On machine A: ```bash -tdc fs delete-file-system \ +ti fs delete-file-system \ --file-system-name shared-workspace ``` @@ -102,5 +102,5 @@ tdc fs delete-file-system \ ## What's next -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [Use a Filesystem in an Agent Sandbox](/ai/tdc/reference/tdc-agent-sandbox-example.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [Use a Filesystem in an Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) diff --git a/ai/tdc/reference/tdc-starter-database.md b/ai/ti/reference/ti-starter-database.md similarity index 57% rename from ai/tdc/reference/tdc-starter-database.md rename to ai/ti/reference/ti-starter-database.md index 87c9ec9e87b35..9b69d4a2767d7 100644 --- a/ai/tdc/reference/tdc-starter-database.md +++ b/ai/ti/reference/ti-starter-database.md @@ -1,20 +1,20 @@ --- title: TiDB Cloud Starter CLI Command Reference -summary: Reference every `tdc db` command for Starter clusters, branches, SQL users, connection strings, and SQL execution. +summary: Reference every `ti db` command for Starter clusters, branches, SQL users, connection strings, and SQL execution. --- # TiDB Cloud Starter CLI Command Reference -Use `tdc db` to manage TiDB Cloud Starter clusters, branches, and SQL access. The TiDB Cloud CLI validates the cluster service plan before every cluster-scoped operation and rejects Essential or unverifiable clusters before continuing. +Use `ti db` to manage TiDB Cloud Starter clusters, branches, and SQL access. The TiDB Cloud CLI validates the cluster service plan before every cluster-scoped operation and rejects Essential or unverifiable clusters before continuing. > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## Command tree ```text -tdc db +ti db ├── create-db-cluster ├── list-db-clusters ├── describe-db-cluster @@ -33,22 +33,22 @@ tdc db | Command | Purpose and key inputs | Example | | --- | --- | --- | -| `create-db-cluster` | Creates a Starter cluster. Requires `--db-cluster-type starter` and `--db-cluster-name`. Use `--wait` for an `ACTIVE` result. | `tdc db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --wait` | -| `list-db-clusters` | Lists Starter clusters in the effective region. Requires `--db-cluster-type starter` and supports pagination, filtering, ordering, and queries. | `tdc db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name}'` | -| `describe-db-cluster` | Reads one cluster by `--db-cluster-id`; `--view FULL` requests expanded fields. | `tdc db describe-db-cluster --db-cluster-id "" --view FULL` | -| `update-db-cluster` | Changes the name or monthly spending limit of one cluster. Supports `--dry-run`. | `tdc db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2` | -| `delete-db-cluster` | Deletes one cluster by ID. Use `--wait` to wait until deletion is observable. | `tdc db delete-db-cluster --db-cluster-id "" --wait` | -| `create-db-cluster-branch` | Creates a branch from a cluster. Requires cluster ID and branch name; supports `--wait`. | `tdc db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name dev --wait` | -| `list-db-cluster-branches` | Lists branches for one cluster with pagination. | `tdc db list-db-cluster-branches --db-cluster-id "" --output text` | -| `describe-db-cluster-branch` | Reads one branch by cluster ID and branch ID. | `tdc db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id ""` | -| `delete-db-cluster-branch` | Deletes one branch. Supports `--dry-run`. | `tdc db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id ""` | -| `create-db-sql-users` | Idempotently creates or repairs read-only, read-write, and admin users for one cluster. | `tdc db create-db-sql-users --db-cluster-id ""` | -| `format-db-connection-string` | Formats stored SQL credentials as a MySQL URI, JDBC, Go, SQLAlchemy, or environment output. | `tdc db format-db-connection-string --db-cluster-id "" --read-only --format env` | -| `execute-sql-statement` | Executes exactly one statement using read-write by default or an explicit SQL role. | `tdc db execute-sql-statement --db-cluster-id "" --read-only --sql "SELECT 1"` | +| `create-db-cluster` | Creates a Starter cluster. Requires `--db-cluster-type starter` and `--db-cluster-name`. Use `--wait` for an `ACTIVE` result. | `ti db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --wait` | +| `list-db-clusters` | Lists Starter clusters in the effective region. Requires `--db-cluster-type starter` and supports pagination, filtering, ordering, and queries. | `ti db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name}'` | +| `describe-db-cluster` | Reads one cluster by `--db-cluster-id`; `--view FULL` requests expanded fields. | `ti db describe-db-cluster --db-cluster-id "" --view FULL` | +| `update-db-cluster` | Changes the name or monthly spending limit of one cluster. Supports `--dry-run`. | `ti db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2` | +| `delete-db-cluster` | Deletes one cluster by ID. Use `--wait` to wait until deletion is observable. | `ti db delete-db-cluster --db-cluster-id "" --wait` | +| `create-db-cluster-branch` | Creates a branch from a cluster. Requires cluster ID and branch name; supports `--wait`. | `ti db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name dev --wait` | +| `list-db-cluster-branches` | Lists branches for one cluster with pagination. | `ti db list-db-cluster-branches --db-cluster-id "" --output text` | +| `describe-db-cluster-branch` | Reads one branch by cluster ID and branch ID. | `ti db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id ""` | +| `delete-db-cluster-branch` | Deletes one branch. Supports `--dry-run`. | `ti db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id ""` | +| `create-db-sql-users` | Idempotently creates or repairs read-only, read-write, and admin users for one cluster. | `ti db create-db-sql-users --db-cluster-id ""` | +| `format-db-connection-string` | Formats stored SQL credentials as a MySQL URI, JDBC, Go, SQLAlchemy, or environment output. | `ti db format-db-connection-string --db-cluster-id "" --read-only --format env` | +| `execute-sql-statement` | Executes exactly one statement using read-write by default or an explicit SQL role. | `ti db execute-sql-statement --db-cluster-id "" --read-only --sql "SELECT 1"` | ## Prerequisites -- Configure `tdc` with `tdc configure`. +- Configure `ti` with `ti configure`. - Ensure the API key can manage Starter clusters in the selected project. - Use synthetic names in automation so cleanup can identify only resources created by that run. @@ -57,12 +57,12 @@ tdc db Preview and create a Starter cluster: ```bash -tdc db create-db-cluster \ +ti db create-db-cluster \ --db-cluster-type starter \ --db-cluster-name demo-cluster \ --dry-run -tdc db create-db-cluster \ +ti db create-db-cluster \ --db-cluster-type starter \ --db-cluster-name demo-cluster ``` @@ -72,22 +72,22 @@ An explicit `--project-id` overrides the configured virtual project. If neither List and filter clusters: ```bash -tdc db list-db-clusters --db-cluster-type starter -tdc db list-db-clusters --db-cluster-type starter --page-size 20 --order-by "createTime desc" -tdc db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name,state:state}' -tdc --region aws-us-west-2 db list-db-clusters --db-cluster-type starter +ti db list-db-clusters --db-cluster-type starter +ti db list-db-clusters --db-cluster-type starter --page-size 20 --order-by "createTime desc" +ti db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name,state:state}' +ti --region aws-us-west-2 db list-db-clusters --db-cluster-type starter ``` -The list command also accepts `--page-token` and `--filter`. It always scopes the API request to the effective region, which resolves from global `--region`, then `TDC_REGION_CODE`, then the selected profile. The shared TiDB Cloud API can return multiple service plans or unverifiable resources, so the TiDB Cloud CLI scans upstream pages and incrementally fills a tdc result page with verified Starter clusters in that region. Its opaque `next_page_token` binds the profile, type, region, filter, and ordering; it omits `total_size`, because the server total can include clusters outside the verified result. A user `--filter` is combined with the mandatory region filter and cannot expand the result to another region. +The list command also accepts `--page-token` and `--filter`. It always scopes the API request to the effective region, which resolves from global `--region`, then `TI_REGION_CODE`, then the selected profile. The shared TiDB Cloud API can return multiple service plans or unverifiable resources, so the TiDB Cloud CLI scans upstream pages and incrementally fills a ti result page with verified Starter clusters in that region. Its opaque `next_page_token` binds the profile, type, region, filter, and ordering; it omits `total_size`, because the server total can include clusters outside the verified result. A user `--filter` is combined with the mandatory region filter and cannot expand the result to another region. Describe and update a cluster: ```bash -tdc db describe-db-cluster \ +ti db describe-db-cluster \ --db-cluster-id "" \ --view FULL -tdc db update-db-cluster \ +ti db update-db-cluster \ --db-cluster-id "" \ --db-cluster-name demo-cluster-renamed ``` @@ -97,16 +97,16 @@ An update must include a new name or spending limit. Preview mutating commands w Delete a cluster: ```bash -tdc db delete-db-cluster \ +ti db delete-db-cluster \ --db-cluster-id "" \ --dry-run -tdc db delete-db-cluster \ +ti db delete-db-cluster \ --db-cluster-id "" \ --wait ``` -`tdc` resolves the cluster name internally; no name-confirmation flag is required. Without `--wait`, delete returns after TiDB Cloud accepts the asynchronous request. The wait flag waits up to 12 minutes and returns when the cluster is `DELETED` or no longer accessible. +`ti` resolves the cluster name internally; no name-confirmation flag is required. Without `--wait`, delete returns after TiDB Cloud accepts the asynchronous request. The wait flag waits up to 12 minutes and returns when the cluster is `DELETED` or no longer accessible. ## Manage branches @@ -115,12 +115,12 @@ Every branch command verifies that the parent cluster is Starter before calling Create and list branches: ```bash -tdc db create-db-cluster-branch \ +ti db create-db-cluster-branch \ --db-cluster-id "" \ --db-cluster-branch-name development \ --wait -tdc db list-db-cluster-branches \ +ti db list-db-cluster-branches \ --db-cluster-id "" \ --page-size 20 ``` @@ -130,12 +130,12 @@ Use `--page-token` to continue a paginated branch list. Without `--wait`, branch Describe and delete a branch: ```bash -tdc db describe-db-cluster-branch \ +ti db describe-db-cluster-branch \ --db-cluster-id "" \ --db-cluster-branch-id "" \ --view FULL -tdc db delete-db-cluster-branch \ +ti db delete-db-cluster-branch \ --db-cluster-id "" \ --db-cluster-branch-id "" ``` @@ -149,11 +149,11 @@ SQL access commands verify that the target cluster is Starter before reading or Create or repair the three TiDB Cloud CLI-managed SQL roles: ```bash -tdc db create-db-sql-users \ +ti db create-db-sql-users \ --db-cluster-id "" ``` -The operation is idempotent. It reuses stable role names and stores generated credentials under `~/.tdc/db_users//credentials`. It creates: +The operation is idempotent. It reuses stable role names and stores generated credentials under `~/.ti/db_users//credentials`. It creates: - `read_only`; - `read_write`; @@ -162,7 +162,7 @@ The operation is idempotent. It reuses stable role names and stores generated cr Preview the operation without changing users: ```bash -tdc db create-db-sql-users \ +ti db create-db-sql-users \ --db-cluster-id "" \ --dry-run ``` @@ -172,19 +172,19 @@ tdc db create-db-sql-users \ Read-write is the default, but explicit role selection is recommended: ```bash -tdc db format-db-connection-string \ +ti db format-db-connection-string \ --db-cluster-id "" \ --read-write \ --database app \ --format mysql-uri -tdc db format-db-connection-string \ +ti db format-db-connection-string \ --db-cluster-id "" \ --read-only \ --format env \ --env-prefix TIDB_ -tdc db format-db-connection-string \ +ti db format-db-connection-string \ --db-cluster-id "" \ --admin \ --format jdbc @@ -201,20 +201,20 @@ Supported formats are `mysql-uri`, `jdbc`, `go-sql-driver`, `sqlalchemy`, and `e Each invocation accepts exactly one SQL statement. Use an explicit role: ```bash -tdc db execute-sql-statement \ +ti db execute-sql-statement \ --db-cluster-id "" \ --read-only \ --database app \ --sql "SELECT COUNT(*) AS row_count FROM messages" \ --output text -tdc db execute-sql-statement \ +ti db execute-sql-statement \ --db-cluster-id "" \ --read-write \ --database app \ --sql "INSERT INTO messages(id, body) VALUES (1, 'hello')" -tdc db execute-sql-statement \ +ti db execute-sql-statement \ --db-cluster-id "" \ --admin \ --sql "CREATE DATABASE IF NOT EXISTS app" @@ -224,6 +224,6 @@ The default `--transport https` sends the SQL request over HTTPS without a persi ## What's next -- [Query SQL with Explicit Roles](/ai/tdc/reference/tdc-query-sql-with-roles-example.md) -- [TiDB Cloud CLI Command Reference](/ai/tdc/reference/tdc-cli-reference.md) -- [Troubleshoot TiDB Cloud CLI](/ai/tdc/reference/tdc-troubleshooting.md) +- [Query SQL with Explicit Roles](/ai/ti/reference/ti-query-sql-with-roles-example.md) +- [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-troubleshooting.md b/ai/ti/reference/ti-troubleshooting.md similarity index 69% rename from ai/tdc/reference/tdc-troubleshooting.md rename to ai/ti/reference/ti-troubleshooting.md index 238b351992435..5591421e00e88 100644 --- a/ai/tdc/reference/tdc-troubleshooting.md +++ b/ai/ti/reference/ti-troubleshooting.md @@ -9,7 +9,7 @@ Use this reference to diagnose common current TiDB Cloud CLI failures. Add `--de > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## API authentication fails @@ -18,39 +18,39 @@ Symptoms include missing credentials, Digest authentication failure, or permissi Check that both environment values are set together: ```bash -test -n "$TDC_PUBLIC_KEY" -test -n "$TDC_PRIVATE_KEY" +test -n "$TIDB_CLOUD_PUBLIC_KEY" +test -n "$TIDB_CLOUD_PRIVATE_KEY" ``` If you intend to use saved credentials, unset both variables and verify the profile: ```bash -unset TDC_PUBLIC_KEY TDC_PRIVATE_KEY -tdc organization list-projects --profile default +unset TIDB_CLOUD_PUBLIC_KEY TIDB_CLOUD_PRIVATE_KEY +ti organization list-projects --profile default ``` An API key can authenticate successfully but still lack the permission declared by a command. Use a key with the required organization or project access. ## Configure cannot find a virtual project -`tdc configure` requires exactly one accessible project whose `type` is `tidbx_virtual`. +`ti configure` requires exactly one accessible project whose `type` is `tidbx_virtual`. ```bash -tdc organization list-projects \ +ti organization list-projects \ --query 'projects[].{id:id,name:name,type:type}' ``` -If no virtual project appears, confirm the API key's organization and project access. If multiple virtual projects appear, report the ambiguous account state through the [`tdc` issue tracker](https://github.com/tidbcloud/tdc/issues). +If no virtual project appears, confirm the API key's organization and project access. If multiple virtual projects appear, report the ambiguous account state through the [`ti` issue tracker](https://github.com/tidbcloud/ti-cli/issues). ## Filesystem token is missing For a clean sandbox, provide all three values: ```bash -export TDC_FS_TOKEN="" -export TDC_REGION_CODE="aws-us-east-1" -export TDC_FS_FILE_SYSTEM_NAME="workspace" -tdc fs check-file-system +export TI_FS_TOKEN="" +export TI_REGION_CODE="aws-us-east-1" +export TI_FS_FILE_SYSTEM_NAME="workspace" +ti fs check-file-system ``` The FS token is not the TiDB Cloud API private key. @@ -60,35 +60,35 @@ The FS token is not the TiDB Cloud API private key. List registered resources and select one explicitly: ```bash -tdc fs list-file-systems --output text -tdc fs list-files --file-system-name workspace --path / +ti fs list-file-systems --output text +ti fs list-files --file-system-name workspace --path / ``` Or select the Filesystem for subsequent commands in the current shell: ```bash -export TDC_FS_FILE_SYSTEM_NAME="workspace" +export TI_FS_FILE_SYSTEM_NAME="workspace" ``` The TiDB Cloud CLI intentionally does not infer a Filesystem from the local registry, including when only one resource is registered. ## Filesystem region is unsupported -The configured TiDB Cloud region might not have a `tidb_cloud_native` Filesystem endpoint. Compare it with [current Filesystem regions](/ai/tdc/reference/tdc-regions-security-and-limitations.md#filesystem-regions). Change placement with a valid profile or command-scoped `--region`; do not configure a raw server URL. +The configured TiDB Cloud region might not have a `tidb_cloud_native` Filesystem endpoint. Compare it with [current Filesystem regions](/ai/ti/reference/ti-regions-security-and-limitations.md#filesystem-regions). Change placement with a valid profile or command-scoped `--region`; do not configure a raw server URL. ## Companion is missing or incompatible -The release installer places `tdc-drive9` next to `tdc`. Re-run the current installer when the TiDB Cloud CLI reports a missing companion: +The release installer places `ti-drive9` next to `ti`. Re-run the current installer when the TiDB Cloud CLI reports a missing companion: ```bash -curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes +curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh -s -- --yes ``` -Verify that `PATH` resolves the expected `tdc`: +Verify that `PATH` resolves the expected `ti`: ```bash -command -v tdc -tdc --version +command -v ti +ti --version ``` Do not copy an arbitrary standalone Drive9 binary into place. @@ -98,8 +98,8 @@ Do not copy an arbitrary standalone Drive9 binary into place. Quota and capacity errors can mean the organization has reached its free Starter limit. List existing resources before creating another: ```bash -tdc db list-db-clusters --db-cluster-type starter --output text -tdc fs list-file-systems --output text +ti db list-db-clusters --db-cluster-type starter --output text +ti fs list-file-systems --output text ``` Never delete an unrelated resource to make automation pass. A Starter spending limit can require configured billing. @@ -109,19 +109,19 @@ Never delete an unrelated resource to make automation pass. A Starter spending l Prepare or repair users for the exact cluster: ```bash -tdc db create-db-sql-users --db-cluster-id "" +ti db create-db-sql-users --db-cluster-id "" ``` Then retry with an explicit role: ```bash -tdc db execute-sql-statement \ +ti db execute-sql-statement \ --db-cluster-id "" \ --read-only \ --sql "SELECT 1" ``` -Deleting `~/.tdc/db_users//credentials` removes local passwords. Run the create/repair command rather than inventing credentials. +Deleting `~/.ti/db_users//credentials` removes local passwords. Run the create/repair command rather than inventing credentials. ## Mount does not become ready @@ -136,7 +136,7 @@ Inspect the log path printed by the timeout error. Confirm: macOS defaults to WebDAV. To request FUSE after installing macFUSE: ```bash -tdc fs mount-file-system \ +ti fs mount-file-system \ --mount-path /path/to/workspace \ --driver fuse ``` @@ -162,17 +162,17 @@ An entry with `operation="mount"`, `name="/workspace/"`, and `info="failed mntpn ```bash mkdir -p "$HOME/workspace" -tdc fs mount-file-system --mount-path "$HOME/workspace" +ti fs mount-file-system --mount-path "$HOME/workspace" ``` -Changing the owner or mode of `/workspace` does not bypass AppArmor. If the path cannot change, add explicit `/workspace` mount and unmount rules to `/etc/apparmor.d/local/fusermount3` as described in [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md#ubuntu-2604-mount-paths). +Changing the owner or mode of `/workspace` does not bypass AppArmor. If the path cannot change, add explicit `/workspace` mount and unmount rules to `/etc/apparmor.d/local/fusermount3` as described in [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md#ubuntu-2604-mount-paths). ## Mount becomes stale after a process crash If the companion is killed without graceful unmount, FUSE access can return `EIO` or `Transport endpoint is not connected`. Stop processes with open files, then try: ```bash -tdc fs unmount-file-system \ +ti fs unmount-file-system \ --mount-path /path/to/workspace \ --force ``` @@ -184,7 +184,7 @@ Use `--ignore-absent` when cleanup should succeed if no locator remains. Abrupt Close editors, shells whose working directory is inside the mount, and other open file handles, and then retry: ```bash -tdc fs unmount-file-system --mount-path /path/to/workspace +ti fs unmount-file-system --mount-path /path/to/workspace ``` Unmount performs the graceful FUSE drain automatically. Running `drain-file-system` separately does not close file descriptors or resolve a busy mount; use it only when you need to flush pending work while leaving the mount online. Drain is not supported for WebDAV. @@ -194,19 +194,19 @@ Unmount performs the graceful FUSE drain automatically. Running `drain-file-syst List resources and identify only those created by your workflow. Use describe before delete: ```bash -tdc db describe-db-cluster --db-cluster-id "" -tdc fs describe-file-system --file-system-name "" +ti db describe-db-cluster --db-cluster-id "" +ti fs describe-file-system --file-system-name "" ``` Preview supported cleanup: ```bash -tdc db delete-db-cluster --db-cluster-id "" --dry-run -tdc fs delete-file-system \ +ti db delete-db-cluster --db-cluster-id "" --dry-run +ti fs delete-file-system \ --file-system-name "" \ --dry-run ``` ## Report a problem -Include the TiDB Cloud CLI version, OS and architecture, command name, stable error code, and redacted logs. Never include API keys, FS or vault tokens, DB passwords, SQL containing private data, or file contents. Report issues at [github.com/tidbcloud/tdc/issues](https://github.com/tidbcloud/tdc/issues). +Include the TiDB Cloud CLI version, OS and architecture, command name, stable error code, and redacted logs. Never include API keys, FS or vault tokens, DB passwords, SQL containing private data, or file contents. Report issues at [github.com/tidbcloud/ti-cli/issues](https://github.com/tidbcloud/ti-cli/issues). diff --git a/ai/tdc/reference/tdc-vault-agent-secrets-example.md b/ai/ti/reference/ti-vault-agent-secrets-example.md similarity index 82% rename from ai/tdc/reference/tdc-vault-agent-secrets-example.md rename to ai/ti/reference/ti-vault-agent-secrets-example.md index 0524b862eea17..00f31cf949f31 100644 --- a/ai/tdc/reference/tdc-vault-agent-secrets-example.md +++ b/ai/ti/reference/ti-vault-agent-secrets-example.md @@ -9,7 +9,7 @@ This example gives an agent temporary access to one secret field without sharing > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## The agent problem @@ -31,7 +31,7 @@ The Filesystem owner stores the secret once and creates a short-lived grant scop ## Step 1. Create a secret ```bash -tdc fs-vault create-secret \ +ti fs-vault create-secret \ --secret-name service-demo \ --field ENDPOINT=https://service.example \ --field API_TOKEN=@./api-token.txt @@ -40,7 +40,7 @@ tdc fs-vault create-secret \ ## Step 2. Create a narrow grant ```bash -export TDC_VAULT_TOKEN="$(tdc fs-vault create-grant \ +export TI_VAULT_TOKEN="$(ti fs-vault create-grant \ --agent-id example-agent \ --scope service-demo/ENDPOINT \ --permission read \ @@ -54,7 +54,7 @@ Record the returned grant ID from the structured create result in a real workflo ## Step 3. Use the delegated field ```bash -tdc fs-vault read-secret \ +ti fs-vault read-secret \ --secret-name service-demo \ --field ENDPOINT \ --format raw @@ -63,7 +63,7 @@ tdc fs-vault read-secret \ Inject the allowed fields into a command: ```bash -tdc fs-vault run-with-secret \ +ti fs-vault run-with-secret \ --secret-path /n/vault/service-demo \ -- sh -c 'test -n "$ENDPOINT"' ``` @@ -73,12 +73,12 @@ The process exits successfully when the permitted field is present. Do not use c ## Step 4. Audit and revoke ```bash -tdc fs-vault list-audit-events \ +ti fs-vault list-audit-events \ --secret-name service-demo \ --agent-id example-agent \ --limit 20 -tdc fs-vault delete-grant \ +ti fs-vault delete-grant \ --grant-id "" \ --revoked-by operator \ --reason task-complete @@ -87,13 +87,13 @@ tdc fs-vault delete-grant \ Unset the local token: ```bash -unset TDC_VAULT_TOKEN +unset TI_VAULT_TOKEN ``` ## Cleanup ```bash -tdc fs-vault delete-secret --secret-name service-demo +ti fs-vault delete-secret --secret-name service-demo rm -f ./api-token.txt ``` @@ -105,5 +105,5 @@ rm -f ./api-token.txt ## What's next -- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/tdc/reference/tdc-filesystem-vault.md) -- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/ti/ti-overview.md b/ai/ti/ti-overview.md new file mode 100644 index 0000000000000..38982ab78b964 --- /dev/null +++ b/ai/ti/ti-overview.md @@ -0,0 +1,102 @@ +--- +title: TiDB Cloud Command Line Interface Overview +summary: Learn when to use the TiDB Cloud CLI to manage TiDB Cloud Starter databases and persistent Filesystems for users, automation, and AI agents. +--- + +# 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. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## 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. + +| Interface | Use it for | Interaction model | +| --- | --- | --- | +| `ti` (Preview) | New TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows | Predictable commands, JSON output by default, and non-interactive operation except for `ti configure` | +| `ticloud` | TiDB Cloud Essential and operations not available in the TiDB Cloud CLI, such as import, export, and audit-log commands | Traditional CLI workflows with interactive and non-interactive modes | +| TiDB Cloud console | Visual resource inspection, guided setup, and manual operations | Browser-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: + +```text +ti +``` + +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 CLI and Drive9 + +The TiDB Cloud CLI installs a bundled [Drive9](https://github.com/mem9-ai/drive9) companion named `ti-drive9`. The TiDB Cloud CLI owns profile selection, TiDB Cloud credentials, region and Filesystem selection, output formatting, and `ti` error behavior. The companion owns Filesystem data-plane semantics, FUSE and WebDAV mounts, layers, pack and unpack, Git workspace acceleration, journals, and vault operations. + +You do not need to install, configure, or invoke Drive9 separately for normal TiDB Cloud CLI workflows. + +## Find the right documentation + +Follow the [Quick Start](/ai/ti/ti-quick-start.md) to install the TiDB Cloud CLI and complete your first Starter or Filesystem workflow. Use these guides for task-oriented instructions: + +- [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) +- [TiDB Cloud Organization CLI Command Reference](/ai/ti/reference/ti-organization.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) + +### Scenario references + +Use scenarios to follow a complete workflow that combines multiple commands and features: + +For users and automation: + +- [Run a Daily TiDB Cloud CLI Workflow](/ai/ti/reference/ti-daily-workflow-example.md) +- [Query SQL with Explicit Roles](/ai/ti/reference/ti-query-sql-with-roles-example.md) +- [Share a Filesystem Across Machines](/ai/ti/reference/ti-share-filesystem-across-machines-example.md) +- [Hand Off CI Artifacts Between Jobs](/ai/ti/reference/ti-ci-artifact-handoff-example.md) + +For AI agents: + +- [Use a Filesystem in an Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) +- [Persist Agent State Across Sandboxes](/ai/ti/reference/ti-persistent-agent-state-example.md) +- [Share a Read-Only Dataset Across Parallel Agents](/ai/ti/reference/ti-parallel-agent-dataset-example.md) +- [Prepare a Git Workspace for Agents](/ai/ti/reference/ti-git-workspace-for-agents-example.md) +- [Record an Agent Workflow in a Journal](/ai/ti/reference/ti-journal-agent-workflow-example.md) +- [Delegate Secrets to an Agent](/ai/ti/reference/ti-vault-agent-secrets-example.md) + +### Reference + +- [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) + +To report a problem or suggest an improvement, create an issue in the [TiDB Cloud CLI GitHub repository](https://github.com/tidbcloud/ti-cli/issues). diff --git a/ai/tdc/tdc-quick-start.md b/ai/ti/ti-quick-start.md similarity index 59% rename from ai/tdc/tdc-quick-start.md rename to ai/ti/ti-quick-start.md index 5dd4814164f37..4c677967e8ce1 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -9,7 +9,7 @@ This quick start installs the TiDB Cloud CLI, configures one profile, and gets a > **Note:** > -> The TiDB Cloud Command Line Interface — `tdc` — is currently in preview. Its features and command-line interface might change without prior notice. +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. ## When to use this quick start @@ -24,41 +24,41 @@ Before you begin, obtain a TiDB Cloud API public key and private key from the [T On macOS or Linux, run the installer: ```bash -curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes +curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh -s -- --yes ``` -After installation, add `tdc` to the current shell and verify it: +After installation, add `ti` to the current shell and verify it: ```bash -export PATH="$HOME/.tdc/bin:$PATH" -tdc --version +export PATH="$HOME/.ti/bin:$PATH" +ti --version ``` -Add `export PATH="$HOME/.tdc/bin:$PATH"` to your shell profile to keep `tdc` available in new terminals. +Add `export PATH="$HOME/.ti/bin:$PATH"` to your shell profile to keep `ti` available in new terminals. On Windows PowerShell, run the installer: ```powershell -$script = "$env:TEMP\install-tdc.ps1" -iwr https://github.com/tidbcloud/tdc/releases/latest/download/install.ps1 -OutFile $script +$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 ``` -After installation, add `tdc` to the current PowerShell session and verify it: +After installation, add `ti` to the current PowerShell session and verify it: ```powershell -$env:Path = "$HOME\.tdc\bin;$env:Path" -tdc --version +$env:Path = "$HOME\.ti\bin;$env:Path" +ti --version ``` -Add `$HOME\.tdc\bin` to your user `PATH` to keep `tdc` available in new PowerShell sessions. +Add `$HOME\.ti\bin` to your user `PATH` to keep `ti` available in new PowerShell sessions. ## Step 2. Configure TiDB Cloud CLI Run the interactive configuration: ```bash -tdc configure +ti configure ``` Enter your API public key, private key, and a canonical region code such as `aws-us-east-1`. @@ -66,7 +66,7 @@ Enter your API public key, private key, and a canonical region code such as `aws Verify the configuration: ```bash -tdc organization list-projects --output text +ti organization list-projects --output text ``` ## Step 3. Choose a first workflow @@ -78,21 +78,21 @@ Complete either the Filesystem workflow or the Starter database workflow. Create a Filesystem and wait until it is ready: ```bash -tdc fs create-file-system \ +ti fs create-file-system \ --file-system-name quickstart-fs \ --wait \ --output text ``` -`tdc` stores the Filesystem credential locally. Write and read a file directly: +`ti` stores the Filesystem credential locally. Write and read a file directly: ```bash -printf 'hello from tdc\n' | tdc fs copy-file \ +printf 'hello from ti\n' | ti fs copy-file \ --file-system-name quickstart-fs \ --from-stdin \ --to-remote /hello.txt -tdc fs read-file \ +ti fs read-file \ --file-system-name quickstart-fs \ --path /hello.txt ``` @@ -100,13 +100,13 @@ tdc fs read-file \ Expected output: ```text -hello from tdc +hello from ti ``` Clean up: ```bash -tdc fs delete-file-system \ +ti fs delete-file-system \ --file-system-name quickstart-fs ``` @@ -115,7 +115,7 @@ tdc fs delete-file-system \ Create a Starter cluster and save its ID: ```bash -export TDC_DB_CLUSTER_ID="$(tdc db create-db-cluster \ +export TI_DB_CLUSTER_ID="$(ti db create-db-cluster \ --db-cluster-type starter \ --db-cluster-name quickstart-db \ --wait \ @@ -126,11 +126,11 @@ export TDC_DB_CLUSTER_ID="$(tdc db create-db-cluster \ Create the SQL users and run a read-only verification query: ```bash -tdc db create-db-sql-users \ - --db-cluster-id "$TDC_DB_CLUSTER_ID" +ti db create-db-sql-users \ + --db-cluster-id "$TI_DB_CLUSTER_ID" -tdc db execute-sql-statement \ - --db-cluster-id "$TDC_DB_CLUSTER_ID" \ +ti db execute-sql-statement \ + --db-cluster-id "$TI_DB_CLUSTER_ID" \ --read-only \ --sql "SELECT 1 AS ready" \ --output text @@ -141,14 +141,14 @@ The command executes one statement through the HTTPS SQL API and returns a resul Clean up: ```bash -tdc db delete-db-cluster \ - --db-cluster-id "$TDC_DB_CLUSTER_ID" \ +ti db delete-db-cluster \ + --db-cluster-id "$TI_DB_CLUSTER_ID" \ --wait -unset TDC_DB_CLUSTER_ID +unset TI_DB_CLUSTER_ID ``` ## What's next -- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md) -- [TiDB Cloud Filesystem CLI Command Reference](/ai/tdc/reference/tdc-filesystem.md) -- [TiDB Cloud CLI Configuration and Credentials](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/tidb-cloud/cli-reference.md b/tidb-cloud/cli-reference.md index f7f63a4262b6e..af87e74fdb990 100644 --- a/tidb-cloud/cli-reference.md +++ b/tidb-cloud/cli-reference.md @@ -11,7 +11,7 @@ summary: Provides an overview of the ticloud CLI for TiDB Cloud Starter and Esse > **Note:** > -> `ticloud` is the TiDB Cloud CLI for Essential. tdc does not replace `ticloud` for Essential. For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use the [`tdc` CLI](/ai/tdc/tdc-overview.md). Continue to use `ticloud` for Essential and for operations that tdc does not provide, such as import, export, and audit-log commands. +> `ticloud` is the TiDB Cloud CLI for Essential. `ti` does not replace `ticloud` for Essential. For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use the [TiDB Cloud Command Line Interface](/ai/ti/ti-overview.md). Continue to use `ticloud` for Essential and for operations that `ti` does not provide, such as import, export, and audit-log commands. The `ticloud` CLI is a command-line interface that lets you operate TiDB Cloud from your terminal. It manages {{{ .starter }}} and Essential instances, imports and exports data, and supports other CLI workflows. diff --git a/tidb-cloud/get-started-with-cli.md b/tidb-cloud/get-started-with-cli.md index affe2208a89a8..42635ff3a8417 100644 --- a/tidb-cloud/get-started-with-cli.md +++ b/tidb-cloud/get-started-with-cli.md @@ -7,7 +7,7 @@ summary: Learn how to manage {{{ .starter }}} and Essential instances through th > **Note:** > -> `ticloud` is the TiDB Cloud CLI for Essential. tdc does not replace `ticloud` for Essential. For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use the [`tdc` CLI](/ai/tdc/tdc-overview.md). Continue to use `ticloud` for Essential and for operations that tdc does not provide, such as import, export, and audit-log commands. +> `ticloud` is the TiDB Cloud CLI for Essential. `ti` does not replace `ticloud` for Essential. For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use the [TiDB Cloud Command Line Interface](/ai/ti/ti-overview.md). Continue to use `ticloud` for Essential and for operations that `ti` does not provide, such as import, export, and audit-log commands. TiDB Cloud provides the command-line interface (CLI) [`ticloud`](https://github.com/tidbcloud/tidbcloud-cli) for you to interact with TiDB Cloud Starter and Essential from your terminal with a few lines of commands. For example, you can perform the following operations using `ticloud`: From dec494786c02a88efe2e79d9184ef065b8e0c8be Mon Sep 17 00:00:00 2001 From: Cheese Date: Tue, 11 Aug 2026 16:58:02 +0800 Subject: [PATCH 27/29] docs: remove TiDB Cloud project selection --- TOC-ai.md | 3 - ai/_index.md | 1 - .../commands/db/ti-db-create-db-cluster.md | 11 +-- .../ti-organization-list-projects.md | 51 ------------- ai/ti/reference/ti-cli-reference.md | 11 +-- .../ti-configuration-and-credentials.md | 13 +--- ai/ti/reference/ti-daily-workflow-example.md | 5 +- .../reference/ti-install-configure-update.md | 2 +- ai/ti/reference/ti-organization.md | 74 ------------------- .../ti-regions-security-and-limitations.md | 4 +- ai/ti/reference/ti-starter-database.md | 2 +- ai/ti/reference/ti-troubleshooting.md | 15 +--- ai/ti/ti-overview.md | 1 - ai/ti/ti-quick-start.md | 4 +- 14 files changed, 15 insertions(+), 182 deletions(-) delete mode 100644 ai/ti/reference/commands/organization/ti-organization-list-projects.md delete mode 100644 ai/ti/reference/ti-organization.md diff --git a/TOC-ai.md b/TOC-ai.md index 17075170e8d60..453df6b80b649 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -87,7 +87,6 @@ - [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) - Guides - [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) - - [TiDB Cloud Organization CLI Command Reference](/ai/ti/reference/ti-organization.md) - [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) - [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) - [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) @@ -97,8 +96,6 @@ - [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) - [configure](/ai/ti/reference/commands/ti/ti-configure.md) - [update](/ai/ti/reference/commands/ti/ti-update.md) - - organization - - [list-projects](/ai/ti/reference/commands/organization/ti-organization-list-projects.md) - db - [create-db-cluster](/ai/ti/reference/commands/db/ti-db-create-db-cluster.md) - [list-db-clusters](/ai/ti/reference/commands/db/ti-db-list-db-clusters.md) diff --git a/ai/_index.md b/ai/_index.md index c140a24e86be7..68f027f66b007 100644 --- a/ai/_index.md +++ b/ai/_index.md @@ -94,7 +94,6 @@ The command reference follows the two-level `ti` command tree. Every command has | [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) | Command tree, global flags, output, queries, dry-run, help, errors, aliases, and links to command pages. | | [`ti configure`](/ai/ti/reference/commands/ti/ti-configure.md) | Configure a local profile interactively or non-interactively. | | [`ti update`](/ai/ti/reference/commands/ti/ti-update.md) | Check for and install release updates. | -| [`ti organization list-projects`](/ai/ti/reference/commands/organization/ti-organization-list-projects.md) | List accessible TiDB Cloud projects. | | [`ti db create-db-cluster`](/ai/ti/reference/commands/db/ti-db-create-db-cluster.md) | Start with the database command reference. | | [`ti fs create-file-system`](/ai/ti/reference/commands/fs/ti-fs-create-file-system.md) | Start with the Filesystem command reference. | | [`ti fs import-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-import-file-system-token.md) | Restore local access from an existing FS token. | diff --git a/ai/ti/reference/commands/db/ti-db-create-db-cluster.md b/ai/ti/reference/commands/db/ti-db-create-db-cluster.md index 9893ce8025fbd..2809f2712200f 100644 --- a/ai/ti/reference/commands/db/ti-db-create-db-cluster.md +++ b/ai/ti/reference/commands/db/ti-db-create-db-cluster.md @@ -5,7 +5,7 @@ summary: Create a TiDB Cloud Starter cluster. # ti db create-db-cluster -Creates a Starter cluster. The required `--db-cluster-type` must be `starter`; there is no implicit type. `--wait` waits for the cluster to become `ACTIVE`. Project selection uses an explicit `--project-id`, then the configured virtual project, then the TiDB Cloud account default. The TiDB Cloud CLI validates the returned service plan; if verification fails after creation is accepted, it reports the cluster ID and retains the cluster for inspection. +Creates a Starter cluster. The required `--db-cluster-type` must be `starter`; there is no implicit type. `--wait` waits for the cluster to become `ACTIVE`. The request omits project selection and lets TiDB Cloud select its server-side default project. The TiDB Cloud CLI validates the returned service plan; if verification fails after creation is accepted, it reports the cluster ID and retains the cluster for inspection. > **Note:** > @@ -20,7 +20,6 @@ ti db create-db-cluster [--dry-run] [--help] [--monthly-spending-limit-usd-cents ] - [--project-id ] [--version] [--wait] ``` @@ -32,7 +31,6 @@ ti db create-db-cluster - `--dry-run`: Validate the request without applying changes. - `--help`: Display help information. - `--monthly-spending-limit-usd-cents `: Monthly spending limit in USD cents; omit to use the API default. -- `--project-id `: TiDB Cloud project ID. Overrides the configured and account defaults. - `--version`: Display version information. - `--wait`: Wait until the created cluster becomes `ACTIVE` before returning. @@ -61,13 +59,6 @@ For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli ti db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --dry-run ``` -- Create a cluster in an explicit project: - - ```bash - # Override the configured virtual project for this cluster. - ti db create-db-cluster --db-cluster-type starter --db-cluster-name project-db --project-id "" --wait - ``` - - Set a monthly spending limit: ```bash diff --git a/ai/ti/reference/commands/organization/ti-organization-list-projects.md b/ai/ti/reference/commands/organization/ti-organization-list-projects.md deleted file mode 100644 index 4aae855fb0223..0000000000000 --- a/ai/ti/reference/commands/organization/ti-organization-list-projects.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: ti organization list-projects -summary: List TiDB Cloud projects accessible to the configured API key. ---- - -# ti organization list-projects - -Lists projects accessible to the configured TiDB Cloud API key, with optional pagination. - -> **Note:** -> -> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. - -## Syntax - -```text -ti organization list-projects - [--help] - [--page-size ] - [--page-token ] - [--version] -``` - -## Options - -- `--help`: Display help information. -- `--page-size `: Number of projects to request; 0 uses the API default. -- `--page-token `: Page token returned by a previous list-projects call. -- `--version`: Display version information. - -For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). - -## Examples - -- List accessible projects: - - ```bash - # Return the TiDB Cloud projects available to the configured API key. - ti organization list-projects --page-size 50 - ``` - -- Select the virtual project ID: - - ```bash - # Use a JMESPath query to return only virtual project IDs. - ti organization list-projects --query 'projects[?type == `tidbx_virtual`].id' --output text - ``` - -## Related documentation - -- [TiDB Cloud Organization CLI Command Reference](/ai/ti/reference/ti-organization.md) diff --git a/ai/ti/reference/ti-cli-reference.md b/ai/ti/reference/ti-cli-reference.md index 913940d22dfde..9f1bd6402d444 100644 --- a/ai/ti/reference/ti-cli-reference.md +++ b/ai/ti/reference/ti-cli-reference.md @@ -25,8 +25,6 @@ The `ti` executable accepts long flags only. A one-letter flag such as `-p` is r ti ├── configure ├── update -├── organization -│ └── list-projects ├── db │ ├── create-db-cluster │ ├── list-db-clusters @@ -96,7 +94,7 @@ ti └── unmount-vault ``` -Every operation has a dedicated command page with syntax and examples. Expand **Command Reference** in the documentation navigation and select a command under `ti`, `organization`, `db`, `fs`, `fs-git`, `fs-journal`, or `fs-vault`. +Every operation has a dedicated command page with syntax and examples. Expand **Command Reference** in the documentation navigation and select a command under `ti`, `db`, `fs`, `fs-git`, `fs-journal`, or `fs-vault`. Required options appear before optional options in generated usage. Optional options are enclosed in brackets: @@ -111,7 +109,7 @@ In command help, value types are enclosed in angle brackets and required options ```text --db-cluster-name (required) Starter DB cluster display name ---project-id TiDB Cloud project ID +--wait Wait until the created cluster is active ``` ## Global options @@ -148,10 +146,6 @@ Raw byte-oriented commands such as `ti fs read-file` and `ti fs copy-file --to-s ti db list-db-clusters \ --db-cluster-type starter \ --query 'clusters[].{id:id,name:display_name,state:state}' - -ti organization list-projects \ - --query 'projects[?type == `tidbx_virtual`].id' \ - --output text ``` An invalid expression fails without replacing the command result with partial output. @@ -219,7 +213,6 @@ The following task-oriented guides explain how commands work together. They are | Guide | Purpose | | --- | --- | | [Install, Configure, and Update](/ai/ti/reference/ti-install-configure-update.md) | Install releases, configure profiles, update, and uninstall `ti` | -| [Organization and Projects](/ai/ti/reference/ti-organization.md) | Inspect projects and understand virtual-project selection | | [Starter Databases and SQL](/ai/ti/reference/ti-starter-database.md) | Manage Starter clusters, branches, and SQL | | [Filesystem](/ai/ti/reference/ti-filesystem.md) | Manage Filesystems, files, layers, packs, and mounts | | [Filesystem Git Workspaces](/ai/ti/reference/ti-filesystem-git.md) | Manage Git workspaces on mounted Filesystems | diff --git a/ai/ti/reference/ti-configuration-and-credentials.md b/ai/ti/reference/ti-configuration-and-credentials.md index 20ef4306d835e..ac8da7c4c9b02 100644 --- a/ai/ti/reference/ti-configuration-and-credentials.md +++ b/ai/ti/reference/ti-configuration-and-credentials.md @@ -17,7 +17,6 @@ summary: Reference TiDB Cloud CLI profiles, precedence rules, local state paths, # ~/.ti/config [default] region_code = "aws-us-east-1" -project_id = "..." ``` ```toml @@ -73,17 +72,9 @@ Placement selection is: Command flags, environment inputs, saved configuration, and command defaults are resolved per field. Values can therefore come from different levels when they do not form an atomic pair such as the API key pair. -## Default Starter project +## Starter project placement -Starter create selects a project in this order: - -1. explicit non-empty `--project-id`; -2. profile `project_id` discovered by `ti configure`; -3. omit the project label and let TiDB Cloud select the account's default project. - -An explicitly empty `--project-id` is invalid. When no project ID is available, `ti` omits the project label entirely rather than sending an empty value. - -Other DB commands identify resources by cluster or branch ID and do not use `project_id`. Filesystem commands do not consume the DB project default. +The TiDB Cloud CLI does not accept or store a project selector. Starter cluster creation omits project placement and lets TiDB Cloud select its server-side default project. Project fields and labels returned by TiDB Cloud remain visible as resource metadata and are not reused for later requests. ## Filesystem credentials and remote inventory diff --git a/ai/ti/reference/ti-daily-workflow-example.md b/ai/ti/reference/ti-daily-workflow-example.md index e3870ea348dbb..93957212654d6 100644 --- a/ai/ti/reference/ti-daily-workflow-example.md +++ b/ai/ti/reference/ti-daily-workflow-example.md @@ -1,6 +1,6 @@ --- title: Run a Daily TiDB Cloud CLI Workflow -summary: Inspect projects, manage a Starter cluster and Filesystem, check for TiDB Cloud CLI updates, and clean up resources. +summary: Inspect resources, manage a Starter cluster and Filesystem, check for TiDB Cloud CLI updates, and clean up resources. --- # Run a Daily TiDB Cloud CLI Workflow @@ -16,10 +16,9 @@ This example follows a typical operator workflow across TiDB Cloud Starter and T - Install `ti` and run `ti configure`. - Ensure your organization has capacity for one Starter cluster and one Filesystem. -## Step 1. Inspect the active account +## Step 1. Inspect current resources ```bash -ti organization list-projects --output text ti db list-db-clusters --db-cluster-type starter --output text ti fs list-file-systems --output text ``` diff --git a/ai/ti/reference/ti-install-configure-update.md b/ai/ti/reference/ti-install-configure-update.md index 85d2848b3388f..a3ffa6e8fadac 100644 --- a/ai/ti/reference/ti-install-configure-update.md +++ b/ai/ti/reference/ti-install-configure-update.md @@ -76,7 +76,7 @@ Interactive configuration is the only TiDB Cloud CLI workflow that prompts: ti configure ``` -The TiDB Cloud CLI requests a TiDB Cloud API public key, private key, and canonical region code. It validates the key by listing projects and records the unique `tidbx_virtual` project as the profile's default project. +The TiDB Cloud CLI requests a TiDB Cloud API public key, private key, and canonical region code, validates those values locally, and stores the selected profile. Configuration makes no network request. The first remote command reports authentication or authorization errors for the permission it requires. Configure a named profile: diff --git a/ai/ti/reference/ti-organization.md b/ai/ti/reference/ti-organization.md deleted file mode 100644 index dbaeec96d29cd..0000000000000 --- a/ai/ti/reference/ti-organization.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: TiDB Cloud Organization CLI Command Reference -summary: Reference the `ti organization` command tree, project listing inputs, output, and examples. ---- - -# TiDB Cloud Organization CLI Command Reference - -Use `ti organization` to inspect the projects accessible to the configured TiDB Cloud API key. - -> **Note:** -> -> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. - -## Command tree - -```text -ti organization -└── list-projects -``` - -`list-projects` requires a configured TiDB Cloud API key. It accepts `--page-size` and `--page-token` for pagination, plus the global output and query flags. - -## Prerequisites - -Run `ti configure` with a TiDB Cloud API key that can list organization projects. - -## List projects - -```bash -ti organization list-projects -``` - -The JSON response includes project IDs, names, and `type` values: - -- `tidbx` identifies a regular project; -- `tidbx_virtual` identifies a virtual project used as the default Starter project. - -Request a page size or continue with a returned page token: - -```bash -ti organization list-projects --page-size 50 -ti organization list-projects --page-size 50 --page-token "" -``` - -Render a terminal-oriented table or select fields: - -```bash -ti organization list-projects --output text -ti organization list-projects --query 'projects[].{id:id,name:name,type:type}' -``` - -## Default virtual project - -`ti configure` calls the same project-listing API. Configuration succeeds only when it finds exactly one accessible `tidbx_virtual` project, and saves its ID in the selected profile: - -```toml -[default] -region_code = "aws-us-east-1" -project_id = "..." -``` - -`ti db create-db-cluster` uses this project when `--project-id` is omitted. If the saved ID is removed, cluster creation omits the project label and TiDB Cloud selects the account's default project. Pass an explicit project ID to override either default for one cluster: - -```bash -ti db create-db-cluster \ - --db-cluster-type starter \ - --db-cluster-name project-specific-cluster \ - --project-id "" -``` - -## What's next - -- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) -- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/ti/reference/ti-regions-security-and-limitations.md b/ai/ti/reference/ti-regions-security-and-limitations.md index 10d84eafc656e..eef91558ba653 100644 --- a/ai/ti/reference/ti-regions-security-and-limitations.md +++ b/ai/ti/reference/ti-regions-security-and-limitations.md @@ -43,7 +43,7 @@ The hosted manifest is authoritative and can change during preview. A profile in | Operation | Required credential | | --- | --- | -| `ti configure`, `ti organization`, all `ti db` control-plane operations | TiDB Cloud API public/private key | +| `ti configure`, all `ti db` control-plane operations | TiDB Cloud API public/private key | | `ti fs create-file-system` | TiDB Cloud API key | | `ti fs delete-file-system` | TiDB Cloud API key and file system ID | | Remote file, layer, pack, mount, Git, journal, and owner vault operations | FS owner token or registered resource credential | @@ -54,7 +54,7 @@ TiDB Cloud API calls use Digest authentication. SQL HTTPS execution uses generat ## Security best practices -- Create TiDB Cloud API keys with only the organization and project access required for the workflow. Do not reuse a personal administrator key in unattended automation. +- Create TiDB Cloud API keys with only the access required for the workflow. Do not reuse a personal administrator key in unattended automation. - Inject automation credentials from a CI secret store or runtime secret manager. Do not place credentials in source control, container images, shell scripts, or command-line arguments that can appear in process listings and shell history. - Do not copy the complete `~/.ti/` directory into an agent sandbox. For an existing Filesystem, pass only `TI_FS_TOKEN` and `TI_REGION_CODE`; use `TI_FS_FILE_SYSTEM_ID` only as an optional assertion. - Treat an FS owner token as full access to that Filesystem. When an agent needs only selected secrets, create a vault grant with the narrowest field scope and shortest practical TTL, and pass the delegated vault token instead. diff --git a/ai/ti/reference/ti-starter-database.md b/ai/ti/reference/ti-starter-database.md index 9b69d4a2767d7..78938615800ef 100644 --- a/ai/ti/reference/ti-starter-database.md +++ b/ai/ti/reference/ti-starter-database.md @@ -67,7 +67,7 @@ ti db create-db-cluster \ --db-cluster-name demo-cluster ``` -An explicit `--project-id` overrides the configured virtual project. If neither is available, TiDB Cloud selects the account's default project. `--db-cluster-type starter` is required for cluster creation and listing; no type is inferred. `--monthly-spending-limit-usd-cents` is optional; setting it can require a payment method. +The TiDB Cloud CLI omits project selection and lets TiDB Cloud select its server-side default project. Any project metadata in the response remains visible. `--db-cluster-type starter` is required for cluster creation and listing; no type is inferred. `--monthly-spending-limit-usd-cents` is optional; setting it can require a payment method. List and filter clusters: diff --git a/ai/ti/reference/ti-troubleshooting.md b/ai/ti/reference/ti-troubleshooting.md index 63dc5ca357714..ba87ecf6b3067 100644 --- a/ai/ti/reference/ti-troubleshooting.md +++ b/ai/ti/reference/ti-troubleshooting.md @@ -26,21 +26,10 @@ If you intend to use saved credentials, unset both variables and verify the prof ```bash unset TI_PUBLIC_KEY TI_PRIVATE_KEY -ti organization list-projects --profile default +ti db list-db-clusters --db-cluster-type starter --profile default ``` -An API key can authenticate successfully but still lack the permission declared by a command. Use a key with the required organization or project access. - -## Configure cannot find a virtual project - -`ti configure` requires exactly one accessible project whose `type` is `tidbx_virtual`. - -```bash -ti organization list-projects \ - --query 'projects[].{id:id,name:name,type:type}' -``` - -If no virtual project appears, confirm the API key's organization and project access. If multiple virtual projects appear, report the ambiguous account state through the [`ti` issue tracker](https://github.com/tidbcloud/ti/issues). +An API key can authenticate successfully but still lack the permission declared by a command. Use a key with the access required by that operation. `ti configure` validates and stores local values without contacting TiDB Cloud, so credential failures first appear on a remote command. ## Filesystem token is missing diff --git a/ai/ti/ti-overview.md b/ai/ti/ti-overview.md index 38982ab78b964..ef2107e00f321 100644 --- a/ai/ti/ti-overview.md +++ b/ai/ti/ti-overview.md @@ -65,7 +65,6 @@ You do not need to install, configure, or invoke Drive9 separately for normal Ti Follow the [Quick Start](/ai/ti/ti-quick-start.md) to install the TiDB Cloud CLI and complete your first Starter or Filesystem workflow. Use these guides for task-oriented instructions: - [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) -- [TiDB Cloud Organization CLI Command Reference](/ai/ti/reference/ti-organization.md) - [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) - [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) - [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md index ead802ca3935c..bf780b7513b8d 100644 --- a/ai/ti/ti-quick-start.md +++ b/ai/ti/ti-quick-start.md @@ -63,10 +63,10 @@ ti configure Enter your API public key, private key, and a canonical region code such as `aws-us-east-1`. -Verify the configuration: +Run a read-only command to verify the saved credentials and selected region: ```bash -ti organization list-projects --output text +ti db list-db-clusters --db-cluster-type starter --output text ``` ## Step 3. Choose a first workflow From 75cd8aa091694fb817058dbc637241c870b0c3e6 Mon Sep 17 00:00:00 2001 From: Cheese Date: Thu, 13 Aug 2026 12:29:14 +0800 Subject: [PATCH 28/29] docs: add filesystem token lifecycle commands --- TOC-ai.md | 6 ++ .../fs/ti-fs-delete-file-system-token.md | 45 +++++++++++ .../fs/ti-fs-disable-file-system-token.md | 47 ++++++++++++ .../fs/ti-fs-enable-file-system-token.md | 45 +++++++++++ .../fs/ti-fs-generate-file-system-token.md | 76 +++++++++++++++++++ .../fs/ti-fs-list-file-system-tokens.md | 58 ++++++++++++++ .../fs/ti-fs-refresh-file-system-token.md | 63 +++++++++++++++ ai/ti/reference/ti-cli-reference.md | 6 ++ .../ti-configuration-and-credentials.md | 6 +- ai/ti/reference/ti-filesystem.md | 56 ++++++++++++++ .../ti-regions-security-and-limitations.md | 6 ++ ...hare-filesystem-across-machines-example.md | 15 +++- ai/ti/reference/ti-troubleshooting.md | 35 ++++++++- 13 files changed, 459 insertions(+), 5 deletions(-) create mode 100644 ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md create mode 100644 ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md create mode 100644 ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md create mode 100644 ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md create mode 100644 ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md create mode 100644 ai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.md diff --git a/TOC-ai.md b/TOC-ai.md index 453df6b80b649..b80c2692eb5ff 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -112,6 +112,12 @@ - fs - [create-file-system](/ai/ti/reference/commands/fs/ti-fs-create-file-system.md) - [import-file-system-token](/ai/ti/reference/commands/fs/ti-fs-import-file-system-token.md) + - [generate-file-system-token](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) + - [list-file-system-tokens](/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md) + - [enable-file-system-token](/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md) + - [disable-file-system-token](/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md) + - [delete-file-system-token](/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md) + - [refresh-file-system-token](/ai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.md) - [list-file-systems](/ai/ti/reference/commands/fs/ti-fs-list-file-systems.md) - [describe-file-system](/ai/ti/reference/commands/fs/ti-fs-describe-file-system.md) - [check-file-system](/ai/ti/reference/commands/fs/ti-fs-check-file-system.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md new file mode 100644 index 0000000000000..58bedf0d37eb7 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md @@ -0,0 +1,45 @@ +--- +title: ti fs delete-file-system-token +summary: Permanently revoke a TiDB Cloud Filesystem token. +--- + +# ti fs delete-file-system-token + +Permanently revokes a token by immutable token ID. Revocation is terminal and the service does not return revoked tokens in later list results. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs delete-file-system-token + --file-system-id + --token-id + [--dry-run] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. This option is required. +- `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--dry-run`: Validate credentials, identifiers, and known local mount conflicts without revoking the token. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Revoke an old token after validating its replacement: + + ```bash + # Revocation is permanent; use disable first when you need a reversible rollout. + ti fs delete-file-system-token \ + --file-system-id "" \ + --token-id "" + ``` + +## Related documentation + +- [`ti fs generate-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) +- [`ti fs disable-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md new file mode 100644 index 0000000000000..b4eff74c23ba8 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md @@ -0,0 +1,47 @@ +--- +title: ti fs disable-file-system-token +summary: Temporarily disable a TiDB Cloud Filesystem token. +--- + +# ti fs disable-file-system-token + +Disables an active token by immutable token ID without revoking it. A token used by a known local mount must be drained and unmounted first. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs disable-file-system-token + --file-system-id + --token-id + [--dry-run] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. This option is required. +- `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--dry-run`: Validate credentials, identifiers, and known local mount conflicts without disabling the token. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Disable a token after stopping its local mount: + + ```bash + # Drain and unmount first when this token backs a mount on the current machine. + ti fs drain-file-system --mount-path /path/to/workspace + ti fs unmount-file-system --mount-path /path/to/workspace + ti fs disable-file-system-token \ + --file-system-id "" \ + --token-id "" + ``` + +## Related documentation + +- [`ti fs enable-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md) +- [`ti fs delete-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md new file mode 100644 index 0000000000000..154bf16f78806 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md @@ -0,0 +1,45 @@ +--- +title: ti fs enable-file-system-token +summary: Enable a disabled TiDB Cloud Filesystem token. +--- + +# ti fs enable-file-system-token + +Changes a disabled token to active by immutable token ID. Authentication caches can take approximately 10 seconds to converge. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs enable-file-system-token + --file-system-id + --token-id + [--dry-run] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. This option is required. +- `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--dry-run`: Validate the request without changing remote token state. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Enable a known token: + + ```bash + # Allow about 10 seconds for all authentication caches to observe the change. + ti fs enable-file-system-token \ + --file-system-id "" \ + --token-id "" + ``` + +## Related documentation + +- [`ti fs list-file-system-tokens`](/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md) +- [`ti fs disable-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md new file mode 100644 index 0000000000000..174fd45e6180c --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md @@ -0,0 +1,76 @@ +--- +title: ti fs generate-file-system-token +summary: Generate an additional owner token for one TiDB Cloud Filesystem. +--- + +# ti fs generate-file-system-token + +Generates an owner token for one Filesystem. The plaintext `fs_token` appears only in the successful response and cannot be recovered through the list command. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs generate-file-system-token + --file-system-id + --token-name + (--ttl | --no-expiration) + [--dry-run] + [--replace] + [--store-locally] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. This option is required. +- `--token-name `: Set an operational token name of at most 64 bytes. Names are not unique. This option is required. +- `--ttl `: Set a positive lifetime in whole seconds, up to 365 days. Specify exactly one of `--ttl` and `--no-expiration`. +- `--no-expiration`: Create a token without an expiry. Specify exactly one of `--ttl` and `--no-expiration`. +- `--store-locally`: Store and select the generated token for this profile and Filesystem. +- `--replace`: Replace an existing selected local token. Requires `--store-locally` and does not revoke the previous remote token. +- `--dry-run`: Validate credentials, region, lifetime, and local storage preconditions without generating a token. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Generate a short-lived token for a CI job: + + ```bash + # Save the one-time plaintext response in an owner-only file. + umask 077 + ti fs generate-file-system-token \ + --file-system-id "" \ + --token-name ci-deploy \ + --ttl 24h > ./ci-token.json + ``` + +- Generate a non-expiring token for another machine: + + ```bash + # Generation does not change the current local selection by default. + ti fs generate-file-system-token \ + --file-system-id "" \ + --token-name workstation \ + --no-expiration + ``` + +- Generate and select a replacement local token: + + ```bash + # The old remote token remains active until you explicitly disable or delete it. + ti fs generate-file-system-token \ + --file-system-id "" \ + --token-name local-owner-v2 \ + --ttl 720h \ + --store-locally \ + --replace + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [`ti fs list-file-system-tokens`](/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md b/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md new file mode 100644 index 0000000000000..38188081cf9cb --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md @@ -0,0 +1,58 @@ +--- +title: ti fs list-file-system-tokens +summary: List token metadata for one TiDB Cloud Filesystem. +--- + +# ti fs list-file-system-tokens + +Lists non-secret token metadata for one Filesystem. The response never contains token plaintext. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs list-file-system-tokens + --file-system-id + [--include-expired] + [--limit ] + [--offset ] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem whose tokens are listed. This option is required. +- `--include-expired`: Include expired token metadata. Revoked tokens are not returned by the service. +- `--offset `: Set the zero-based token offset [default: 0]. +- `--limit `: Set the maximum number of tokens to return, from 1 through 200 [default: 50]. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- List current token metadata as text: + + ```bash + # Use token_id, not the non-unique token name, for later mutations. + ti fs list-file-system-tokens \ + --file-system-id "" \ + --output text + ``` + +- Inspect expired token metadata with pagination: + + ```bash + # Request up to 100 rows starting at offset 0. + ti fs list-file-system-tokens \ + --file-system-id "" \ + --include-expired \ + --offset 0 \ + --limit 100 + ``` + +## Related documentation + +- [`ti fs generate-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.md new file mode 100644 index 0000000000000..c34778bc9a104 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.md @@ -0,0 +1,63 @@ +--- +title: ti fs refresh-file-system-token +summary: Rotate one TiDB Cloud Filesystem token and return its replacement plaintext once. +--- + +# ti fs refresh-file-system-token + +Rotates the supplied bearer token in place. Refresh is not idempotent: if the request commits but its response is lost, do not retry with the old token. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs refresh-file-system-token + [--file-system-id ] + [--fs-token ] + [--ttl ] + [--dry-run] +``` + +## Options + +- `--file-system-id `: Assert the Filesystem ID decoded from a supplied token. This option is required when loading a locally selected token. +- `--fs-token `: Supply the current token. Prefer `TI_FS_TOKEN` to avoid shell history and process-list exposure. Defaults to `TI_FS_TOKEN`, then the selected local credential. +- `--ttl `: Set a new positive lifetime in whole seconds, up to 365 days. Omit it to preserve the previous lifetime period. +- `--dry-run`: Validate token selection, region, TTL, and known local mount conflicts without rotating the token. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Refresh the selected local credential: + + ```bash + # ti atomically replaces the local credential after receiving the new token. + ti fs refresh-file-system-token --file-system-id "" + ``` + +- Refresh a token supplied by a secret manager: + + ```bash + # Capture the one-time replacement and update the external secret manager yourself. + TI_FS_TOKEN="" \ + TI_REGION_CODE="aws-us-east-1" \ + ti fs refresh-file-system-token > ./refreshed-token.json + ``` + +- Change the token lifetime during refresh: + + ```bash + # Rotate the token and set its new lifetime to 30 days. + TI_FS_TOKEN="" \ + TI_REGION_CODE="aws-us-east-1" \ + ti fs refresh-file-system-token --ttl 720h + ``` + +## Related documentation + +- [`ti fs generate-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) diff --git a/ai/ti/reference/ti-cli-reference.md b/ai/ti/reference/ti-cli-reference.md index 9f1bd6402d444..c6d683327cb0b 100644 --- a/ai/ti/reference/ti-cli-reference.md +++ b/ai/ti/reference/ti-cli-reference.md @@ -41,6 +41,12 @@ ti ├── fs │ ├── create-file-system │ ├── import-file-system-token +│ ├── generate-file-system-token +│ ├── list-file-system-tokens +│ ├── enable-file-system-token +│ ├── disable-file-system-token +│ ├── delete-file-system-token +│ ├── refresh-file-system-token │ ├── list-file-systems │ ├── describe-file-system │ ├── check-file-system diff --git a/ai/ti/reference/ti-configuration-and-credentials.md b/ai/ti/reference/ti-configuration-and-credentials.md index ac8da7c4c9b02..a79611b4b801a 100644 --- a/ai/ti/reference/ti-configuration-and-credentials.md +++ b/ai/ti/reference/ti-configuration-and-credentials.md @@ -84,7 +84,11 @@ One profile can access multiple Filesystems. Drive9's remote inventory is author ~/.ti/fs_credentials///credentials ``` -The credential contains the server-assigned file system ID, canonical region code, and owner `api_key`, and uses owner-only permissions. `ti fs list-file-systems` reads remote resources and joins only the non-secret `has_local_token` hint. +The credential contains the server-assigned file system ID, canonical region code, selected `api_key`, and optional authoritative token metadata, and uses owner-only permissions. `ti fs list-file-systems` reads remote resources and joins only the non-secret `has_local_token` hint. + +One remote Filesystem can have multiple tokens, but each profile stores at most one selected token per Filesystem. The local store is an operational selection, not a replica of remote token inventory. Credentials created by provisioning or older imports might not contain `token_id`, `scope_kind`, `token_name`, or `expires_at`; they remain valid for data-plane use, and `ti` does not guess missing metadata from token-list rows. + +`ti fs generate-file-system-token` does not change the selected credential unless `--store-locally` is set. `--replace` changes only the local selection and leaves the previous remote token active. A refresh sourced from the local credential atomically replaces it. A refresh sourced from a flag or `TI_FS_TOKEN` returns the replacement plaintext without writing local state. Resource selection is: diff --git a/ai/ti/reference/ti-filesystem.md b/ai/ti/reference/ti-filesystem.md index 8993c32dbc102..f70d4686f3cfc 100644 --- a/ai/ti/reference/ti-filesystem.md +++ b/ai/ti/reference/ti-filesystem.md @@ -17,6 +17,12 @@ Use `ti fs` to provision TiDB Cloud Filesystem resources and access their data f ti fs ├── create-file-system ├── import-file-system-token +├── generate-file-system-token +├── list-file-system-tokens +├── enable-file-system-token +├── disable-file-system-token +├── delete-file-system-token +├── refresh-file-system-token ├── list-file-systems ├── describe-file-system ├── check-file-system @@ -55,6 +61,12 @@ ti fs | --- | --- | --- | | `create-file-system` | Provisions a Filesystem with a server-assigned ID; `--wait` waits until data-plane access is ready. | `ti fs create-file-system --wait` | | `import-file-system-token` | Validates and stores an existing token under its embedded file system ID. | `ti fs import-file-system-token --from-file ./fs-token --region aws-us-east-1` | +| `generate-file-system-token` | Generates an additional owner token and returns its plaintext once. | `ti fs generate-file-system-token --file-system-id --token-name ci --ttl 24h` | +| `list-file-system-tokens` | Lists non-secret token metadata for one Filesystem. | `ti fs list-file-system-tokens --file-system-id ` | +| `enable-file-system-token` | Re-enables a disabled token by immutable token ID. | `ti fs enable-file-system-token --file-system-id --token-id ` | +| `disable-file-system-token` | Temporarily disables a token by immutable token ID. | `ti fs disable-file-system-token --file-system-id --token-id ` | +| `delete-file-system-token` | Permanently revokes a token by immutable token ID. | `ti fs delete-file-system-token --file-system-id --token-id ` | +| `refresh-file-system-token` | Rotates the supplied token and returns its replacement plaintext once. | `ti fs refresh-file-system-token --file-system-id ` | | `list-file-systems` | Lists remote resources available to the TiDB Cloud credentials in the effective region. | `ti fs list-file-systems --output text` | | `describe-file-system` | Reads one remote resource by ID without requiring its FS token. | `ti fs describe-file-system --file-system-id ` | | `check-file-system` | Verifies resource selection, endpoint resolution, credentials, and companion access. | `ti fs check-file-system --file-system-id ` | @@ -151,6 +163,50 @@ ti fs delete-file-system \ Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and an ID, but not a local FS token. Drive9 deletion is asynchronous, so a successfully accepted request reports `status: "deleting"` while `ti` removes only a matching ID-keyed local credential. +## Manage Filesystem tokens + +One Filesystem can have multiple owner or scoped tokens. The remote service is authoritative for token inventory and lifecycle state. Each local profile stores only one selected operational token per Filesystem; it does not mirror every remote token. + +Generate an additional owner token for CI and save its one-time plaintext response securely: + +```bash +umask 077 +ti fs generate-file-system-token \ + --file-system-id "" \ + --token-name ci-deploy \ + --ttl 24h > ./ci-token.json +``` + +Generation does not change local selection by default. Add `--store-locally` to select the generated token. If another local token exists, `--replace` is also required. Replacing local selection does not disable or revoke the old remote token. + +List token metadata and use the immutable token ID for state changes: + +```bash +ti fs list-file-system-tokens --file-system-id "" --output text +ti fs disable-file-system-token --file-system-id "" --token-id "" +ti fs enable-file-system-token --file-system-id "" --token-id "" +ti fs delete-file-system-token --file-system-id "" --token-id "" +``` + +Token names are not unique. List output never contains token plaintext, and revoked tokens do not appear. Authentication changes can take approximately 10 seconds to converge. + +Refresh a selected local token atomically: + +```bash +ti fs refresh-file-system-token --file-system-id "" +``` + +To refresh a token held by an external secret manager, supply `TI_FS_TOKEN` and `TI_REGION_CODE`. The command returns the replacement plaintext but cannot update the external store. Refresh is non-idempotent: when the request might have committed but the response was lost, do not retry with the old token. Generate another owner token with TiDB Cloud credentials instead. + +Before refreshing, disabling, or deleting a token used by a known local mount, drain and unmount it: + +```bash +ti fs drain-file-system --mount-path /path/to/workspace +ti fs unmount-file-system --mount-path /path/to/workspace +``` + +Older credentials created or imported before token lifecycle metadata was available can continue to access data, but `ti` cannot correlate them with a remote token row. It never guesses a token ID from name, timestamp, or list order. + ## Select one of multiple Filesystems One profile can own multiple resources. Selection precedence is: diff --git a/ai/ti/reference/ti-regions-security-and-limitations.md b/ai/ti/reference/ti-regions-security-and-limitations.md index eef91558ba653..2c06d2e967493 100644 --- a/ai/ti/reference/ti-regions-security-and-limitations.md +++ b/ai/ti/reference/ti-regions-security-and-limitations.md @@ -46,6 +46,8 @@ The hosted manifest is authoritative and can change during preview. A profile in | `ti configure`, all `ti db` control-plane operations | TiDB Cloud API public/private key | | `ti fs create-file-system` | TiDB Cloud API key | | `ti fs delete-file-system` | TiDB Cloud API key and file system ID | +| Generate, list, enable, disable, or delete Filesystem tokens | TiDB Cloud API key and explicit file system ID | +| Refresh a Filesystem token | The current FS bearer token only | | Remote file, layer, pack, mount, Git, journal, and owner vault operations | FS owner token or registered resource credential | | Delegated vault read, list, run, or mount | Scope-appropriate delegated vault token | | Drain and unmount after a successful background mount | Non-secret mount locator in the same `HOME` | @@ -58,6 +60,9 @@ TiDB Cloud API calls use Digest authentication. SQL HTTPS execution uses generat - Inject automation credentials from a CI secret store or runtime secret manager. Do not place credentials in source control, container images, shell scripts, or command-line arguments that can appear in process listings and shell history. - Do not copy the complete `~/.ti/` directory into an agent sandbox. For an existing Filesystem, pass only `TI_FS_TOKEN` and `TI_REGION_CODE`; use `TI_FS_FILE_SYSTEM_ID` only as an optional assertion. - Treat an FS owner token as full access to that Filesystem. When an agent needs only selected secrets, create a vault grant with the narrowest field scope and shortest practical TTL, and pass the delegated vault token instead. +- Use a separate Filesystem token for each machine, CI workflow, or sandbox class so that one environment can be disabled or revoked without interrupting others. Token names are operational labels, not unique identifiers; mutate tokens only by `token_id`. +- Capture generated and refreshed token plaintext immediately because it is returned only once. A token refreshed from `TI_FS_TOKEN` is not written back to an external secret manager. Refresh is non-idempotent, so do not retry after an ambiguous network failure. +- For shared-token rotation, generate and distribute a replacement, validate access, then disable and delete the old token. Allow approximately 10 seconds for authentication caches to converge after a state change. - Use `--read-only` for SQL inspection by untrusted or exploratory agents. Use `--admin` only for DDL or privilege management, and use `--read-write` only when data changes are intended. - Use `--dry-run` before destructive control-plane operations. Keep `~/.ti/credentials`, resource credentials, and DB SQL credentials owner-readable only. - Grant Docker access to `/dev/fuse`, `SYS_ADMIN`, and an unconfined AppArmor profile only to dedicated, trusted containers. These settings reduce container isolation. @@ -93,6 +98,7 @@ Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path - Read-write is the default SQL role; use explicit role flags in security-sensitive automation. - Journals are append-only and the current public command surface has no journal delete command. - Filesystem list and describe commands query the region-scoped remote inventory with TiDB Cloud credentials. They do not aggregate across regions. +- The local credential store keeps one selected token per profile and Filesystem. It does not mirror all remote tokens. Older create/import credentials without a known token ID remain usable, but cannot be correlated with remote token metadata. - Telemetry management commands are intentionally not implemented. Control telemetry through `~/.ti/.preferences` or `TI_TELEMETRY`; serverless-function deployment, Homebrew, and Scoop distribution are not implemented. - The TiDB Cloud CLI depends on its installed `ti-drive9` companion for all public Filesystem runtime behavior. diff --git a/ai/ti/reference/ti-share-filesystem-across-machines-example.md b/ai/ti/reference/ti-share-filesystem-across-machines-example.md index fbe5c5bd72d87..ced810173d5e2 100644 --- a/ai/ti/reference/ti-share-filesystem-across-machines-example.md +++ b/ai/ti/reference/ti-share-filesystem-across-machines-example.md @@ -21,7 +21,7 @@ Local disks do not provide a shared namespace. Commands such as `scp` and archiv ## How TiDB Cloud CLI changes the workflow -Both machines select the same TiDB Cloud Filesystem. Data-plane commands and the mounted path address one remote namespace, so a write from either interface becomes visible through the other after it is flushed. Machine B needs only the Filesystem token and region code; the token identifies the Filesystem, so it does not need TiDB Cloud API keys or a copied profile. +Both machines select the same TiDB Cloud Filesystem with separate owner tokens. Data-plane commands and the mounted path address one remote namespace, so a write from either interface becomes visible through the other after it is flushed. Machine B needs only its Filesystem token and region code; the token identifies the Filesystem, so it does not need TiDB Cloud API keys or a copied profile. Separate tokens let you revoke machine B without interrupting machine A. ## Prerequisites @@ -37,12 +37,17 @@ ti fs create-file-system --wait > ./filesystem.json export FILE_SYSTEM_ID="$(jq -r '.file_system_id' ./filesystem.json)" export TI_FS_TOKEN="$(jq -r '.fs_token' ./filesystem.json)" +ti fs generate-file-system-token \ + --file-system-id "$FILE_SYSTEM_ID" \ + --token-name machine-b \ + --ttl 720h > ./machine-b-token.json + printf 'from machine A\n' | ti fs copy-file \ --from-stdin \ --to-remote /shared/origin.txt ``` -Transfer the token through a secret manager and communicate the canonical region code. Keep `FILE_SYSTEM_ID` on machine A for control-plane operations, then delete `filesystem.json` after storing the token securely. +Transfer the `fs_token` from `machine-b-token.json` through a secret manager and communicate the canonical region code. Keep `FILE_SYSTEM_ID` on machine A for control-plane operations, then delete both JSON files after storing their tokens securely. ## Step 2. Configure machine B in memory @@ -86,13 +91,17 @@ unset TI_FS_TOKEN TI_REGION_CODE On machine A: ```bash +ti fs list-file-system-tokens --file-system-id "$FILE_SYSTEM_ID" --output text +ti fs delete-file-system-token \ + --file-system-id "$FILE_SYSTEM_ID" \ + --token-id "" ti fs delete-file-system \ --file-system-id "$FILE_SYSTEM_ID" ``` ## Security notes -- The FS token grants owner access. Transfer it as a secret, not in chat or command history. +- Each FS token grants owner access. Transfer it as a secret, not in chat or command history, and use a separate token for each machine. - Concurrent writers can overwrite the same paths; coordinate ownership at the workflow level. - Do not terminate a machine before graceful unmount completes. Use an explicit drain only when you need remote durability while keeping the FUSE mount online. diff --git a/ai/ti/reference/ti-troubleshooting.md b/ai/ti/reference/ti-troubleshooting.md index ba87ecf6b3067..66f4d00782f69 100644 --- a/ai/ti/reference/ti-troubleshooting.md +++ b/ai/ti/reference/ti-troubleshooting.md @@ -52,7 +52,40 @@ ti fs import-file-system-token --from-file ./fs-token --region aws-us-east-1 ti fs list-files --file-system-id --path / ``` -The current Preview cannot regenerate a lost Filesystem token. A remote Filesystem can still be listed, described, or deleted with TiDB Cloud API keys, but its data cannot be read or mounted until a valid known token is supplied. +If every known token is lost or revoked, use TiDB Cloud API keys to generate another owner token: + +```bash +ti fs generate-file-system-token \ + --file-system-id "" \ + --token-name recovery \ + --ttl 24h +``` + +The new plaintext appears once in the response. Store it securely or add `--store-locally` to select it on the current machine. + +## Filesystem token is rejected + +A data-plane HTTP 401 cannot distinguish a token that was disabled, expired, refreshed on another machine, or revoked. Inspect remote metadata with TiDB Cloud API keys: + +```bash +ti fs list-file-system-tokens \ + --file-system-id "" \ + --include-expired \ + --output text +``` + +Token names are not unique. Use the immutable `token_id` from this output for enable, disable, or delete operations. Old credentials created or imported without token lifecycle metadata can remain valid, but `ti` cannot safely identify their list row and never guesses a match. + +After enable, disable, delete, or refresh, allow approximately 10 seconds for authentication caches to converge. If refresh reports `fs.token_refresh_ambiguous`, the server might have rotated the token even though the response was lost. Do not retry with the old token. Generate another owner token through TiDB Cloud credentials. + +If token mutation reports `fs.token_mount_active`, use the exact mount path in the error: + +```bash +ti fs drain-file-system --mount-path /path/to/workspace +ti fs unmount-file-system --mount-path /path/to/workspace +``` + +Then retry the token operation. A mount on another machine is not visible locally; coordinate rotation with that machine separately. ## Filesystem selection is missing From 4f9bc531321527f44c68521584b57efb82333721 Mon Sep 17 00:00:00 2001 From: Cheese Date: Thu, 13 Aug 2026 13:15:09 +0800 Subject: [PATCH 29/29] docs: add scoped filesystem token issuance --- TOC-ai.md | 1 + .../fs/ti-fs-delete-file-system-token.md | 4 +- .../fs/ti-fs-disable-file-system-token.md | 4 +- .../fs/ti-fs-enable-file-system-token.md | 4 +- ...ti-fs-generate-file-system-scoped-token.md | 83 +++++++++++++++++++ .../fs/ti-fs-list-file-system-tokens.md | 3 + ai/ti/reference/ti-cli-reference.md | 1 + .../ti-configuration-and-credentials.md | 4 +- ai/ti/reference/ti-filesystem.md | 2 + 9 files changed, 102 insertions(+), 4 deletions(-) create mode 100644 ai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.md diff --git a/TOC-ai.md b/TOC-ai.md index b80c2692eb5ff..d72cee2f128de 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -113,6 +113,7 @@ - [create-file-system](/ai/ti/reference/commands/fs/ti-fs-create-file-system.md) - [import-file-system-token](/ai/ti/reference/commands/fs/ti-fs-import-file-system-token.md) - [generate-file-system-token](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) + - [generate-file-system-scoped-token](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.md) - [list-file-system-tokens](/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md) - [enable-file-system-token](/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md) - [disable-file-system-token](/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md index 58bedf0d37eb7..9ff3d0a9a17a8 100644 --- a/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md +++ b/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md @@ -5,7 +5,7 @@ summary: Permanently revoke a TiDB Cloud Filesystem token. # ti fs delete-file-system-token -Permanently revokes a token by immutable token ID. Revocation is terminal and the service does not return revoked tokens in later list results. +Permanently revokes a token by immutable token ID. Revocation is terminal and the service does not return revoked tokens in later list results. An owner token can revoke either token kind in the same Filesystem; a scoped token cannot use this command. > **Note:** > @@ -17,6 +17,7 @@ Permanently revokes a token by immutable token ID. Revocation is terminal and th ti fs delete-file-system-token --file-system-id --token-id + [--fs-token ] [--dry-run] ``` @@ -24,6 +25,7 @@ ti fs delete-file-system-token - `--file-system-id `: Specify the Filesystem that owns the token. This option is required. - `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--fs-token `: Authorize the request with an owner FS token. Defaults to `TI_FS_TOKEN`; when neither is present, the command uses configured TiDB Cloud API keys. - `--dry-run`: Validate credentials, identifiers, and known local mount conflicts without revoking the token. For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). diff --git a/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md index b4eff74c23ba8..3d119a7b51b17 100644 --- a/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md +++ b/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md @@ -5,7 +5,7 @@ summary: Temporarily disable a TiDB Cloud Filesystem token. # ti fs disable-file-system-token -Disables an active token by immutable token ID without revoking it. A token used by a known local mount must be drained and unmounted first. +Disables an active token by immutable token ID without revoking it. A token used by a known local mount must be drained and unmounted first. When `--fs-token` or `TI_FS_TOKEN` supplies owner Bearer authentication, the target must be an `fs_scoped` token. Configured TiDB Cloud API keys can disable either token kind. > **Note:** > @@ -17,6 +17,7 @@ Disables an active token by immutable token ID without revoking it. A token used ti fs disable-file-system-token --file-system-id --token-id + [--fs-token ] [--dry-run] ``` @@ -24,6 +25,7 @@ ti fs disable-file-system-token - `--file-system-id `: Specify the Filesystem that owns the token. This option is required. - `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--fs-token `: Authorize the request with an owner FS token. Defaults to `TI_FS_TOKEN`; when neither is present, the command uses configured TiDB Cloud API keys. - `--dry-run`: Validate credentials, identifiers, and known local mount conflicts without disabling the token. For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). diff --git a/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md index 154bf16f78806..7cf4e63b9277d 100644 --- a/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md +++ b/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md @@ -5,7 +5,7 @@ summary: Enable a disabled TiDB Cloud Filesystem token. # ti fs enable-file-system-token -Changes a disabled token to active by immutable token ID. Authentication caches can take approximately 10 seconds to converge. +Changes a disabled token to active by immutable token ID. Authentication caches can take approximately 10 seconds to converge. When `--fs-token` or `TI_FS_TOKEN` supplies owner Bearer authentication, the target must be an `fs_scoped` token. Configured TiDB Cloud API keys can enable either token kind. > **Note:** > @@ -17,6 +17,7 @@ Changes a disabled token to active by immutable token ID. Authentication caches ti fs enable-file-system-token --file-system-id --token-id + [--fs-token ] [--dry-run] ``` @@ -24,6 +25,7 @@ ti fs enable-file-system-token - `--file-system-id `: Specify the Filesystem that owns the token. This option is required. - `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--fs-token `: Authorize the request with an owner FS token. Defaults to `TI_FS_TOKEN`; when neither is present, the command uses configured TiDB Cloud API keys. - `--dry-run`: Validate the request without changing remote token state. For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). diff --git a/ai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.md b/ai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.md new file mode 100644 index 0000000000000..2958ea7a97ddd --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.md @@ -0,0 +1,83 @@ +--- +title: ti fs generate-file-system-scoped-token +summary: Generate a path-and-operation-limited token for one TiDB Cloud Filesystem. +--- + +# ti fs generate-file-system-scoped-token + +Uses an owner Filesystem token to generate a finite `fs_scoped` token. The plaintext `fs_token` appears only in the successful response. A scoped token can access only its allowed path prefixes and operations. + +Scoped tokens support ordinary file, upload, Layer, and mount operations only when the requested paths and operations are covered. `chmod`, Git workspace APIs, Journal, Vault, SQL, fork, event, and token-management operations are not available to scoped tokens. Scoped tokens can refresh themselves without changing their scopes. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs generate-file-system-scoped-token + --ttl + --allow + [--file-system-id ] + [--fs-token ] + [--subject ] + [--store-locally] + [--replace] + [--dry-run] +``` + +## Options + +- `--ttl `: Set a finite positive token lifetime that resolves to whole seconds. This option is required. +- `--allow `: Allow operations under one remote path prefix. Repeat this option for multiple prefixes. Operations are `read`, `list`, `search`, `write`, and `delete`; `search` requires `read`. This option is required. +- `--file-system-id `: Assert the Filesystem ID embedded in the owner token. This option is required only when loading a locally stored owner token. +- `--fs-token `: Supply the owner token. Defaults to `TI_FS_TOKEN`, then the selected local credential. +- `--subject `: Set an optional server-side audit label of at most 64 bytes. It is not a unique selector. +- `--store-locally`: Store and select the generated scoped token for this profile and Filesystem. +- `--replace`: Replace an existing selected local token. Requires `--store-locally` and does not revoke the previous remote token. +- `--dry-run`: Validate the owner credential, region, lifetime, scopes, and local storage preconditions without generating a token. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Give a sandbox read and write access to one workspace: + + ```bash + # Use an owner token to create a 24-hour token limited to /workspace. + export TI_FS_TOKEN="" + ti fs generate-file-system-scoped-token \ + --subject sandbox-agent \ + --ttl 24h \ + --allow /workspace:read,list,write + ``` + +- Separate writable workspace data from read-only artifacts: + + ```bash + # Repeat --allow to assign different operations to independent prefixes. + ti fs generate-file-system-scoped-token \ + --fs-token "" \ + --ttl 8h \ + --allow /workspace:read,list,write,delete \ + --allow /artifacts:read,list + ``` + +- Select the generated scoped token for later local commands: + + ```bash + # Replacing the local selection does not revoke the previous remote owner token. + ti fs generate-file-system-scoped-token \ + --file-system-id "" \ + --ttl 1h \ + --allow /task:read,list,write \ + --store-locally \ + --replace + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [`ti fs generate-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) +- [`ti fs refresh-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md b/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md index 38188081cf9cb..acca25a89d175 100644 --- a/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md +++ b/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md @@ -16,6 +16,7 @@ Lists non-secret token metadata for one Filesystem. The response never contains ```text ti fs list-file-system-tokens --file-system-id + [--fs-token ] [--include-expired] [--limit ] [--offset ] @@ -24,6 +25,7 @@ ti fs list-file-system-tokens ## Options - `--file-system-id `: Specify the Filesystem whose tokens are listed. This option is required. +- `--fs-token `: Authorize the request with an owner FS token. Defaults to `TI_FS_TOKEN`; when neither is present, the command uses configured TiDB Cloud API keys. Scoped tokens cannot list token metadata. - `--include-expired`: Include expired token metadata. Revoked tokens are not returned by the service. - `--offset `: Set the zero-based token offset [default: 0]. - `--limit `: Set the maximum number of tokens to return, from 1 through 200 [default: 50]. @@ -55,4 +57,5 @@ For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli ## Related documentation - [`ti fs generate-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) +- [`ti fs generate-file-system-scoped-token`](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.md) - [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/ti/reference/ti-cli-reference.md b/ai/ti/reference/ti-cli-reference.md index c6d683327cb0b..735b6b2800ccd 100644 --- a/ai/ti/reference/ti-cli-reference.md +++ b/ai/ti/reference/ti-cli-reference.md @@ -42,6 +42,7 @@ ti │ ├── create-file-system │ ├── import-file-system-token │ ├── generate-file-system-token +│ ├── generate-file-system-scoped-token │ ├── list-file-system-tokens │ ├── enable-file-system-token │ ├── disable-file-system-token diff --git a/ai/ti/reference/ti-configuration-and-credentials.md b/ai/ti/reference/ti-configuration-and-credentials.md index a79611b4b801a..6881bafdd49a8 100644 --- a/ai/ti/reference/ti-configuration-and-credentials.md +++ b/ai/ti/reference/ti-configuration-and-credentials.md @@ -86,10 +86,12 @@ One profile can access multiple Filesystems. Drive9's remote inventory is author The credential contains the server-assigned file system ID, canonical region code, selected `api_key`, and optional authoritative token metadata, and uses owner-only permissions. `ti fs list-file-systems` reads remote resources and joins only the non-secret `has_local_token` hint. -One remote Filesystem can have multiple tokens, but each profile stores at most one selected token per Filesystem. The local store is an operational selection, not a replica of remote token inventory. Credentials created by provisioning or older imports might not contain `token_id`, `scope_kind`, `token_name`, or `expires_at`; they remain valid for data-plane use, and `ti` does not guess missing metadata from token-list rows. +One remote Filesystem can have multiple tokens, but each profile stores at most one selected token per Filesystem. The local store is an operational selection, not a replica of remote token inventory. Credentials created by provisioning or older imports might not contain `token_id`, `scope_kind`, `token_name`, `expires_at`, or `scopes`; they remain valid for data-plane use, and `ti` does not guess missing metadata from token-list rows. `ti fs generate-file-system-token` does not change the selected credential unless `--store-locally` is set. `--replace` changes only the local selection and leaves the previous remote token active. A refresh sourced from the local credential atomically replaces it. A refresh sourced from a flag or `TI_FS_TOKEN` returns the replacement plaintext without writing local state. +`ti fs generate-file-system-scoped-token` accepts only an owner token and can store its authoritative path scopes locally. The token JWT itself contains the Filesystem ID but not the token kind, token ID, or scopes. Therefore, an explicit or environment token is passed to the service for authorization instead of being classified locally. `TI_FS_TOKEN` can contain either an owner token or a scoped token; available operations depend on its server-side capability. + Resource selection is: 1. explicit `--file-system-id`; diff --git a/ai/ti/reference/ti-filesystem.md b/ai/ti/reference/ti-filesystem.md index f70d4686f3cfc..6035e1babba68 100644 --- a/ai/ti/reference/ti-filesystem.md +++ b/ai/ti/reference/ti-filesystem.md @@ -18,6 +18,7 @@ ti fs ├── create-file-system ├── import-file-system-token ├── generate-file-system-token +├── generate-file-system-scoped-token ├── list-file-system-tokens ├── enable-file-system-token ├── disable-file-system-token @@ -62,6 +63,7 @@ ti fs | `create-file-system` | Provisions a Filesystem with a server-assigned ID; `--wait` waits until data-plane access is ready. | `ti fs create-file-system --wait` | | `import-file-system-token` | Validates and stores an existing token under its embedded file system ID. | `ti fs import-file-system-token --from-file ./fs-token --region aws-us-east-1` | | `generate-file-system-token` | Generates an additional owner token and returns its plaintext once. | `ti fs generate-file-system-token --file-system-id --token-name ci --ttl 24h` | +| `generate-file-system-scoped-token` | Uses an owner token to generate a finite path-and-operation-limited token. | `ti fs generate-file-system-scoped-token --ttl 24h --allow /workspace:read,list` | | `list-file-system-tokens` | Lists non-secret token metadata for one Filesystem. | `ti fs list-file-system-tokens --file-system-id ` | | `enable-file-system-token` | Re-enables a disabled token by immutable token ID. | `ti fs enable-file-system-token --file-system-id --token-id ` | | `disable-file-system-token` | Temporarily disables a token by immutable token ID. | `ti fs disable-file-system-token --file-system-id --token-id ` |