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](/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)
@@ -83,3 +84,100 @@
 - [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
+  - [TiDB Cloud Command Line Interface Overview](/ai/tdc/tdc-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)
+  - 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)
+    - 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)
+      - [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
+    - [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
+    - [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)

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 (Preview)
+
+| 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. |
+
 ## 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 (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 |
+| --- | --- |
+| [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. |
+
+#### 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. |
+
+#### 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,55 @@
+---
+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`. 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.
+
+## Syntax
+
+```text
+tdc db create-db-cluster-branch
+  --db-cluster-branch-name <string>
+  --db-cluster-id <string>
+  [--dry-run]
+  [--help]
+  [--version]
+  [--wait]
+```
+
+## Options
+
+- `--db-cluster-branch-name <string>`: Starter DB cluster branch display name. \[required]
+- `--db-cluster-id <string>`: Starter DB cluster ID. \[required]
+- `--dry-run`: Validate the request without applying changes.
+- `--help`: Display help 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:
+
+    ```bash
+    # Wait until the new database branch can accept connections.
+    tdc db create-db-cluster-branch --db-cluster-id "<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 "<cluster-id>" --db-cluster-branch-name preview --dry-run
+    ```
+
+## Related documentation
+
+- [TiDB Cloud Starter CLI Command Reference](/ai/tdc/reference/tdc-starter-database.md)