docs: add TiDB Cloud CLI (tdc) Preview documentation

TOC-ai.md

@@ -5,8 +5,9 @@
 
 ## QUICK START
 
-- [Get Started via Python](/ai/quickstart-via-python.md)
-- [Get Started via SQL](/ai/quickstart-via-sql.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
 
@@ -23,7 +24,7 @@
     - [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)
@@ -84,3 +85,94 @@
 - [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)
+  - [Overview](/ai/tdc/tdc-overview.md)
+  - Command Reference
+    - [CLI Syntax and Global Behavior](/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
+      - [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)
+    - [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)

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)](/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) Reference ![PREVIEW](/media/tidb-cloud/blank_transparent_placeholder.png)
   - [Overview](/tidb-cloud/cli-reference.md)
   - auth
     - [login](/tidb-cloud/ticloud-auth-login.md)

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)

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) | 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
 
 Understand the foundational concepts behind AI-powered search in TiDB.
@@ -75,3 +82,45 @@ 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)
+
+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. |
+| [`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. |
+
+#### 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. |

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 <string>
+    --db-cluster-id <string>
+    [--dry-run]
+    [--help]
+    [--version]
+    [--wait]
+    [--debug]
+    [--output <string>]
+    [--profile <string>]
+    [--query <string>]
+    [--region <string>]
+```
+
+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 "<cluster-id>" --db-cluster-branch-name dev --wait
+tdc db create-db-cluster-branch --db-cluster-id "<cluster-id>" --db-cluster-branch-name preview --dry-run
+```

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 <string>
+    [--db-cluster-type <string>]
+    [--dry-run]
+    [--help]
+    [--monthly-spending-limit-usd-cents <int32>]
+    [--project-id <string>]
+    [--version]
+    [--wait]
+    [--debug]
+    [--output <string>]
+    [--profile <string>]
+    [--query <string>]
+    [--region <string>]
+```
+
+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
+```

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 <string>
+    [--dry-run]
+    [--help]
+    [--version]
+    [--debug]
+    [--output <string>]
+    [--profile <string>]
+    [--query <string>]
+    [--region <string>]
+```
+
+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 "<cluster-id>" --dry-run
+tdc db create-db-sql-users --db-cluster-id "<cluster-id>"
+```

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 <string>
+    --db-cluster-id <string>
+    [--dry-run]
+    [--help]
+    [--version]
+    [--debug]
+    [--output <string>]
+    [--profile <string>]
+    [--query <string>]
+    [--region <string>]
+```
+
+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 "<cluster-id>" --db-cluster-branch-id "<branch-id>" --dry-run
+tdc db delete-db-cluster-branch --db-cluster-id "<cluster-id>" --db-cluster-branch-id "<branch-id>"
+```