diff --git a/TOC-ai.md b/TOC-ai.md index e79d9a34cc2be..5d9a208c466ed 100644 --- a/TOC-ai.md +++ b/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) diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index 8ff041c162ee8..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](/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) 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 bf8a92d7832e7..83b962a76b979 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) | 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. | 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-agent-sandbox-example.md b/ai/tdc/reference/tdc-agent-sandbox-example.md new file mode 100644 index 0000000000000..fb2a9a64e1515 --- /dev/null +++ b/ai/tdc/reference/tdc-agent-sandbox-example.md @@ -0,0 +1,117 @@ +--- +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 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. +- 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 \ + --wait \ + --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 "$HOME/workspace" +tdc fs mount-file-system \ + --file-system-name agent-sandbox \ + --mount-path "$HOME/workspace" \ + --driver fuse + +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. + +## 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" +``` + +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 +``` + +## 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. +- Graceful unmount drains pending FUSE writes; deleting the sandbox without unmounting does not. + +## 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) 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 new file mode 100644 index 0000000000000..5e2a7dd091b81 --- /dev/null +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -0,0 +1,263 @@ +--- +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. + +## 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 +``` + +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: + +```text +tdc db describe-db-cluster + --db-cluster-id + [--output ] + [--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 | +| --- | --- | +| `--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 + +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 +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 start with a blank line and 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. + +## Feature guides + +The following task-oriented guides explain how commands work together. They are separate from the per-command reference pages. + +| 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 | + +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/reference/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..71d4ebc520c52 --- /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. + +## 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-daily-workflow-example.md b/ai/tdc/reference/tdc-daily-workflow-example.md new file mode 100644 index 0000000000000..be9e51d41c2bc --- /dev/null +++ b/ai/tdc/reference/tdc-daily-workflow-example.md @@ -0,0 +1,110 @@ +--- +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 \ + --dry-run + +tdc db create-db-cluster \ + --db-cluster-name daily-demo \ + --wait +``` + +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 \ + --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 + +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 + +- [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/reference/tdc-filesystem-git.md b/ai/tdc/reference/tdc-filesystem-git.md new file mode 100644 index 0000000000000..260a91444935e --- /dev/null +++ b/ai/tdc/reference/tdc-filesystem-git.md @@ -0,0 +1,116 @@ +--- +title: tdc fs-git Command Reference +summary: Reference every tdc fs-git command for cloning, hydrating, and managing linked Git worktrees. +--- + +# 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. + +> **Note:** +> +> 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. +- 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 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 background +``` + +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 + +```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. 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. + +## 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) diff --git a/ai/tdc/reference/tdc-filesystem-journal.md b/ai/tdc/reference/tdc-filesystem-journal.md new file mode 100644 index 0000000000000..658cb74c2f3bd --- /dev/null +++ b/ai/tdc/reference/tdc-filesystem-journal.md @@ -0,0 +1,101 @@ +--- +title: tdc fs-journal Command Reference +summary: Reference every tdc fs-journal command for creating, appending, reading, searching, and verifying 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. + +> **Note:** +> +> 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`. + +## 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/reference/tdc-journal-agent-workflow-example.md) +- [tdc 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 new file mode 100644 index 0000000000000..1fbb583f6b0ea --- /dev/null +++ b/ai/tdc/reference/tdc-filesystem-vault.md @@ -0,0 +1,172 @@ +--- +title: tdc fs-vault 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 + +`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. + +## 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. + +## 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/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/reference/tdc-filesystem.md b/ai/tdc/reference/tdc-filesystem.md new file mode 100644 index 0000000000000..811993a7cdcd6 --- /dev/null +++ b/ai/tdc/reference/tdc-filesystem.md @@ -0,0 +1,499 @@ +--- +title: tdc fs Command Reference +summary: Reference every tdc fs command for Filesystem resources, files, layers, packs, and mounts. +--- + +# tdc fs 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. + +## 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. +- 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 \ + --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)" +``` + +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 +``` + +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 + +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 | + +### 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 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 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 \ + --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 +``` + +### 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. 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 +``` + +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 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 + +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` | + +## 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) +- [tdc fs-git 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 new file mode 100644 index 0000000000000..8a9be1ac7c684 --- /dev/null +++ b/ai/tdc/reference/tdc-git-workspace-for-agents-example.md @@ -0,0 +1,103 @@ +--- +title: Prepare a Git Workspace for Agents on TiDB Cloud Filesystem +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 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. +- 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. 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 background +``` + +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 +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 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. + +## 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 + +- [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/reference/tdc-install-configure-update.md b/ai/tdc/reference/tdc-install-configure-update.md new file mode 100644 index 0000000000000..c84bd0ddc02cd --- /dev/null +++ b/ai/tdc/reference/tdc-install-configure-update.md @@ -0,0 +1,176 @@ +--- +title: tdc Installation, Configuration, and Update Command Reference +summary: Reference tdc release installation, configure and update commands, version checks, and uninstallation. +--- + +# tdc Installation, Configuration, and Update Command Reference + +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 + +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. + +### 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. + +## 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 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 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) +- [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/reference/tdc-journal-agent-workflow-example.md b/ai/tdc/reference/tdc-journal-agent-workflow-example.md new file mode 100644 index 0000000000000..e5db1e3e377a5 --- /dev/null +++ b/ai/tdc/reference/tdc-journal-agent-workflow-example.md @@ -0,0 +1,96 @@ +--- +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 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. + +## 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 + +- [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/reference/tdc-organization.md b/ai/tdc/reference/tdc-organization.md new file mode 100644 index 0000000000000..5ec7471c18f4b --- /dev/null +++ b/ai/tdc/reference/tdc-organization.md @@ -0,0 +1,73 @@ +--- +title: tdc organization Command Reference +summary: Reference the tdc organization command tree, project listing inputs, output, and examples. +--- + +# tdc organization 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. + +## 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. Pass an explicit project ID to override it for one cluster: + +```bash +tdc db create-db-cluster \ + --db-cluster-name project-specific-cluster \ + --project-id "" +``` + +## 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) 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/reference/tdc-query-sql-with-roles-example.md b/ai/tdc/reference/tdc-query-sql-with-roles-example.md new file mode 100644 index 0000000000000..8d574a21d8fe6 --- /dev/null +++ b/ai/tdc/reference/tdc-query-sql-with-roles-example.md @@ -0,0 +1,115 @@ +--- +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 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. +- 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 + +- [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 new file mode 100644 index 0000000000000..612701e9ef24d --- /dev/null +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -0,0 +1,103 @@ +--- +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 in: + +| 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. + +## 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 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 + +| 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. + +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. +- 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. +- 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 + +- [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/reference/tdc-share-filesystem-across-machines-example.md b/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md new file mode 100644 index 0000000000000..f291f36946632 --- /dev/null +++ b/ai/tdc/reference/tdc-share-filesystem-across-machines-example.md @@ -0,0 +1,106 @@ +--- +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 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. +- 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 \ + --wait \ + --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 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 +``` + +On machine A: + +```bash +tdc fs delete-file-system \ + --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 graceful unmount completes. Use an explicit drain only when you need remote durability while keeping the FUSE mount online. + +## What's next + +- [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/reference/tdc-starter-database.md b/ai/tdc/reference/tdc-starter-database.md new file mode 100644 index 0000000000000..0136464095d93 --- /dev/null +++ b/ai/tdc/reference/tdc-starter-database.md @@ -0,0 +1,222 @@ +--- +title: tdc db Command Reference +summary: Reference every tdc db command for Starter clusters, branches, SQL users, connection strings, and SQL execution. +--- + +# tdc db 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. + +## 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`. +- 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 \ + --dry-run + +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. + +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 "" \ + --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. + +## Manage branches + +Create and list branches: + +```bash +tdc db create-db-cluster-branch \ + --db-cluster-id "" \ + --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. 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: + +```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. + +## 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) diff --git a/ai/tdc/reference/tdc-troubleshooting.md b/ai/tdc/reference/tdc-troubleshooting.md new file mode 100644 index 0000000000000..346b697d03708 --- /dev/null +++ b/ai/tdc/reference/tdc-troubleshooting.md @@ -0,0 +1,212 @@ +--- +title: Troubleshoot tdc +summary: Diagnose tdc authentication, project, Filesystem selection, companion, quota, SQL user, mount, and interrupted-cleanup failures. +--- + +# Troubleshoot tdc + +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:** +> +> 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:`. + +## 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 [tdc fs Command Reference](/ai/tdc/reference/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: + +```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, and then retry: + +```bash +tdc 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. + +## 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 "" \ + --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/reference/tdc-vault-agent-secrets-example.md b/ai/tdc/reference/tdc-vault-agent-secrets-example.md new file mode 100644 index 0000000000000..543da0688e721 --- /dev/null +++ b/ai/tdc/reference/tdc-vault-agent-secrets-example.md @@ -0,0 +1,109 @@ +--- +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 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. +- 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 + +- [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 new file mode 100644 index 0000000000000..0f05cb99050c8 --- /dev/null +++ b/ai/tdc/tdc-overview.md @@ -0,0 +1,103 @@ +--- +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. +--- + +# TiDB Cloud CLI (tdc) 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. + +> **Note:** +> +> tdc is currently in Preview. Its features and command-line interface might change without prior notice. + +## When to use tdc + +Use tdc 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 tdc does not provide, use `ticloud`. + +## tdc, 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 | +| 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. + +## 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: + +```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. + +## 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: + +- [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) + +### Scenario references + +Use scenarios to follow a complete workflow that combines multiple commands and features: + +For users and automation: + +- [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/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 + +- [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) + +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..80a30653ec992 --- /dev/null +++ b/ai/tdc/tdc-quick-start.md @@ -0,0 +1,151 @@ +--- +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. + +## 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). + +## 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 + +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, 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: + +```bash +tdc configure +``` + +Enter your API public key, private key, and a canonical region code such as `aws-us-east-1`. + +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 make it the default: + +```bash +tdc fs create-file-system \ + --file-system-name quickstart-fs \ + --set-default \ + --wait \ + --output text +``` + +tdc stores the Filesystem credential locally. Write and read a file directly: + +```bash +printf 'hello from tdc\n' | tdc fs copy-file \ + --from-stdin \ + --to-remote /hello.txt + +tdc fs read-file --path /hello.txt +``` + +Expected output: + +```text +hello from tdc +``` + +Clean up: + +```bash +tdc fs delete-file-system \ + --file-system-name quickstart-fs +``` + +### Option B: Query a Starter database + +Create a Starter cluster and save its ID: + +```bash +export TDC_DB_CLUSTER_ID="$(tdc db create-db-cluster \ + --db-cluster-name quickstart-db \ + --wait \ + --query id \ + --output text)" +``` + +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 \ + --sql "SELECT 1 AS ready" \ + --output text +``` + +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" \ + --wait +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) diff --git a/tidb-cloud/cli-reference.md b/tidb-cloud/cli-reference.md index 742ddb62356e7..f7f63a4262b6e 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 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 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 `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 425c141e73763..affe2208a89a8 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 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 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 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.