diff --git a/TOC-ai.md b/TOC-ai.md index 6437c43935a39..d72cee2f128de 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](/ai/ti/ti-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) @@ -82,3 +83,105 @@ - [Vector Search Index](/ai/reference/vector-search-index.md) - [Vector Search Performance Tuning](/ai/reference/vector-search-improve-performance.md) - [Vector Search Limitations](/ai/reference/vector-search-limitations.md) +- TiDB Cloud CLI + - [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) + - Guides + - [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) + - [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) + - [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) + - [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) + - [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) + - [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) + - Command Reference + - [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) + - [configure](/ai/ti/reference/commands/ti/ti-configure.md) + - [update](/ai/ti/reference/commands/ti/ti-update.md) + - db + - [create-db-cluster](/ai/ti/reference/commands/db/ti-db-create-db-cluster.md) + - [list-db-clusters](/ai/ti/reference/commands/db/ti-db-list-db-clusters.md) + - [describe-db-cluster](/ai/ti/reference/commands/db/ti-db-describe-db-cluster.md) + - [update-db-cluster](/ai/ti/reference/commands/db/ti-db-update-db-cluster.md) + - [delete-db-cluster](/ai/ti/reference/commands/db/ti-db-delete-db-cluster.md) + - [create-db-cluster-branch](/ai/ti/reference/commands/db/ti-db-create-db-cluster-branch.md) + - [list-db-cluster-branches](/ai/ti/reference/commands/db/ti-db-list-db-cluster-branches.md) + - [describe-db-cluster-branch](/ai/ti/reference/commands/db/ti-db-describe-db-cluster-branch.md) + - [delete-db-cluster-branch](/ai/ti/reference/commands/db/ti-db-delete-db-cluster-branch.md) + - [create-db-sql-users](/ai/ti/reference/commands/db/ti-db-create-db-sql-users.md) + - [format-db-connection-string](/ai/ti/reference/commands/db/ti-db-format-db-connection-string.md) + - [execute-sql-statement](/ai/ti/reference/commands/db/ti-db-execute-sql-statement.md) + - fs + - [create-file-system](/ai/ti/reference/commands/fs/ti-fs-create-file-system.md) + - [import-file-system-token](/ai/ti/reference/commands/fs/ti-fs-import-file-system-token.md) + - [generate-file-system-token](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) + - [generate-file-system-scoped-token](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.md) + - [list-file-system-tokens](/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md) + - [enable-file-system-token](/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md) + - [disable-file-system-token](/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md) + - [delete-file-system-token](/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md) + - [refresh-file-system-token](/ai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.md) + - [list-file-systems](/ai/ti/reference/commands/fs/ti-fs-list-file-systems.md) + - [describe-file-system](/ai/ti/reference/commands/fs/ti-fs-describe-file-system.md) + - [check-file-system](/ai/ti/reference/commands/fs/ti-fs-check-file-system.md) + - [delete-file-system](/ai/ti/reference/commands/fs/ti-fs-delete-file-system.md) + - [copy-file](/ai/ti/reference/commands/fs/ti-fs-copy-file.md) + - [read-file](/ai/ti/reference/commands/fs/ti-fs-read-file.md) + - [list-files](/ai/ti/reference/commands/fs/ti-fs-list-files.md) + - [describe-file](/ai/ti/reference/commands/fs/ti-fs-describe-file.md) + - [move-file](/ai/ti/reference/commands/fs/ti-fs-move-file.md) + - [delete-file](/ai/ti/reference/commands/fs/ti-fs-delete-file.md) + - [create-directory](/ai/ti/reference/commands/fs/ti-fs-create-directory.md) + - [chmod-file](/ai/ti/reference/commands/fs/ti-fs-chmod-file.md) + - [create-symlink](/ai/ti/reference/commands/fs/ti-fs-create-symlink.md) + - [create-hardlink](/ai/ti/reference/commands/fs/ti-fs-create-hardlink.md) + - [search-file-content](/ai/ti/reference/commands/fs/ti-fs-search-file-content.md) + - [find-files](/ai/ti/reference/commands/fs/ti-fs-find-files.md) + - [create-layer](/ai/ti/reference/commands/fs/ti-fs-create-layer.md) + - [list-layers](/ai/ti/reference/commands/fs/ti-fs-list-layers.md) + - [describe-layer](/ai/ti/reference/commands/fs/ti-fs-describe-layer.md) + - [diff-layer](/ai/ti/reference/commands/fs/ti-fs-diff-layer.md) + - [create-layer-checkpoint](/ai/ti/reference/commands/fs/ti-fs-create-layer-checkpoint.md) + - [rollback-layer](/ai/ti/reference/commands/fs/ti-fs-rollback-layer.md) + - [commit-layer](/ai/ti/reference/commands/fs/ti-fs-commit-layer.md) + - [pack-file-system](/ai/ti/reference/commands/fs/ti-fs-pack-file-system.md) + - [unpack-file-system](/ai/ti/reference/commands/fs/ti-fs-unpack-file-system.md) + - [mount-file-system](/ai/ti/reference/commands/fs/ti-fs-mount-file-system.md) + - [drain-file-system](/ai/ti/reference/commands/fs/ti-fs-drain-file-system.md) + - [unmount-file-system](/ai/ti/reference/commands/fs/ti-fs-unmount-file-system.md) + - fs-git + - [clone-git-workspace](/ai/ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.md) + - [hydrate-git-workspace](/ai/ti/reference/commands/fs-git/ti-fs-git-hydrate-git-workspace.md) + - [add-git-worktree](/ai/ti/reference/commands/fs-git/ti-fs-git-add-git-worktree.md) + - [remove-git-worktree](/ai/ti/reference/commands/fs-git/ti-fs-git-remove-git-worktree.md) + - fs-journal + - [create-journal](/ai/ti/reference/commands/fs-journal/ti-fs-journal-create-journal.md) + - [append-journal-entries](/ai/ti/reference/commands/fs-journal/ti-fs-journal-append-journal-entries.md) + - [read-journal-entries](/ai/ti/reference/commands/fs-journal/ti-fs-journal-read-journal-entries.md) + - [search-journal-entries](/ai/ti/reference/commands/fs-journal/ti-fs-journal-search-journal-entries.md) + - [verify-journal](/ai/ti/reference/commands/fs-journal/ti-fs-journal-verify-journal.md) + - fs-vault + - [create-secret](/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-secret.md) + - [replace-secret](/ai/ti/reference/commands/fs-vault/ti-fs-vault-replace-secret.md) + - [read-secret](/ai/ti/reference/commands/fs-vault/ti-fs-vault-read-secret.md) + - [list-secrets](/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-secrets.md) + - [delete-secret](/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-secret.md) + - [create-grant](/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-grant.md) + - [delete-grant](/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-grant.md) + - [list-audit-events](/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-audit-events.md) + - [run-with-secret](/ai/ti/reference/commands/fs-vault/ti-fs-vault-run-with-secret.md) + - [mount-vault](/ai/ti/reference/commands/fs-vault/ti-fs-vault-mount-vault.md) + - [unmount-vault](/ai/ti/reference/commands/fs-vault/ti-fs-vault-unmount-vault.md) + - Scenarios for Users and Automation + - [Run a Daily TiDB Cloud CLI Workflow](/ai/ti/reference/ti-daily-workflow-example.md) + - [Query TiDB Cloud Starter with Explicit SQL Roles](/ai/ti/reference/ti-query-sql-with-roles-example.md) + - [Share a TiDB Cloud Filesystem Across Machines](/ai/ti/reference/ti-share-filesystem-across-machines-example.md) + - [Hand Off CI Artifacts Between Isolated Jobs with TiDB Cloud Filesystem](/ai/ti/reference/ti-ci-artifact-handoff-example.md) + - Scenarios for AI Agents + - [Use TiDB Cloud Filesystem in an Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) + - [Persist Agent State Across Disposable Sandboxes with TiDB Cloud Filesystem](/ai/ti/reference/ti-persistent-agent-state-example.md) + - [Share a Read-Only Dataset Across Parallel Agents with TiDB Cloud Filesystem](/ai/ti/reference/ti-parallel-agent-dataset-example.md) + - [Prepare a Git Workspace for Agents on TiDB Cloud Filesystem](/ai/ti/reference/ti-git-workspace-for-agents-example.md) + - [Record an Agent Workflow in a TiDB Cloud Filesystem Journal](/ai/ti/reference/ti-journal-agent-workflow-example.md) + - [Delegate TiDB Cloud Filesystem Vault Secrets to an Agent](/ai/ti/reference/ti-vault-agent-secrets-example.md) + - [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) + - [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) + - [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index d3e987ae4d5ca..387ccf240a5a5 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) @@ -460,7 +460,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 aa318fe47688c..68f027f66b007 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 (Preview) + +| Document | Description | +| --- | --- | +| [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) | Learn when to use the TiDB Cloud CLI, how it differs from the `ticloud` CLI and TiDB Cloud console, and which Starter and Filesystem workflows it supports. | +| [Get Started with TiDB Cloud CLI](/ai/ti/ti-quick-start.md) | Install and configure the TiDB Cloud CLI, then complete a first database or Filesystem operation. | + ## Concepts Understand the foundational concepts behind AI-powered search in TiDB. @@ -74,3 +81,45 @@ Technical reference documentation for TiDB's AI and vector search features. | [Vector Search Index](/ai/reference/vector-search-index.md) | Create and manage vector indexes for performance. | | [Performance Tuning](/ai/reference/vector-search-improve-performance.md) | Optimize vector search performance. | | [Limitations](/ai/reference/vector-search-limitations.md) | Current limitations and constraints. | + +### TiDB Cloud CLI (Preview) + +The command reference follows the two-level `ti` command tree. Every command has a dedicated page with its syntax and examples. Expand **Command Reference** in the documentation navigation to browse commands by family. + +#### Command reference + +| Document | Description | +| --- | --- | +| [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) | Decide when to use the TiDB Cloud CLI and understand its scope relative to `ticloud` and the TiDB Cloud console. | +| [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) | Command tree, global flags, output, queries, dry-run, help, errors, aliases, and links to command pages. | +| [`ti configure`](/ai/ti/reference/commands/ti/ti-configure.md) | Configure a local profile interactively or non-interactively. | +| [`ti update`](/ai/ti/reference/commands/ti/ti-update.md) | Check for and install release updates. | +| [`ti db create-db-cluster`](/ai/ti/reference/commands/db/ti-db-create-db-cluster.md) | Start with the database command reference. | +| [`ti fs create-file-system`](/ai/ti/reference/commands/fs/ti-fs-create-file-system.md) | Start with the Filesystem command reference. | +| [`ti fs import-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-import-file-system-token.md) | Restore local access from an existing FS token. | +| [`ti fs-git clone-git-workspace`](/ai/ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.md) | Start with the Filesystem Git command reference. | +| [`ti fs-journal create-journal`](/ai/ti/reference/commands/fs-journal/ti-fs-journal-create-journal.md) | Start with the Filesystem journal command reference. | +| [`ti fs-vault create-secret`](/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-secret.md) | Start with the Filesystem Vault command reference. | +| [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) | Profiles, precedence, local state, credentials, mount locators, and logs. | +| [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) | Placement, authentication boundaries, platforms, durability, and preview constraints. | +| [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) | Diagnose authentication, quota, SQL, companion, selection, and mount failures. | + +#### Scenarios for users and automation + +| Document | Description | +| --- | --- | +| [Daily Workflow](/ai/ti/reference/ti-daily-workflow-example.md) | Manage one Starter cluster and Filesystem in a routine operator flow. | +| [Query SQL with Roles](/ai/ti/reference/ti-query-sql-with-roles-example.md) | Use explicit read-only, read-write, and admin SQL roles. | +| [Share a Filesystem Across Machines](/ai/ti/reference/ti-share-filesystem-across-machines-example.md) | Transfer an owner token securely and verify cross-machine visibility. | +| [Hand Off CI Artifacts Between Jobs](/ai/ti/reference/ti-ci-artifact-handoff-example.md) | Persist build output across isolated jobs without copying a complete TiDB Cloud CLI profile. | + +#### Scenarios for AI agents + +| Document | Description | +| --- | --- | +| [Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) | Give a clean sandbox Filesystem access without TiDB Cloud API keys. | +| [Persistent Agent State](/ai/ti/reference/ti-persistent-agent-state-example.md) | Preserve plans, checkpoints, and results across disposable sandboxes. | +| [Parallel Agent Dataset](/ai/ti/reference/ti-parallel-agent-dataset-example.md) | Give multiple agents read-only access to one shared unstructured dataset. | +| [Git Workspace for Agents](/ai/ti/reference/ti-git-workspace-for-agents-example.md) | Prepare a mounted Git workspace and isolated linked worktree. | +| [Journal an Agent Workflow](/ai/ti/reference/ti-journal-agent-workflow-example.md) | Record structured events and verify their hash chain. | +| [Delegate Vault Secrets](/ai/ti/reference/ti-vault-agent-secrets-example.md) | Grant an agent temporary access to one secret field. | diff --git a/ai/ti/reference/commands/db/ti-db-create-db-cluster-branch.md b/ai/ti/reference/commands/db/ti-db-create-db-cluster-branch.md new file mode 100644 index 0000000000000..9e37e300918ea --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-create-db-cluster-branch.md @@ -0,0 +1,55 @@ +--- +title: ti db create-db-cluster-branch +summary: Create a branch for a TiDB Cloud Starter cluster. +--- + +# ti db create-db-cluster-branch + +Creates a branch for one Starter cluster. `--wait` waits for the branch to become `ACTIVE`. The command verifies that the parent cluster is Starter before creating the branch. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti db create-db-cluster-branch + --db-cluster-branch-name + --db-cluster-id + [--dry-run] + [--help] + [--version] + [--wait] +``` + +## Options + +- `--db-cluster-branch-name `: Starter DB cluster branch display name. \[required] +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--version`: Display version information. +- `--wait`: Wait until the created branch becomes `ACTIVE` before returning. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create a branch and wait until it is active: + + ```bash + # Wait until the new database branch can accept connections. + ti db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name dev --wait + ``` + +- Preview branch creation: + + ```bash + # Validate the parent cluster and branch request without creating it. + ti db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name preview --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/db/ti-db-create-db-cluster.md b/ai/ti/reference/commands/db/ti-db-create-db-cluster.md new file mode 100644 index 0000000000000..2809f2712200f --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-create-db-cluster.md @@ -0,0 +1,71 @@ +--- +title: ti db create-db-cluster +summary: Create a TiDB Cloud Starter cluster. +--- + +# ti db create-db-cluster + +Creates a Starter cluster. The required `--db-cluster-type` must be `starter`; there is no implicit type. `--wait` waits for the cluster to become `ACTIVE`. The request omits project selection and lets TiDB Cloud select its server-side default project. The TiDB Cloud CLI validates the returned service plan; if verification fails after creation is accepted, it reports the cluster ID and retains the cluster for inspection. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti db create-db-cluster + --db-cluster-name + --db-cluster-type + [--dry-run] + [--help] + [--monthly-spending-limit-usd-cents ] + [--version] + [--wait] +``` + +## Options + +- `--db-cluster-name `: Starter DB cluster display name. \[required] +- `--db-cluster-type `: DB cluster type; must be `starter`. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--monthly-spending-limit-usd-cents `: Monthly spending limit in USD cents; omit to use the API default. +- `--version`: Display version information. +- `--wait`: Wait until the created cluster becomes `ACTIVE` before returning. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create a cluster and wait until it is active: + + ```bash + # Wait until the new Starter cluster reaches the ACTIVE state. + ti db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --wait + ``` + +- Create a cluster asynchronously: + + ```bash + # Return after TiDB Cloud accepts creation so another process can poll the cluster. + ti db create-db-cluster --db-cluster-type starter --db-cluster-name background-db + ``` + +- Preview cluster creation: + + ```bash + # Validate the request and resolved defaults without creating a cluster. + ti db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --dry-run + ``` + +- Set a monthly spending limit: + + ```bash + # Create a paid Starter cluster with a monthly limit expressed in US dollar cents. + ti db create-db-cluster --db-cluster-type starter --db-cluster-name production-db --monthly-spending-limit-usd-cents 1000 --wait + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/db/ti-db-create-db-sql-users.md b/ai/ti/reference/commands/db/ti-db-create-db-sql-users.md new file mode 100644 index 0000000000000..d8700c05a8167 --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-create-db-sql-users.md @@ -0,0 +1,51 @@ +--- +title: ti db create-db-sql-users +summary: Create TiDB Cloud CLI-managed SQL users for a Starter cluster. +--- + +# ti db create-db-sql-users + +Idempotently creates or repairs the read-only, read-write, and admin SQL users managed by `ti`. The command verifies that the cluster is Starter before calling SQL-user APIs or writing local credentials. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti db create-db-sql-users + --db-cluster-id + [--dry-run] + [--help] + [--version] +``` + +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create the managed SQL users: + + ```bash + # Create or reconcile the read-only, read-write, and admin SQL users. + ti db create-db-sql-users --db-cluster-id "" + ``` + +- Preview SQL user creation: + + ```bash + # Show the three managed roles without changing SQL users or local credentials. + ti db create-db-sql-users --db-cluster-id "" --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/db/ti-db-delete-db-cluster-branch.md b/ai/ti/reference/commands/db/ti-db-delete-db-cluster-branch.md new file mode 100644 index 0000000000000..c5bc5f668abaf --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-delete-db-cluster-branch.md @@ -0,0 +1,46 @@ +--- +title: ti db delete-db-cluster-branch +summary: Delete a branch from a TiDB Cloud Starter cluster. +--- + +# ti db delete-db-cluster-branch + +Deletes one branch from a Starter cluster. The command verifies that the parent cluster is Starter before reading or deleting the branch. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti db delete-db-cluster-branch + --db-cluster-branch-id + --db-cluster-id + [--dry-run] + [--help] + [--version] +``` + +## Options + +- `--db-cluster-branch-id `: Starter DB cluster branch ID. \[required] +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Delete a branch: + + ```bash + # Delete only the selected branch from its parent Starter cluster. + ti db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/db/ti-db-delete-db-cluster.md b/ai/ti/reference/commands/db/ti-db-delete-db-cluster.md new file mode 100644 index 0000000000000..8fedac716c62c --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-delete-db-cluster.md @@ -0,0 +1,53 @@ +--- +title: ti db delete-db-cluster +summary: Delete a TiDB Cloud Starter cluster. +--- + +# ti db delete-db-cluster + +Deletes one Starter cluster. `--wait` waits until deletion is observable. The command verifies the service plan before sending the delete request and rejects non-Starter or unverifiable clusters without sending `DELETE`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti db delete-db-cluster + --db-cluster-id + [--dry-run] + [--help] + [--version] + [--wait] +``` + +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--version`: Display version information. +- `--wait`: Wait until the deleted cluster reaches `DELETED` or is no longer accessible. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Delete a cluster and wait for completion: + + ```bash + # Wait until TiDB Cloud reports the cluster deleted or no longer accessible. + ti db delete-db-cluster --db-cluster-id "" --wait + ``` + +- Delete a cluster asynchronously: + + ```bash + # Return after TiDB Cloud accepts deletion while cleanup continues remotely. + ti db delete-db-cluster --db-cluster-id "" + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/db/ti-db-describe-db-cluster-branch.md b/ai/ti/reference/commands/db/ti-db-describe-db-cluster-branch.md new file mode 100644 index 0000000000000..71717cf6a1007 --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-describe-db-cluster-branch.md @@ -0,0 +1,46 @@ +--- +title: ti db describe-db-cluster-branch +summary: Describe a branch for a TiDB Cloud Starter cluster. +--- + +# ti db describe-db-cluster-branch + +Describes one branch by cluster ID and branch ID. The command verifies that the parent cluster is Starter before reading the branch. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti db describe-db-cluster-branch + --db-cluster-branch-id + --db-cluster-id + [--help] + [--version] + [--view ] +``` + +## Options + +- `--db-cluster-branch-id `: Starter DB cluster branch ID. \[required] +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--help`: Display help information. +- `--version`: Display version information. +- `--view `: Detail level: `BASIC` or `FULL`. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Describe a branch: + + ```bash + # Return full lifecycle and connection details for one branch. + ti db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" --view FULL + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/db/ti-db-describe-db-cluster.md b/ai/ti/reference/commands/db/ti-db-describe-db-cluster.md new file mode 100644 index 0000000000000..84bd40e24bc8b --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-describe-db-cluster.md @@ -0,0 +1,44 @@ +--- +title: ti db describe-db-cluster +summary: Describe a TiDB Cloud Starter cluster. +--- + +# ti db describe-db-cluster + +Describes one Starter cluster. Use `--view FULL` to request expanded fields. The command rejects the cluster if its API metadata does not verify it as Starter. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti db describe-db-cluster + --db-cluster-id + [--help] + [--version] + [--view ] +``` + +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--help`: Display help information. +- `--version`: Display version information. +- `--view `: Detail level: `BASIC` or `FULL`. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Describe a cluster: + + ```bash + # Return the cluster state, placement, and connection metadata. + ti db describe-db-cluster --db-cluster-id "" --view FULL + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/db/ti-db-execute-sql-statement.md b/ai/ti/reference/commands/db/ti-db-execute-sql-statement.md new file mode 100644 index 0000000000000..965871e872f94 --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-execute-sql-statement.md @@ -0,0 +1,75 @@ +--- +title: ti db execute-sql-statement +summary: Execute one SQL statement against a TiDB Cloud Starter cluster. +--- + +# ti db execute-sql-statement + +Executes exactly one SQL statement. Read-write is the default role; explicit role selection is recommended. The command verifies that the cluster is Starter before loading credentials or sending an HTTPS or MySQL request. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti db execute-sql-statement + --db-cluster-id + --sql + [--admin] + [--database ] + [--help] + [--read-only] + [--read-write] + [--transport ] + [--version] +``` + +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--sql `: One SQL statement to execute. \[required] +- `--admin`: Use prepared admin DB SQL credentials. +- `--database `: Database/default schema name. +- `--help`: Display help information. +- `--read-only`: Use prepared `read_only` DB SQL credentials. +- `--read-write`: Use prepared `read_write` DB SQL credentials. +- `--transport `: SQL execution transport: `https` or `mysql`. \[default: https] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Run a statement with the default read-write role: + + ```bash + # Use the default prepared role for normal application reads and writes. + ti db execute-sql-statement --db-cluster-id "" --sql "INSERT INTO app.events(message) VALUES ('ready')" + ``` + +- Run a read-only query: + + ```bash + # Prevent the statement from using read-write or admin credentials. + ti db execute-sql-statement --db-cluster-id "" --read-only --sql "SELECT 1 AS ready" --output text + ``` + +- Run an administrative statement: + + ```bash + # Use the admin role for schema creation or privilege management. + ti db execute-sql-statement --db-cluster-id "" --admin --sql "CREATE DATABASE IF NOT EXISTS app" + ``` + +- Use the MySQL fallback transport: + + ```bash + # Open a one-shot MySQL connection when the HTTPS SQL API is unsuitable. + ti db execute-sql-statement --db-cluster-id "" --transport mysql --sql "SELECT CURRENT_TIMESTAMP" + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/db/ti-db-format-db-connection-string.md b/ai/ti/reference/commands/db/ti-db-format-db-connection-string.md new file mode 100644 index 0000000000000..3261a82bc5bb4 --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-format-db-connection-string.md @@ -0,0 +1,79 @@ +--- +title: ti db format-db-connection-string +summary: Format a connection string for a TiDB Cloud CLI-managed SQL user. +--- + +# ti db format-db-connection-string + +Formats stored SQL credentials for read-write, read-only, or admin access. The command verifies that the cluster is Starter before loading its local SQL credentials. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti 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] +``` + +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--admin`: Use prepared admin DB SQL credentials. +- `--database `: Database/default schema name. +- `--env-database-url-name `: Database URL variable name for `--format env`. \[default: DATABASE_URL] +- `--env-include-database-url`: Include a database URL variable with `--format env`. +- `--env-prefix `: Dotenv variable prefix for `--format env`. \[default: TIDB_] +- `--format `: Connection string format: `mysql-uri`, `jdbc`, `go-sql-driver`, `sqlalchemy`, or `env`. \[default: mysql-uri] +- `--help`: Display help information. +- `--read-only`: Use prepared `read_only` DB SQL credentials. +- `--read-write`: Use prepared `read_write` DB SQL credentials. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Format a read-write MySQL URI: + + ```bash + # Use the default application role in tools that accept a MySQL URI. + ti db format-db-connection-string --db-cluster-id "" --read-write --format mysql-uri + ``` + +- Format read-only dotenv variables: + + ```bash + # Emit environment assignments for a workload that must not modify data. + ti db format-db-connection-string --db-cluster-id "" --read-only --format env --env-prefix TIDB_ + ``` + +- Format an admin JDBC URL: + + ```bash + # Generate a JDBC connection value with the prepared admin credentials. + ti db format-db-connection-string --db-cluster-id "" --admin --format jdbc --database app + ``` + +- Include DATABASE_URL in dotenv output: + + ```bash + # Emit both component variables and a conventional DATABASE_URL value. + ti db format-db-connection-string --db-cluster-id "" --format env --env-include-database-url + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/db/ti-db-list-db-cluster-branches.md b/ai/ti/reference/commands/db/ti-db-list-db-cluster-branches.md new file mode 100644 index 0000000000000..afee7bd7cef00 --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-list-db-cluster-branches.md @@ -0,0 +1,46 @@ +--- +title: ti db list-db-cluster-branches +summary: List branches for a TiDB Cloud Starter cluster. +--- + +# ti db list-db-cluster-branches + +Lists branches for one Starter cluster, with optional pagination. The command verifies that the parent cluster is Starter before listing branches. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti db list-db-cluster-branches + --db-cluster-id + [--help] + [--page-size ] + [--page-token ] + [--version] +``` + +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--help`: Display help information. +- `--page-size `: Number of branches to request; 0 uses the API default. +- `--page-token `: Page token returned by a previous list-db-cluster-branches call. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- List cluster branches: + + ```bash + # Return all branches that belong to the selected Starter cluster. + ti db list-db-cluster-branches --db-cluster-id "" + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/db/ti-db-list-db-clusters.md b/ai/ti/reference/commands/db/ti-db-list-db-clusters.md new file mode 100644 index 0000000000000..1906fd10055d2 --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-list-db-clusters.md @@ -0,0 +1,66 @@ +--- +title: ti db list-db-clusters +summary: List TiDB Cloud Starter clusters. +--- + +# ti db list-db-clusters + +Lists verified Starter clusters in the effective region with pagination, filtering, ordering, and JMESPath projection. The required `--db-cluster-type` must be `starter`. Cross-region, non-Starter, and unverifiable clusters are omitted. The command incrementally fills each result page from TiDB Cloud API pages and returns an opaque ti `next_page_token`; it omits the server `total_size`, which can include resources outside the verified result. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti db list-db-clusters + --db-cluster-type + [--filter ] + [--help] + [--order-by ] + [--page-size ] + [--page-token ] + [--version] +``` + +## Options + +- `--db-cluster-type `: DB cluster type; must be `starter`. \[required] +- `--filter `: Starter API filter expression. +- `--help`: Display help information. +- `--order-by `: Starter API orderBy expression. +- `--page-size `: Number of verified clusters to return; 0 returns 10 and the maximum is 1000. +- `--page-token `: Opaque ti page token returned by a previous compatible list-db-clusters call. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- List clusters: + + ```bash + # Return Starter clusters in the profile's configured region as structured JSON. + ti db list-db-clusters --db-cluster-type starter + ``` + +- List clusters in another region: + + ```bash + # Override the region for this invocation without changing the profile. + ti --region aws-us-west-2 db list-db-clusters --db-cluster-type starter + ``` + +- Select cluster fields: + + ```bash + # Reduce the result to IDs, names, and lifecycle states. + ti db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name,state:state}' + ``` + +The effective region resolves from global `--region`, then `TI_REGION_CODE`, then the selected profile's `region_code`. User-supplied `--filter` expressions are combined with this mandatory region scope and cannot expand the result to other regions. A page token can be reused only with the same profile, cluster type, region, filter, and ordering. If its replay page changed, restart the listing without `--page-token`. + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/db/ti-db-update-db-cluster.md b/ai/ti/reference/commands/db/ti-db-update-db-cluster.md new file mode 100644 index 0000000000000..6beea73b90d6b --- /dev/null +++ b/ai/ti/reference/commands/db/ti-db-update-db-cluster.md @@ -0,0 +1,55 @@ +--- +title: ti db update-db-cluster +summary: Update a TiDB Cloud Starter cluster. +--- + +# ti db update-db-cluster + +Updates the display name or monthly spending limit of one Starter cluster. The command verifies the service plan before sending the update and rejects non-Starter or unverifiable clusters without sending `PATCH`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti db update-db-cluster + --db-cluster-id + [--db-cluster-name ] + [--dry-run] + [--help] + [--monthly-spending-limit-usd-cents ] + [--version] +``` + +## Options + +- `--db-cluster-id `: Starter DB cluster ID. \[required] +- `--db-cluster-name `: New Starter DB cluster display name. +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--monthly-spending-limit-usd-cents `: Monthly spending limit in USD cents; omit to leave unchanged. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Rename a cluster: + + ```bash + # Change the Starter cluster display name without recreating it. + ti db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2 + ``` + +- Preview a spending-limit update: + + ```bash + # Validate a new monthly limit without applying the change. + ti db update-db-cluster --db-cluster-id "" --monthly-spending-limit-usd-cents 1000 --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/commands/fs-git/ti-fs-git-add-git-worktree.md b/ai/ti/reference/commands/fs-git/ti-fs-git-add-git-worktree.md new file mode 100644 index 0000000000000..0a3b5ed9fe01f --- /dev/null +++ b/ai/ti/reference/commands/fs-git/ti-fs-git-add-git-worktree.md @@ -0,0 +1,67 @@ +--- +title: ti fs-git add-git-worktree +summary: Add a linked Git worktree in a mounted TiDB Cloud Filesystem. +--- + +# ti fs-git add-git-worktree + +Adds a linked Git worktree from a base workspace. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-git add-git-worktree + --base-path + --worktree-path + [--blobless] + [--branch-name ] + [--commit-ish ] + [--detach] + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--hydrate ] + [--version] +``` + +## Options + +- `--base-path `: The mounted file system path of the base Git workspace. \[required] +- `--worktree-path `: The mounted file system path for the linked worktree. \[required] +- `--blobless`: Require the base workspace to use blobless Git storage. +- `--branch-name `: Create a branch for the linked worktree. +- `--commit-ish `: Optional commit-ish for the linked worktree. +- `--detach`: Create a detached linked worktree. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--hydrate `: Blobless hydrate mode: `auto`, `background`, `sync`, or `off`. \[default: auto] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create a worktree on a new branch: + + ```bash + # Give an agent an isolated branch while sharing the base Git object store. + ti fs-git add-git-worktree --file-system-id --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-feature --branch-name feature-x + ``` + +- Create a detached worktree: + + ```bash + # Inspect a commit without creating or switching a branch. + ti fs-git add-git-worktree --file-system-id --base-path /path/to/workspace/tidb --worktree-path /path/to/workspace/tidb-review --commit-ish origin/main --detach + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.md b/ai/ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.md new file mode 100644 index 0000000000000..c3d2ab6652d48 --- /dev/null +++ b/ai/ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.md @@ -0,0 +1,68 @@ +--- +title: ti fs-git clone-git-workspace +summary: Clone a Git repository into a mounted TiDB Cloud Filesystem. +--- + +# ti fs-git clone-git-workspace + +Clones a repository into a mounted Filesystem path. Hydration can run synchronously or in the background. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-git clone-git-workspace + --repo-url + --target-path + [--blobless] + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--hydrate ] + [--version] +``` + +## Options + +- `--repo-url `: Git repository URL. \[required] +- `--target-path `: The mounted file system path to clone into. \[required] +- `--blobless`: Create a blobless partial local `.git` and hydrate clean blobs separately. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--hydrate `: Blobless hydrate mode: `auto`, `background`, `sync`, or `off`. \[default: auto] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Clone a repository normally: + + ```bash + # Create a complete Git checkout in the mounted Filesystem path. + ti fs-git clone-git-workspace --file-system-id --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb + ``` + +- Start a blobless workspace immediately: + + ```bash + # Expose the repository tree while clean Git objects hydrate in the background. + ti fs-git clone-git-workspace --file-system-id --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate background + ``` + +- Wait for blobless hydration: + + ```bash + # Keep the clone command running until clean Git objects finish hydrating. + ti fs-git clone-git-workspace --file-system-id --repo-url https://github.com/pingcap/tidb.git --target-path /path/to/workspace/tidb --blobless --hydrate sync + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/ti/reference/commands/fs-git/ti-fs-git-hydrate-git-workspace.md b/ai/ti/reference/commands/fs-git/ti-fs-git-hydrate-git-workspace.md new file mode 100644 index 0000000000000..7d83e6d7ffe56 --- /dev/null +++ b/ai/ti/reference/commands/fs-git/ti-fs-git-hydrate-git-workspace.md @@ -0,0 +1,48 @@ +--- +title: ti fs-git hydrate-git-workspace +summary: Hydrate clean Git objects in a Filesystem Git workspace. +--- + +# ti fs-git hydrate-git-workspace + +Hydrates clean Git objects for an existing `ti` Git workspace. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-git hydrate-git-workspace + --target-path + [--file-system-id ] + [--fs-token ] + [--help] + [--timeout ] + [--version] +``` + +## Options + +- `--target-path `: Mounted `ti fs` workspace path. \[required] +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--timeout `: Maximum hydrate duration. \[default: `30m0s`] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Finish hydrating a Git workspace: + + ```bash + # Download missing clean Git objects for an existing blobless workspace. + ti fs-git hydrate-git-workspace --file-system-id --target-path /path/to/workspace/tidb --timeout 30m + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/ti/reference/commands/fs-git/ti-fs-git-remove-git-worktree.md b/ai/ti/reference/commands/fs-git/ti-fs-git-remove-git-worktree.md new file mode 100644 index 0000000000000..31ecf6e964db5 --- /dev/null +++ b/ai/ti/reference/commands/fs-git/ti-fs-git-remove-git-worktree.md @@ -0,0 +1,50 @@ +--- +title: ti fs-git remove-git-worktree +summary: Remove a linked Git worktree from a mounted TiDB Cloud Filesystem. +--- + +# ti fs-git remove-git-worktree + +Removes a linked worktree without recursively deleting shared clean-tree data. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-git remove-git-worktree + --worktree-path + [--dry-run] + [--file-system-id ] + [--force] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--worktree-path `: Mounted `ti fs` path of the linked worktree. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--force`: Remove even when the linked worktree has local changes. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Remove a Git worktree: + + ```bash + # Force removal when the isolated worktree still contains local changes. + ti fs-git remove-git-worktree --file-system-id --worktree-path /path/to/workspace/tidb-feature --force + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/ti/reference/commands/fs-journal/ti-fs-journal-append-journal-entries.md b/ai/ti/reference/commands/fs-journal/ti-fs-journal-append-journal-entries.md new file mode 100644 index 0000000000000..566961e906fab --- /dev/null +++ b/ai/ti/reference/commands/fs-journal/ti-fs-journal-append-journal-entries.md @@ -0,0 +1,74 @@ +--- +title: ti fs-journal append-journal-entries +summary: Append entries to a Filesystem journal. +--- + +# ti fs-journal append-journal-entries + +Appends one JSON event or a JSON array to a journal. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-journal append-journal-entries + --journal-id + [--dry-run] + [--entry-json ] + [--entry-type ] + [--file-system-id ] + [--fs-token ] + [--help] + [--idempotency-key ] + [--json-array] + [--source ] + [--subject ] + [--version] +``` + +## Options + +- `--journal-id `: Journal ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--entry-json `: One JSON journal entry object; repeatable. +- `--entry-type `: Default entry type for entries missing type. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--idempotency-key `: Append idempotency key; generated when omitted. +- `--json-array`: Read a JSON array from stdin instead of JSONL. +- `--source `: Entry source. +- `--subject `: Entry subject; repeatable. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Append one JSON entry: + + ```bash + # Record an event object exactly as supplied on the command line. + ti fs-journal append-journal-entries --file-system-id --journal-id jrn-demo --entry-json '{"type":"task.started"}' + ``` + +- Append an idempotent typed entry: + + ```bash + # Prevent retries from recording the same completion event twice. + ti fs-journal append-journal-entries --file-system-id --journal-id jrn-demo --entry-type task.completed --subject issue-42 --idempotency-key issue-42-complete + ``` + +- Append a JSON array from standard input: + + ```bash + # Batch multiple ordered events in a single append operation. + printf '[{"type":"step.started"},{"type":"step.completed"}]' | ti fs-journal append-journal-entries --file-system-id --journal-id jrn-demo --json-array + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) diff --git a/ai/ti/reference/commands/fs-journal/ti-fs-journal-create-journal.md b/ai/ti/reference/commands/fs-journal/ti-fs-journal-create-journal.md new file mode 100644 index 0000000000000..4f9364ab24f74 --- /dev/null +++ b/ai/ti/reference/commands/fs-journal/ti-fs-journal-create-journal.md @@ -0,0 +1,63 @@ +--- +title: ti fs-journal create-journal +summary: Create an append-only Filesystem journal. +--- + +# ti fs-journal create-journal + +Creates a journal. If `--journal-id` is omitted, the service generates one. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-journal create-journal + [--actor ] + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--journal-id ] + [--journal-kind ] + [--label ] + [--title ] + [--version] +``` + +## Options + +- `--actor `: Actor in the form `type:id`. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--journal-id `: Journal ID; generated when omitted. +- `--journal-kind `: Journal kind. \[default: agent] +- `--label `: Journal label `key=value`; repeatable. +- `--title `: Journal title. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create an agent journal: + + ```bash + # Create an append-only journal for one agent task. + ti fs-journal create-journal --file-system-id --journal-id jrn-demo --journal-kind agent --title "demo task" + ``` + +- Create a labeled deployment journal: + + ```bash + # Attach actor and environment metadata for later searches. + ti fs-journal create-journal --file-system-id --journal-kind deployment --actor agent:ti --label env=dev + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) diff --git a/ai/ti/reference/commands/fs-journal/ti-fs-journal-read-journal-entries.md b/ai/ti/reference/commands/fs-journal/ti-fs-journal-read-journal-entries.md new file mode 100644 index 0000000000000..e7b6b639d366a --- /dev/null +++ b/ai/ti/reference/commands/fs-journal/ti-fs-journal-read-journal-entries.md @@ -0,0 +1,57 @@ +--- +title: ti fs-journal read-journal-entries +summary: Read entries from a Filesystem journal. +--- + +# ti fs-journal read-journal-entries + +Reads entries from one journal in sequence order. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-journal read-journal-entries + --journal-id + [--after-seq ] + [--file-system-id ] + [--fs-token ] + [--help] + [--limit ] + [--version] +``` + +## Options + +- `--journal-id `: Journal ID. \[required] +- `--after-seq `: Read entries after this sequence. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--limit `: Maximum entries to read. \[default: 100] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Read journal entries: + + ```bash + # Return the first page of ordered entries for a journal. + ti fs-journal read-journal-entries --file-system-id --journal-id jrn-demo + ``` + +- Continue after a sequence number: + + ```bash + # Read the next page after the last sequence processed by a consumer. + ti fs-journal read-journal-entries --file-system-id --journal-id jrn-demo --after-seq 100 --limit 50 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) diff --git a/ai/ti/reference/commands/fs-journal/ti-fs-journal-search-journal-entries.md b/ai/ti/reference/commands/fs-journal/ti-fs-journal-search-journal-entries.md new file mode 100644 index 0000000000000..cb05dcda81bc3 --- /dev/null +++ b/ai/ti/reference/commands/fs-journal/ti-fs-journal-search-journal-entries.md @@ -0,0 +1,80 @@ +--- +title: ti fs-journal search-journal-entries +summary: Search Filesystem journals and entries. +--- + +# ti fs-journal search-journal-entries + +Searches journals and optionally returns matching entries. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-journal search-journal-entries + [--actor ] + [--cursor ] + [--entry-type ] + [--file-system-id ] + [--fs-token ] + [--help] + [--include-entries] + [--journal-kind ] + [--label ] + [--limit ] + [--since ] + [--status ] + [--subject ] + [--until ] + [--version] +``` + +## Options + +- `--actor `: Actor in the form `type:id`. +- `--cursor `: Pagination cursor. +- `--entry-type `: Entry type filter. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--include-entries`: Include full entry payloads in matches. +- `--journal-kind `: Journal kind filter. +- `--label `: Label filter `key=value`; repeatable. +- `--limit `: Maximum matches to read. \[default: 100] +- `--since `: Relative duration or RFC3339 lower time bound. +- `--status `: Entry status filter. +- `--subject `: Subject filter; repeatable. +- `--until `: RFC3339 upper time bound. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Search by entry type: + + ```bash + # Find journals containing task-start events and include their payloads. + ti fs-journal search-journal-entries --file-system-id --entry-type task.started --include-entries + ``` + +- Search by label and time: + + ```bash + # Limit deployment journal matches to one environment and time window. + ti fs-journal search-journal-entries --file-system-id --label env=dev --since 2026-07-01T00:00:00Z --limit 100 + ``` + +- Search by actor and subject: + + ```bash + # Find events produced by one agent for a specific task subject. + ti fs-journal search-journal-entries --file-system-id --actor agent:ti --subject issue-42 --include-entries + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) diff --git a/ai/ti/reference/commands/fs-journal/ti-fs-journal-verify-journal.md b/ai/ti/reference/commands/fs-journal/ti-fs-journal-verify-journal.md new file mode 100644 index 0000000000000..45e8690c7e5a0 --- /dev/null +++ b/ai/ti/reference/commands/fs-journal/ti-fs-journal-verify-journal.md @@ -0,0 +1,46 @@ +--- +title: ti fs-journal verify-journal +summary: Verify a Filesystem journal hash chain. +--- + +# ti fs-journal verify-journal + +Verifies the integrity of one journal hash chain. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-journal verify-journal + --journal-id + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--journal-id `: Journal ID. \[required] +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Verify a journal: + + ```bash + # Validate the journal's ordered hash chain and integrity metadata. + ti fs-journal verify-journal --file-system-id --journal-id jrn-demo + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) diff --git a/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-grant.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-grant.md new file mode 100644 index 0000000000000..0db272a516f82 --- /dev/null +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-grant.md @@ -0,0 +1,65 @@ +--- +title: ti fs-vault create-grant +summary: Create a delegated Filesystem Vault grant. +--- + +# ti fs-vault create-grant + +Creates a time-limited delegated grant for one agent and scope. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-vault create-grant + --agent-id + --permission + --scope + --ttl + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--label-hint ] + [--token-only] + [--version] +``` + +## Options + +- `--agent-id `: Agent ID for the delegated grant. \[required] +- `--permission `: Grant permission: `read` or `write`. \[required] +- `--scope `: Vault scope such as secret or secret/field; repeatable. \[required] +- `--ttl `: Grant time to live, for example, `1h`. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--label-hint `: Optional grant label hint. +- `--token-only`: Print only the delegated bearer token. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create a temporary read grant: + + ```bash + # Limit an agent to one secret field for ten minutes. + ti fs-vault create-grant --file-system-id --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m + ``` + +- Return only the delegated token: + + ```bash + # Produce token-only output for injection into an isolated CI job. + ti fs-vault create-grant --file-system-id --agent-id ci-agent --scope api-dev/TOKEN --permission read --ttl 5m --token-only + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-secret.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-secret.md new file mode 100644 index 0000000000000..09ff2261b2606 --- /dev/null +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-create-secret.md @@ -0,0 +1,64 @@ +--- +title: ti fs-vault create-secret +summary: Create a secret in Filesystem Vault. +--- + +# ti fs-vault create-secret + +Creates a secret from one or more `NAME=value` or `NAME=@file` fields. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-vault create-secret + --field + --secret-name + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--field `: Secret field assignment `key=value`, `key=@file`, or `key=-`; repeatable. \[required] +- `--secret-name `: Vault secret name. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create a secret from values and a file: + + ```bash + # Keep the password out of the command line by reading it from a local file. + ti fs-vault create-secret --file-system-id --secret-name db-prod --field DB_URL=mysql://example --field PASSWORD=@./password.txt + ``` + +- Read a secret field from standard input: + + ```bash + # Supply a sensitive token through a pipe instead of a process argument. + printf '%s' "$API_TOKEN" | ti fs-vault create-secret --file-system-id --secret-name api-dev --field TOKEN=- + ``` + +- Preview secret creation: + + ```bash + # Validate field assignments without storing secret material. + ti fs-vault create-secret --file-system-id --secret-name api-dev --field TOKEN=@./token.txt --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-grant.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-grant.md new file mode 100644 index 0000000000000..7818f74c91040 --- /dev/null +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-grant.md @@ -0,0 +1,52 @@ +--- +title: ti fs-vault delete-grant +summary: Revoke a delegated Filesystem Vault grant. +--- + +# ti fs-vault delete-grant + +Revokes one delegated Filesystem Vault grant. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-vault delete-grant + --grant-id + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--reason ] + [--revoked-by ] + [--version] +``` + +## Options + +- `--grant-id `: Vault grant ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--reason `: Optional revoke reason. +- `--revoked-by `: Actor label for the revoke audit entry. \[default: `ti`] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Revoke a grant: + + ```bash + # Invalidate the delegated token and record the revocation reason. + ti fs-vault delete-grant --file-system-id --grant-id "" --reason rotated + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-secret.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-secret.md new file mode 100644 index 0000000000000..296f18fc6fc47 --- /dev/null +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-delete-secret.md @@ -0,0 +1,48 @@ +--- +title: ti fs-vault delete-secret +summary: Delete a secret from Filesystem Vault. +--- + +# ti fs-vault delete-secret + +Deletes one Filesystem Vault secret. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-vault delete-secret + --secret-name + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--secret-name `: Vault secret name. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Delete a secret: + + ```bash + # Remove the selected secret and its fields from the Vault. + ti fs-vault delete-secret --file-system-id --secret-name db-prod + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-audit-events.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-audit-events.md new file mode 100644 index 0000000000000..7c430e6069c1d --- /dev/null +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-audit-events.md @@ -0,0 +1,59 @@ +--- +title: ti fs-vault list-audit-events +summary: List Filesystem Vault audit events. +--- + +# ti fs-vault list-audit-events + +Lists vault audit events with optional agent, secret, and time filters. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-vault list-audit-events + [--agent-id ] + [--file-system-id ] + [--fs-token ] + [--help] + [--limit ] + [--secret-name ] + [--since ] + [--version] +``` + +## Options + +- `--agent-id `: Filter by agent ID. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--limit `: Maximum events to return. \[default: 100] +- `--secret-name `: Filter by Vault secret name. +- `--since `: Client-side relative time filter, for example, `24h`. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- List events for one secret: + + ```bash + # Inspect recent access and mutation events for the selected secret. + ti fs-vault list-audit-events --file-system-id --secret-name db-prod --limit 20 + ``` + +- List recent events for an agent: + + ```bash + # Filter the audit trail to one delegated identity and time range. + ti fs-vault list-audit-events --file-system-id --agent-id deploy-agent --since 24h + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-secrets.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-secrets.md new file mode 100644 index 0000000000000..84f5236423c89 --- /dev/null +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-list-secrets.md @@ -0,0 +1,53 @@ +--- +title: ti fs-vault list-secrets +summary: List secrets visible to a Filesystem Vault credential. +--- + +# ti fs-vault list-secrets + +Lists secrets visible to the active owner or delegated credential. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-vault list-secrets + [--file-system-id ] + [--fs-token ] + [--help] + [--vault-token ] + [--version] +``` + +## Options + +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--vault-token `: Delegated `ti fs-vault` token; prefer `TI_VAULT_TOKEN`. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- List owner-visible secrets: + + ```bash + # Return secret metadata without exposing field values. + ti fs-vault list-secrets --file-system-id + ``` + +- List secrets visible to a delegated token: + + ```bash + # Restrict the result to secrets within the token's granted scope. + ti fs-vault list-secrets --file-system-id --vault-token "$TI_VAULT_TOKEN" + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/commands/fs-vault/ti-fs-vault-mount-vault.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-mount-vault.md new file mode 100644 index 0000000000000..fa49a8527d91f --- /dev/null +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-mount-vault.md @@ -0,0 +1,61 @@ +--- +title: ti fs-vault mount-vault +summary: Mount a read-only Filesystem Vault view. +--- + +# ti fs-vault mount-vault + +Mounts readable vault fields as a local read-only FUSE filesystem. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-vault mount-vault + --mount-path + [--dry-run] + [--file-system-id ] + [--foreground] + [--fs-token ] + [--help] + [--ready-timeout ] + [--vault-token ] + [--version] +``` + +## Options + +- `--mount-path `: Local mount path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--foreground`: Run mount runtime in the foreground until interrupted. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--ready-timeout `: Time to wait for a background mount to become ready. \[default: `30s`] +- `--vault-token `: Delegated `ti fs-vault` token; prefer `TI_VAULT_TOKEN`. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Mount a delegated Vault view: + + ```bash + # Expose only the paths allowed by the delegated Vault token. + ti fs-vault mount-vault --file-system-id --mount-path ./vault --vault-token "$TI_VAULT_TOKEN" + ``` + +- Run the Vault mount in the foreground: + + ```bash + # Keep the runtime attached for containers or process supervisors. + ti fs-vault mount-vault --file-system-id --mount-path ./vault --foreground --ready-timeout 60s + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/commands/fs-vault/ti-fs-vault-read-secret.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-read-secret.md new file mode 100644 index 0000000000000..e1f0a50b20508 --- /dev/null +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-read-secret.md @@ -0,0 +1,66 @@ +--- +title: ti fs-vault read-secret +summary: Read a secret from Filesystem Vault. +--- + +# ti fs-vault read-secret + +Reads a complete secret or one field using an owner or delegated credential. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-vault read-secret + --secret-name + [--field ] + [--file-system-id ] + [--format ] + [--fs-token ] + [--help] + [--vault-token ] + [--version] +``` + +## Options + +- `--secret-name `: Vault secret name. \[required] +- `--field `: Optional field name to read. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--format `: Read output format: `json`, `raw`, or `env`. \[default: json] +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--vault-token `: Delegated `ti fs-vault` token; prefer `TI_VAULT_TOKEN`. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Read one secret field as raw text: + + ```bash + # Write only the selected field value for direct consumption by a process. + ti fs-vault read-secret --file-system-id --secret-name db-prod --field PASSWORD --format raw + ``` + +- Format a field as an environment assignment: + + ```bash + # Emit an exportable environment-variable representation of the field. + ti fs-vault read-secret --file-system-id --secret-name db-prod --field DB_URL --format env + ``` + +- Read with a delegated Vault token: + + ```bash + # Access only the scope granted to an agent without using the owner token. + ti fs-vault read-secret --file-system-id --secret-name db-prod --field DB_URL --vault-token "$TI_VAULT_TOKEN" --format raw + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/commands/fs-vault/ti-fs-vault-replace-secret.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-replace-secret.md new file mode 100644 index 0000000000000..e7f0d48df4055 --- /dev/null +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-replace-secret.md @@ -0,0 +1,57 @@ +--- +title: ti fs-vault replace-secret +summary: Replace all fields in a Filesystem Vault secret. +--- + +# ti fs-vault replace-secret + +Replaces all fields in one secret from files in a local directory. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-vault replace-secret + --from-directory + --secret-path + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--from-directory `: Directory whose files become secret fields. \[required] +- `--secret-path `: Vault path in the form `/n/vault/`. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Replace a secret from a directory: + + ```bash + # Replace all fields with files loaded from the selected directory. + ti fs-vault replace-secret --file-system-id --secret-path /n/vault/db-prod --from-directory ./secret-fields + ``` + +- Preview secret replacement: + + ```bash + # Validate the replacement source without changing the stored secret. + ti fs-vault replace-secret --file-system-id --secret-path /n/vault/db-prod --from-directory ./secret-fields --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/commands/fs-vault/ti-fs-vault-run-with-secret.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-run-with-secret.md new file mode 100644 index 0000000000000..ec0ce9be54b36 --- /dev/null +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-run-with-secret.md @@ -0,0 +1,55 @@ +--- +title: ti fs-vault run-with-secret +summary: Run a process with a Filesystem Vault secret. +--- + +# ti fs-vault run-with-secret + +Runs a command with one secret injected into its environment. Arguments after `--` are passed to the child command. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-vault run-with-secret + --secret-path + [--file-system-id ] + [--fs-token ] + [--help] + [--vault-token ] + [--version] +``` + +## Options + +- `--secret-path `: Vault path in the form `/n/vault/`. \[required] +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--vault-token `: Delegated `ti fs-vault` token; prefer `TI_VAULT_TOKEN`. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Run a process with secret fields: + + ```bash + # Inject all fields into the child process environment without printing them. + ti fs-vault run-with-secret --file-system-id --secret-path /n/vault/db-prod -- env + ``` + +- Use an injected field in a shell command: + + ```bash + # Verify that the child process receives DB_URL without exposing its value. + ti fs-vault run-with-secret --file-system-id --secret-path /n/vault/db-prod -- sh -c 'test -n "$DB_URL"' + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/commands/fs-vault/ti-fs-vault-unmount-vault.md b/ai/ti/reference/commands/fs-vault/ti-fs-vault-unmount-vault.md new file mode 100644 index 0000000000000..2a90142899df0 --- /dev/null +++ b/ai/ti/reference/commands/fs-vault/ti-fs-vault-unmount-vault.md @@ -0,0 +1,50 @@ +--- +title: ti fs-vault unmount-vault +summary: Unmount a Filesystem Vault view. +--- + +# ti fs-vault unmount-vault + +Unmounts a local Filesystem Vault filesystem. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs-vault unmount-vault + --mount-path + [--dry-run] + [--force] + [--help] + [--ignore-absent] + [--timeout ] + [--version] +``` + +## Options + +- `--mount-path `: Local mount path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--force`: Force-kill the mount process if graceful unmount times out. +- `--help`: Display help information. +- `--ignore-absent`: Return success when no `ti fs-vault` mount state exists for the path. +- `--timeout `: Time to wait for the mount process to exit. \[default: `30s`] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Unmount a Vault view: + + ```bash + # Detach the local read-only Vault mount. + ti fs-vault unmount-vault --mount-path ./vault + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-check-file-system.md b/ai/ti/reference/commands/fs/ti-fs-check-file-system.md new file mode 100644 index 0000000000000..3acb24e817f1f --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-check-file-system.md @@ -0,0 +1,44 @@ +--- +title: ti fs check-file-system +summary: Check TiDB Cloud Filesystem connectivity. +--- + +# ti fs check-file-system + +Checks Filesystem selection, endpoint resolution, credentials, and companion access. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs check-file-system + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Check Filesystem connectivity: + + ```bash + # Verify that the selected token can reach and read the Filesystem root. + ti fs check-file-system --file-system-id + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-chmod-file.md b/ai/ti/reference/commands/fs/ti-fs-chmod-file.md new file mode 100644 index 0000000000000..264eb2555caf1 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-chmod-file.md @@ -0,0 +1,50 @@ +--- +title: ti fs chmod-file +summary: Change file permissions in a TiDB Cloud Filesystem. +--- + +# ti fs chmod-file + +Changes POSIX mode metadata for a remote path. The command alias is `ti fs chmod`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs chmod-file + --mode + --path + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--mode `: The permission mode as an octal value such as 0644. \[required] +- `--path `: File or directory path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Change remote permission metadata: + + ```bash + # Restrict the selected file to owner read and write access. + ti fs chmod-file --file-system-id --path /reports/final.md --mode 0600 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-commit-layer.md b/ai/ti/reference/commands/fs/ti-fs-commit-layer.md new file mode 100644 index 0000000000000..32423b1e4e45a --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-commit-layer.md @@ -0,0 +1,48 @@ +--- +title: ti fs commit-layer +summary: Commit a TiDB Cloud Filesystem layer. +--- + +# ti fs commit-layer + +Applies one layer to its base Filesystem. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs commit-layer + --layer-id + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--layer-id `: Layer ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Commit a layer: + + ```bash + # Apply the selected layer's changes to its base Filesystem view. + ti fs commit-layer --file-system-id --layer-id "" + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-copy-file.md b/ai/ti/reference/commands/fs/ti-fs-copy-file.md new file mode 100644 index 0000000000000..6c281484ed80d --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-copy-file.md @@ -0,0 +1,109 @@ +--- +title: ti fs copy-file +summary: Copy files to, from, or within a TiDB Cloud Filesystem. +--- + +# ti fs copy-file + +Copies files between local paths, remote paths, stdin, and stdout. The command alias is `ti fs cp`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs copy-file + [--append] + [--create-parents] + [--description ] + [--dry-run] + [--file-system-id ] + [--from-local ] + [--from-remote ] + [--from-stdin] + [--fs-token ] + [--help] + [--layer-id ] + [--overwrite] + [--recursive] + [--resume] + [--tag ] + [--to-local ] + [--to-remote ] + [--to-stdout] + [--version] +``` + +## Options + +- `--append`: Append the contents of a local file to a file in the TiDB Cloud file system. +- `--create-parents`: Create missing local parent directories when copying from a TiDB Cloud file system. +- `--description `: The file description for `--to-remote` operation. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--from-local `: The local source path. +- `--from-remote `: The source path in the TiDB Cloud file system. +- `--from-stdin`: Read from stdin and write to `--to-remote`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--layer-id `: Write the copied file content into a file system layer instead of the base file system. +- `--overwrite`: Replace an existing destination file. +- `--recursive`: Copy directory structure recursively. +- `--resume`: Resume an active copy operation. +- `--tag `: Create tags `key=value` for `--to-remote` operation; repeatable. +- `--to-local `: The local destination path. +- `--to-remote `: The destination path in the TiDB Cloud file system. +- `--to-stdout`: Write `--from-remote` to stdout. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Upload a local file: + + ```bash + # Copy a local report into the selected remote Filesystem. + ti fs copy-file --file-system-id --from-local ./report.md --to-remote /reports/report.md + ``` + +- Download a remote file: + + ```bash + # Create missing local parent directories while downloading the file. + ti fs copy-file --file-system-id --from-remote /reports/report.md --to-local ./downloads/report.md --create-parents + ``` + +- Copy a remote directory: + + ```bash + # Duplicate a complete directory tree without downloading it locally. + ti fs copy-file --file-system-id --from-remote /reports --to-remote /archive/reports --recursive + ``` + +- Resume a large upload: + + ```bash + # Continue an interrupted local-to-remote transfer instead of restarting it. + ti fs copy-file --file-system-id --from-local ./large.bin --to-remote /artifacts/large.bin --resume + ``` + +- Append to a remote log: + + ```bash + # Add local log data to the existing remote object efficiently. + ti fs copy-file --file-system-id --from-local ./tail.log --to-remote /logs/app.log --append + ``` + +- Stream standard input to the Filesystem: + + ```bash + # Upload generated content without creating an intermediate local file. + printf 'ready\n' | ti fs copy-file --file-system-id --from-stdin --to-remote /status.txt --tag source=stdin --description "generated status" + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-create-directory.md b/ai/ti/reference/commands/fs/ti-fs-create-directory.md new file mode 100644 index 0000000000000..fbcf9ad004231 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-create-directory.md @@ -0,0 +1,50 @@ +--- +title: ti fs create-directory +summary: Create a directory in a TiDB Cloud Filesystem. +--- + +# ti fs create-directory + +Creates a remote directory. The command alias is `ti fs mkdir`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs create-directory + --path + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--mode ] + [--version] +``` + +## Options + +- `--path `: The file system path of the directory to create. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--mode `: The directory mode as an octal value such as 0755. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create a remote directory: + + ```bash + # Create the directory with explicit POSIX permission metadata. + ti fs create-directory --file-system-id --path /reports/archive --mode 0755 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-create-file-system.md b/ai/ti/reference/commands/fs/ti-fs-create-file-system.md new file mode 100644 index 0000000000000..a54ab37c9c908 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-create-file-system.md @@ -0,0 +1,58 @@ +--- +title: ti fs create-file-system +summary: Create a TiDB Cloud Filesystem. +--- + +# ti fs create-file-system + +Creates a Filesystem with a server-assigned ID. The response contains the owner `fs_token` once. `--wait` waits until data-plane access is ready. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs create-file-system + [--dry-run] + [--help] + [--version] + [--wait] +``` + +## Options + +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--version`: Display version information. +- `--wait`: Wait until the created file system is active. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create a Filesystem and wait until it is ready: + + ```bash + # Wait until the new Filesystem root is readable before returning. + ti fs create-file-system --wait + ``` + +- Create a Filesystem asynchronously: + + ```bash + # Return after provisioning is accepted so work can continue in parallel. + ti fs create-file-system + ``` + +- Preview Filesystem creation: + + ```bash + # Validate credentials, placement, and the request without provisioning storage. + ti fs create-file-system --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-create-hardlink.md b/ai/ti/reference/commands/fs/ti-fs-create-hardlink.md new file mode 100644 index 0000000000000..053c069f843d1 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-create-hardlink.md @@ -0,0 +1,50 @@ +--- +title: ti fs create-hardlink +summary: Create a hard link in a TiDB Cloud Filesystem. +--- + +# ti fs create-hardlink + +Creates a hard link to an existing remote path. The command alias is `ti fs hardlink`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs create-hardlink + --link-path + --source-path + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--link-path `: The file path for the hard link being created in the TiDB Cloud file system. \[required] +- `--source-path `: The existing file path in the TiDB Cloud file system. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create a hard link: + + ```bash + # Expose the same remote file content at a second path. + ti fs create-hardlink --file-system-id --source-path /reports/final.md --link-path /reports/final-copy.md + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-create-layer-checkpoint.md b/ai/ti/reference/commands/fs/ti-fs-create-layer-checkpoint.md new file mode 100644 index 0000000000000..8ad807a8afe1e --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-create-layer-checkpoint.md @@ -0,0 +1,59 @@ +--- +title: ti fs create-layer-checkpoint +summary: Create a checkpoint in a TiDB Cloud Filesystem layer. +--- + +# ti fs create-layer-checkpoint + +Creates a checkpoint in one layer. If `--checkpoint-id` is omitted, the service generates one. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs create-layer-checkpoint + --layer-id + [--checkpoint-id ] + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--label ] + [--version] +``` + +## Options + +- `--layer-id `: The layer ID identifying the layer. \[required] +- `--checkpoint-id `: Checkpoint ID. Normally it is generated by the service automatically. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--label `: The checkpoint label. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create a named checkpoint: + + ```bash + # Record the current layer state under a stable checkpoint ID. + ti fs create-layer-checkpoint --file-system-id --layer-id "" --checkpoint-id before-review + ``` + +- Create an automatically identified checkpoint: + + ```bash + # Let the service assign the checkpoint ID while retaining a human label. + ti fs create-layer-checkpoint --file-system-id --layer-id "" --label "before review" + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-create-layer.md b/ai/ti/reference/commands/fs/ti-fs-create-layer.md new file mode 100644 index 0000000000000..383a742f5a518 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-create-layer.md @@ -0,0 +1,65 @@ +--- +title: ti fs create-layer +summary: Create a layer in a TiDB Cloud Filesystem. +--- + +# ti fs create-layer + +Creates an isolated change layer over a base root. If `--layer-id` is omitted, the service generates one. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs create-layer + --base-root-path + [--actor-id ] + [--dry-run] + [--durability-mode ] + [--file-system-id ] + [--fs-token ] + [--help] + [--layer-id ] + [--layer-name ] + [--tag ] + [--version] +``` + +## Options + +- `--base-root-path `: Base root path in the TiDB Cloud file system. \[required] +- `--actor-id `: Actor ID identifying the layer owner (for example, the agent name). +- `--dry-run`: Validate the request without applying changes. +- `--durability-mode `: Layer durability mode; must be `restore-safe`. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--layer-id `: The layer ID. Normally it is generated by the service automatically. +- `--layer-name `: The name of the layer. +- `--tag `: Tags for the layer, `key=value`; repeatable. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create a layer: + + ```bash + # Start an isolated writable view over the selected base root. + ti fs create-layer --file-system-id --base-root-path /workspace --layer-name agent-task + ``` + +- Create a restore-safe tagged layer: + + ```bash + # Request durable layer behavior and attach task metadata. + ti fs create-layer --file-system-id --base-root-path /workspace --durability-mode restore-safe --tag task=review + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-create-symlink.md b/ai/ti/reference/commands/fs/ti-fs-create-symlink.md new file mode 100644 index 0000000000000..dd713735194b5 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-create-symlink.md @@ -0,0 +1,50 @@ +--- +title: ti fs create-symlink +summary: Create a symbolic link in a TiDB Cloud Filesystem. +--- + +# ti fs create-symlink + +Creates a symbolic link. The command alias is `ti fs symlink`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs create-symlink + --link-path + --target + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--link-path `: The file path for the created symbolic link. \[required] +- `--target `: The actual file path being linked to. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Create a symbolic link: + + ```bash + # Create a relative symbolic link inside the remote namespace. + ti fs create-symlink --file-system-id --target final.md --link-path /reports/latest.md + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md new file mode 100644 index 0000000000000..9ff3d0a9a17a8 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md @@ -0,0 +1,47 @@ +--- +title: ti fs delete-file-system-token +summary: Permanently revoke a TiDB Cloud Filesystem token. +--- + +# ti fs delete-file-system-token + +Permanently revokes a token by immutable token ID. Revocation is terminal and the service does not return revoked tokens in later list results. An owner token can revoke either token kind in the same Filesystem; a scoped token cannot use this command. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs delete-file-system-token + --file-system-id + --token-id + [--fs-token ] + [--dry-run] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. This option is required. +- `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--fs-token `: Authorize the request with an owner FS token. Defaults to `TI_FS_TOKEN`; when neither is present, the command uses configured TiDB Cloud API keys. +- `--dry-run`: Validate credentials, identifiers, and known local mount conflicts without revoking the token. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Revoke an old token after validating its replacement: + + ```bash + # Revocation is permanent; use disable first when you need a reversible rollout. + ti fs delete-file-system-token \ + --file-system-id "" \ + --token-id "" + ``` + +## Related documentation + +- [`ti fs generate-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) +- [`ti fs disable-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-delete-file-system.md b/ai/ti/reference/commands/fs/ti-fs-delete-file-system.md new file mode 100644 index 0000000000000..777dd19dde109 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-delete-file-system.md @@ -0,0 +1,51 @@ +--- +title: ti fs delete-file-system +summary: Delete a TiDB Cloud Filesystem. +--- + +# ti fs delete-file-system + +Requests asynchronous Filesystem deletion by ID. A locally stored FS token is not required. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs delete-file-system + --file-system-id + [--dry-run] + [--help] + [--version] +``` + +## Options + +- `--file-system-id `: Set the file system ID. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Delete a Filesystem: + + ```bash + # Request asynchronous deletion and remove only the matching local credential after acceptance. + ti fs delete-file-system --file-system-id + ``` + +- Preview Filesystem deletion: + + ```bash + # Validate the selected Filesystem without sending the deletion request. + ti fs delete-file-system --file-system-id --dry-run + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-delete-file.md b/ai/ti/reference/commands/fs/ti-fs-delete-file.md new file mode 100644 index 0000000000000..43e5bb53e4da9 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-delete-file.md @@ -0,0 +1,57 @@ +--- +title: ti fs delete-file +summary: Delete a file from a TiDB Cloud Filesystem. +--- + +# ti fs delete-file + +Deletes a remote file or directory. The command alias is `ti fs rm`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs delete-file + --path + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--recursive] + [--version] +``` + +## Options + +- `--path `: File or directory path in the TiDB Cloud file system. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--recursive`: Delete a directory recursively. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Delete a remote file: + + ```bash + # Remove one object from the selected Filesystem. + ti fs delete-file --file-system-id --path /reports/obsolete.md + ``` + +- Delete a directory recursively: + + ```bash + # Remove a directory and all of its descendants in one request. + ti fs delete-file --file-system-id --path /scratch --recursive + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-describe-file-system.md b/ai/ti/reference/commands/fs/ti-fs-describe-file-system.md new file mode 100644 index 0000000000000..a45787f846d8d --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-describe-file-system.md @@ -0,0 +1,42 @@ +--- +title: ti fs describe-file-system +summary: Describe a remote TiDB Cloud Filesystem. +--- + +# ti fs describe-file-system + +Describes one remote Filesystem by its server-assigned ID. The command does not require a locally stored FS token. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs describe-file-system + --file-system-id + [--help] + [--version] +``` + +## Options + +- `--file-system-id `: Set the file system ID. \[required] +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Describe a Filesystem: + + ```bash + # Return remote status and whether this machine has a matching local token. + ti fs describe-file-system --file-system-id + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-describe-file.md b/ai/ti/reference/commands/fs/ti-fs-describe-file.md new file mode 100644 index 0000000000000..cb429e030b71a --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-describe-file.md @@ -0,0 +1,46 @@ +--- +title: ti fs describe-file +summary: Describe a file in a TiDB Cloud Filesystem. +--- + +# ti fs describe-file + +Describes metadata for one remote path. The command alias is `ti fs stat`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs describe-file + --path + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--path `: File or directory path in the TiDB Cloud file system. \[required] +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Describe a remote file: + + ```bash + # Inspect file size, metadata, tags, and revision information. + ti fs describe-file --file-system-id --path /reports/report.md + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-describe-layer.md b/ai/ti/reference/commands/fs/ti-fs-describe-layer.md new file mode 100644 index 0000000000000..c3588ffc75fab --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-describe-layer.md @@ -0,0 +1,46 @@ +--- +title: ti fs describe-layer +summary: Describe a layer in a TiDB Cloud Filesystem. +--- + +# ti fs describe-layer + +Describes one Filesystem layer. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs describe-layer + --layer-id + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--layer-id `: The ID of the specified file system layer. \[required] +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Describe a layer: + + ```bash + # Inspect one layer's base root, state, durability, and metadata. + ti fs describe-layer --file-system-id --layer-id "" + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-diff-layer.md b/ai/ti/reference/commands/fs/ti-fs-diff-layer.md new file mode 100644 index 0000000000000..d96c4103fb27b --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-diff-layer.md @@ -0,0 +1,55 @@ +--- +title: ti fs diff-layer +summary: Show changes in a TiDB Cloud Filesystem layer. +--- + +# ti fs diff-layer + +Lists changes in one layer, optionally up to a sequence number. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs diff-layer + --layer-id + [--file-system-id ] + [--fs-token ] + [--help] + [--max-seq ] + [--version] +``` + +## Options + +- `--layer-id `: The ID of the layer. \[required] +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--max-seq `: The highest layer sequence to include; 0 includes all layers. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Show all layer changes: + + ```bash + # Return the complete ordered change set for the selected layer. + ti fs diff-layer --file-system-id --layer-id "" + ``` + +- Show an earlier layer view: + + ```bash + # Limit the diff to changes at or before a sequence number. + ti fs diff-layer --file-system-id --layer-id "" --max-seq 100 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md new file mode 100644 index 0000000000000..3d119a7b51b17 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md @@ -0,0 +1,49 @@ +--- +title: ti fs disable-file-system-token +summary: Temporarily disable a TiDB Cloud Filesystem token. +--- + +# ti fs disable-file-system-token + +Disables an active token by immutable token ID without revoking it. A token used by a known local mount must be drained and unmounted first. When `--fs-token` or `TI_FS_TOKEN` supplies owner Bearer authentication, the target must be an `fs_scoped` token. Configured TiDB Cloud API keys can disable either token kind. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs disable-file-system-token + --file-system-id + --token-id + [--fs-token ] + [--dry-run] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. This option is required. +- `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--fs-token `: Authorize the request with an owner FS token. Defaults to `TI_FS_TOKEN`; when neither is present, the command uses configured TiDB Cloud API keys. +- `--dry-run`: Validate credentials, identifiers, and known local mount conflicts without disabling the token. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Disable a token after stopping its local mount: + + ```bash + # Drain and unmount first when this token backs a mount on the current machine. + ti fs drain-file-system --mount-path /path/to/workspace + ti fs unmount-file-system --mount-path /path/to/workspace + ti fs disable-file-system-token \ + --file-system-id "" \ + --token-id "" + ``` + +## Related documentation + +- [`ti fs enable-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md) +- [`ti fs delete-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-delete-file-system-token.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-drain-file-system.md b/ai/ti/reference/commands/fs/ti-fs-drain-file-system.md new file mode 100644 index 0000000000000..9e9de63e201ab --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-drain-file-system.md @@ -0,0 +1,46 @@ +--- +title: ti fs drain-file-system +summary: Drain a mounted TiDB Cloud Filesystem. +--- + +# ti fs drain-file-system + +Flushes dirty FUSE state while leaving the mount online. The command alias is `ti fs drain`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs drain-file-system + --mount-path + [--dry-run] + [--help] + [--timeout ] + [--version] +``` + +## Options + +- `--mount-path `: Local FUSE mount path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--timeout `: The time to wait for dirty handles and pending writes to drain. \[default: `30s`] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Drain pending writes: + + ```bash + # Flush queued FUSE writes while leaving the Filesystem mounted. + ti fs drain-file-system --mount-path /path/to/workspace --timeout 30s + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md new file mode 100644 index 0000000000000..7cf4e63b9277d --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-enable-file-system-token.md @@ -0,0 +1,47 @@ +--- +title: ti fs enable-file-system-token +summary: Enable a disabled TiDB Cloud Filesystem token. +--- + +# ti fs enable-file-system-token + +Changes a disabled token to active by immutable token ID. Authentication caches can take approximately 10 seconds to converge. When `--fs-token` or `TI_FS_TOKEN` supplies owner Bearer authentication, the target must be an `fs_scoped` token. Configured TiDB Cloud API keys can enable either token kind. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs enable-file-system-token + --file-system-id + --token-id + [--fs-token ] + [--dry-run] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. This option is required. +- `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--fs-token `: Authorize the request with an owner FS token. Defaults to `TI_FS_TOKEN`; when neither is present, the command uses configured TiDB Cloud API keys. +- `--dry-run`: Validate the request without changing remote token state. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Enable a known token: + + ```bash + # Allow about 10 seconds for all authentication caches to observe the change. + ti fs enable-file-system-token \ + --file-system-id "" \ + --token-id "" + ``` + +## Related documentation + +- [`ti fs list-file-system-tokens`](/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md) +- [`ti fs disable-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-disable-file-system-token.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-find-files.md b/ai/ti/reference/commands/fs/ti-fs-find-files.md new file mode 100644 index 0000000000000..e322bd6edc49e --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-find-files.md @@ -0,0 +1,71 @@ +--- +title: ti fs find-files +summary: Find files in a TiDB Cloud Filesystem. +--- + +# ti fs find-files + +Finds remote paths by name, type, tag, size, or modification time. The command alias is `ti fs find`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs find-files + [--file-name-pattern ] + [--file-system-id ] + [--fs-token ] + [--help] + [--layer-id ] + [--limit ] + [--max-size-bytes ] + [--min-size-bytes ] + [--newer ] + [--older ] + [--path ] + [--resource-type ] + [--tag ] + [--version] +``` + +## Options + +- `--file-name-pattern `: File name pattern filter, such as `*.md`. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--layer-id `: Search files and directories within a specific file system layer. +- `--limit `: Maximum number of results; 0 uses the service default. +- `--max-size-bytes `: Maximum file size in bytes. +- `--min-size-bytes `: Minimum file size in bytes. +- `--newer `: Only return files newer than the filter. +- `--older `: Only return files older than the filter. +- `--path `: File path prefix. \[default: /] +- `--resource-type `: Resource type filter: `file` or `directory`. +- `--tag `: Tag filter. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Find files by name: + + ```bash + # Locate Markdown files recursively under the selected remote path. + ti fs find-files --file-system-id --path /workspace --file-name-pattern "*.md" + ``` + +- Find files by metadata: + + ```bash + # Select tagged files that also meet a minimum size threshold. + ti fs find-files --file-system-id --path /workspace --tag stage=review --min-size-bytes 1024 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.md b/ai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.md new file mode 100644 index 0000000000000..2958ea7a97ddd --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.md @@ -0,0 +1,83 @@ +--- +title: ti fs generate-file-system-scoped-token +summary: Generate a path-and-operation-limited token for one TiDB Cloud Filesystem. +--- + +# ti fs generate-file-system-scoped-token + +Uses an owner Filesystem token to generate a finite `fs_scoped` token. The plaintext `fs_token` appears only in the successful response. A scoped token can access only its allowed path prefixes and operations. + +Scoped tokens support ordinary file, upload, Layer, and mount operations only when the requested paths and operations are covered. `chmod`, Git workspace APIs, Journal, Vault, SQL, fork, event, and token-management operations are not available to scoped tokens. Scoped tokens can refresh themselves without changing their scopes. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs generate-file-system-scoped-token + --ttl + --allow + [--file-system-id ] + [--fs-token ] + [--subject ] + [--store-locally] + [--replace] + [--dry-run] +``` + +## Options + +- `--ttl `: Set a finite positive token lifetime that resolves to whole seconds. This option is required. +- `--allow `: Allow operations under one remote path prefix. Repeat this option for multiple prefixes. Operations are `read`, `list`, `search`, `write`, and `delete`; `search` requires `read`. This option is required. +- `--file-system-id `: Assert the Filesystem ID embedded in the owner token. This option is required only when loading a locally stored owner token. +- `--fs-token `: Supply the owner token. Defaults to `TI_FS_TOKEN`, then the selected local credential. +- `--subject `: Set an optional server-side audit label of at most 64 bytes. It is not a unique selector. +- `--store-locally`: Store and select the generated scoped token for this profile and Filesystem. +- `--replace`: Replace an existing selected local token. Requires `--store-locally` and does not revoke the previous remote token. +- `--dry-run`: Validate the owner credential, region, lifetime, scopes, and local storage preconditions without generating a token. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Give a sandbox read and write access to one workspace: + + ```bash + # Use an owner token to create a 24-hour token limited to /workspace. + export TI_FS_TOKEN="" + ti fs generate-file-system-scoped-token \ + --subject sandbox-agent \ + --ttl 24h \ + --allow /workspace:read,list,write + ``` + +- Separate writable workspace data from read-only artifacts: + + ```bash + # Repeat --allow to assign different operations to independent prefixes. + ti fs generate-file-system-scoped-token \ + --fs-token "" \ + --ttl 8h \ + --allow /workspace:read,list,write,delete \ + --allow /artifacts:read,list + ``` + +- Select the generated scoped token for later local commands: + + ```bash + # Replacing the local selection does not revoke the previous remote owner token. + ti fs generate-file-system-scoped-token \ + --file-system-id "" \ + --ttl 1h \ + --allow /task:read,list,write \ + --store-locally \ + --replace + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [`ti fs generate-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) +- [`ti fs refresh-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md new file mode 100644 index 0000000000000..174fd45e6180c --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md @@ -0,0 +1,76 @@ +--- +title: ti fs generate-file-system-token +summary: Generate an additional owner token for one TiDB Cloud Filesystem. +--- + +# ti fs generate-file-system-token + +Generates an owner token for one Filesystem. The plaintext `fs_token` appears only in the successful response and cannot be recovered through the list command. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs generate-file-system-token + --file-system-id + --token-name + (--ttl | --no-expiration) + [--dry-run] + [--replace] + [--store-locally] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. This option is required. +- `--token-name `: Set an operational token name of at most 64 bytes. Names are not unique. This option is required. +- `--ttl `: Set a positive lifetime in whole seconds, up to 365 days. Specify exactly one of `--ttl` and `--no-expiration`. +- `--no-expiration`: Create a token without an expiry. Specify exactly one of `--ttl` and `--no-expiration`. +- `--store-locally`: Store and select the generated token for this profile and Filesystem. +- `--replace`: Replace an existing selected local token. Requires `--store-locally` and does not revoke the previous remote token. +- `--dry-run`: Validate credentials, region, lifetime, and local storage preconditions without generating a token. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Generate a short-lived token for a CI job: + + ```bash + # Save the one-time plaintext response in an owner-only file. + umask 077 + ti fs generate-file-system-token \ + --file-system-id "" \ + --token-name ci-deploy \ + --ttl 24h > ./ci-token.json + ``` + +- Generate a non-expiring token for another machine: + + ```bash + # Generation does not change the current local selection by default. + ti fs generate-file-system-token \ + --file-system-id "" \ + --token-name workstation \ + --no-expiration + ``` + +- Generate and select a replacement local token: + + ```bash + # The old remote token remains active until you explicitly disable or delete it. + ti fs generate-file-system-token \ + --file-system-id "" \ + --token-name local-owner-v2 \ + --ttl 720h \ + --store-locally \ + --replace + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [`ti fs list-file-system-tokens`](/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-import-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-import-file-system-token.md new file mode 100644 index 0000000000000..e96b3afced90d --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-import-file-system-token.md @@ -0,0 +1,58 @@ +--- +title: ti fs import-file-system-token +summary: Import an existing TiDB Cloud Filesystem token. +--- + +# ti fs import-file-system-token + +Validates an existing FS token against its regional endpoint and stores it in the selected local profile. The file system ID is derived from the token; `--file-system-id` is an optional consistency assertion. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs import-file-system-token + [--dry-run] + [--file-system-id ] + [--from-file ] + [--fs-token ] + [--help] + [--replace] + [--version] +``` + +## Options + +- `--dry-run`: Validate the token and destination without writing local credentials. +- `--file-system-id `: Assert that the token belongs to this file system ID. +- `--from-file `: Read the token from an owner-only file, or use `-` for standard input. +- `--fs-token `: Supply the token directly. Prefer `TI_FS_TOKEN` or `--from-file` to avoid process argument exposure. +- `--help`: Display help information. +- `--replace`: Replace a different locally stored token for the same file system after validation. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Import a token from a protected file: + + ```bash + # Validate the token remotely and store it under its embedded file system ID. + chmod 600 ./fs-token + ti fs import-file-system-token --from-file ./fs-token --region aws-us-east-1 + ``` + +- Import a token from standard input: + + ```bash + # Avoid placing the token in shell history or a process argument. + cat ./fs-token | ti fs import-file-system-token --from-file - --region aws-us-east-1 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md b/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md new file mode 100644 index 0000000000000..acca25a89d175 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.md @@ -0,0 +1,61 @@ +--- +title: ti fs list-file-system-tokens +summary: List token metadata for one TiDB Cloud Filesystem. +--- + +# ti fs list-file-system-tokens + +Lists non-secret token metadata for one Filesystem. The response never contains token plaintext. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs list-file-system-tokens + --file-system-id + [--fs-token ] + [--include-expired] + [--limit ] + [--offset ] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem whose tokens are listed. This option is required. +- `--fs-token `: Authorize the request with an owner FS token. Defaults to `TI_FS_TOKEN`; when neither is present, the command uses configured TiDB Cloud API keys. Scoped tokens cannot list token metadata. +- `--include-expired`: Include expired token metadata. Revoked tokens are not returned by the service. +- `--offset `: Set the zero-based token offset [default: 0]. +- `--limit `: Set the maximum number of tokens to return, from 1 through 200 [default: 50]. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- List current token metadata as text: + + ```bash + # Use token_id, not the non-unique token name, for later mutations. + ti fs list-file-system-tokens \ + --file-system-id "" \ + --output text + ``` + +- Inspect expired token metadata with pagination: + + ```bash + # Request up to 100 rows starting at offset 0. + ti fs list-file-system-tokens \ + --file-system-id "" \ + --include-expired \ + --offset 0 \ + --limit 100 + ``` + +## Related documentation + +- [`ti fs generate-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) +- [`ti fs generate-file-system-scoped-token`](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-list-file-systems.md b/ai/ti/reference/commands/fs/ti-fs-list-file-systems.md new file mode 100644 index 0000000000000..2c63e67ce2401 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-list-file-systems.md @@ -0,0 +1,40 @@ +--- +title: ti fs list-file-systems +summary: List remote TiDB Cloud Filesystems in a region. +--- + +# ti fs list-file-systems + +Lists every Filesystem that the selected TiDB Cloud credentials can access in the effective region. `has_local_token` indicates whether this machine has a matching data-plane token. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs list-file-systems + [--help] + [--version] +``` + +## Options + +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- List remotely managed Filesystems: + + ```bash + # Return the remote inventory for the profile's region without exposing tokens. + ti fs list-file-systems + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-list-files.md b/ai/ti/reference/commands/fs/ti-fs-list-files.md new file mode 100644 index 0000000000000..bd5d82f7acedc --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-list-files.md @@ -0,0 +1,46 @@ +--- +title: ti fs list-files +summary: List files in a TiDB Cloud Filesystem. +--- + +# ti fs list-files + +Lists entries below a remote path. The command alias is `ti fs ls`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs list-files + [--file-system-id ] + [--fs-token ] + [--help] + [--path ] + [--version] +``` + +## Options + +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--path `: File system directory path. \[default: /] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- List a remote directory: + + ```bash + # Return the entries under a specific Filesystem path. + ti fs list-files --file-system-id --path /reports + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-list-layers.md b/ai/ti/reference/commands/fs/ti-fs-list-layers.md new file mode 100644 index 0000000000000..3da168af15cf3 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-list-layers.md @@ -0,0 +1,44 @@ +--- +title: ti fs list-layers +summary: List layers in a TiDB Cloud Filesystem. +--- + +# ti fs list-layers + +Lists layers for the selected Filesystem. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs list-layers + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- List Filesystem layers: + + ```bash + # Return all layers available in the selected Filesystem. + ti fs list-layers --file-system-id + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-mount-file-system.md b/ai/ti/reference/commands/fs/ti-fs-mount-file-system.md new file mode 100644 index 0000000000000..53c3b01cc05dd --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-mount-file-system.md @@ -0,0 +1,99 @@ +--- +title: ti fs mount-file-system +summary: Mount a TiDB Cloud Filesystem. +--- + +# ti fs mount-file-system + +Mounts a Filesystem through automatic, FUSE, or WebDAV mode. The command alias is `ti fs mount`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs mount-file-system + --mount-path + [--cache-dir ] + [--driver ] + [--dry-run] + [--file-system-id ] + [--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] +``` + +## Options + +- `--mount-path `: Local mount path. \[required] +- `--cache-dir `: Local FUSE cache directory. If omitted, uses `~/.ti/cache/mounts/`. +- `--driver `: Mount driver: `auto`, `fuse`, or `webdav`. \[default: auto] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--foreground`: Run the mount runtime in the foreground until interrupted. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--local-root `: Local overlay root. If omitted, uses `~/.ti/local/fs/`. +- `--mount-profile `: Mount profile: `coding-agent`, `portable`, or `none`. If omitted, uses `none`. +- `--no-auto-unpack`: Skip default auto-unpack for portable mount profile before mounting. +- `--pack-path `: Local overlay path included by automatic or manual pack. Repeatable. +- `--read-cache-max-file-mb `: Maximum file size admitted to the FUSE read cache in MiB. 0 uses the default. \[default: 4] +- `--read-cache-size-mb `: FUSE read cache size in MiB. 0 uses the default. \[default: 128] +- `--read-cache-ttl `: FUSE read cache time to live. \[default: `30s`] +- `--read-only`: Read-only mount mode. +- `--ready-timeout `: Time to wait for a background mount to become ready. \[default: `30s`] +- `--remote-path `: The TiDB Cloud file system root path to mount. \[default: /] +- `--unpack-archive-path `: Restore the pack archive before mounting. +- `--version`: Display version information. +- `--write-back-cache`: Persist FUSE writes locally before writing them to the file system on flush. \[default: true] + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Mount a Filesystem with the default driver: + + ```bash + # Let the CLI select the default driver for the current platform. + ti fs mount-file-system --file-system-id --mount-path /path/to/workspace + ``` + +- Create a read-only FUSE mount: + + ```bash + # Expose the remote namespace through FUSE without permitting writes. + ti fs mount-file-system --file-system-id --mount-path /path/to/workspace --driver fuse --read-only + ``` + +- Use WebDAV on macOS without macFUSE: + + ```bash + # Select WebDAV explicitly when a FUSE runtime is unavailable. + ti fs mount-file-system --file-system-id --mount-path /path/to/workspace --driver webdav + ``` + +- Tune the FUSE read cache: + + ```bash + # Increase cache capacity for repeated reads of medium-sized files. + ti fs mount-file-system --file-system-id --mount-path /path/to/workspace --driver fuse --read-cache-size-mb 256 --read-cache-max-file-mb 16 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-move-file.md b/ai/ti/reference/commands/fs/ti-fs-move-file.md new file mode 100644 index 0000000000000..35d4a8de9d9a2 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-move-file.md @@ -0,0 +1,52 @@ +--- +title: ti fs move-file +summary: Move a file in a TiDB Cloud Filesystem. +--- + +# ti fs move-file + +Moves or renames a remote path. The command alias is `ti fs mv`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs move-file + --from-remote + --to-remote + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--overwrite] + [--version] +``` + +## Options + +- `--from-remote `: Source file path. \[required] +- `--to-remote `: Destination file path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--overwrite`: Replace an existing destination file. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Move a remote file: + + ```bash + # Rename or relocate an object entirely within the selected Filesystem. + ti fs move-file --file-system-id --from-remote /draft.md --to-remote /reports/final.md + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-pack-file-system.md b/ai/ti/reference/commands/fs/ti-fs-pack-file-system.md new file mode 100644 index 0000000000000..bfde9f28fb133 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-pack-file-system.md @@ -0,0 +1,65 @@ +--- +title: ti fs pack-file-system +summary: Pack local Filesystem overlay state. +--- + +# ti fs pack-file-system + +Packs selected local overlay state into a remote archive. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs pack-file-system + [--archive-path ] + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--local-root ] + [--mount-path ] + [--mount-profile ] + [--path ] + [--remote-root ] + [--version] +``` + +## Options + +- `--archive-path `: The path for the packed archive. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--local-root `: Local overlay root containing the overlay directory. +- `--mount-path `: The local mounted path. +- `--mount-profile `: The mount profile: `coding-agent`, `portable`, or `none`. If omitted, uses `none`. +- `--path `: Local overlay path for packing; repeatable. +- `--remote-root `: The TiDB Cloud file system root represented by the local overlay. \[default: /] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Pack a mounted workspace: + + ```bash + # Persist the local overlay associated with an existing mount. + ti fs pack-file-system --file-system-id --mount-path /path/to/workspace + ``` + +- Pack explicit roots: + + ```bash + # Create a portable archive from selected local and remote roots. + ti fs pack-file-system --file-system-id --local-root ./overlay --remote-root /workspace --mount-profile portable + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-read-file.md b/ai/ti/reference/commands/fs/ti-fs-read-file.md new file mode 100644 index 0000000000000..0d3ef64e85150 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-read-file.md @@ -0,0 +1,57 @@ +--- +title: ti fs read-file +summary: Read a file from a TiDB Cloud Filesystem. +--- + +# ti fs read-file + +Writes a remote file or byte range to stdout. The command alias is `ti fs cat`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs read-file + --path + [--file-system-id ] + [--fs-token ] + [--help] + [--length ] + [--offset ] + [--version] +``` + +## Options + +- `--path `: File path in the selected file system. \[required] +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--length `: Byte length for a ranged read. +- `--offset `: Zero-based byte offset for a ranged read. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Read a complete file: + + ```bash + # Write the remote file contents directly to standard output. + ti fs read-file --file-system-id --path /reports/report.md + ``` + +- Read a byte range: + + ```bash + # Fetch only the requested range from a large remote object. + ti fs read-file --file-system-id --path /archives/large.bin --offset 1024 --length 4096 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.md b/ai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.md new file mode 100644 index 0000000000000..c34778bc9a104 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.md @@ -0,0 +1,63 @@ +--- +title: ti fs refresh-file-system-token +summary: Rotate one TiDB Cloud Filesystem token and return its replacement plaintext once. +--- + +# ti fs refresh-file-system-token + +Rotates the supplied bearer token in place. Refresh is not idempotent: if the request commits but its response is lost, do not retry with the old token. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs refresh-file-system-token + [--file-system-id ] + [--fs-token ] + [--ttl ] + [--dry-run] +``` + +## Options + +- `--file-system-id `: Assert the Filesystem ID decoded from a supplied token. This option is required when loading a locally selected token. +- `--fs-token `: Supply the current token. Prefer `TI_FS_TOKEN` to avoid shell history and process-list exposure. Defaults to `TI_FS_TOKEN`, then the selected local credential. +- `--ttl `: Set a new positive lifetime in whole seconds, up to 365 days. Omit it to preserve the previous lifetime period. +- `--dry-run`: Validate token selection, region, TTL, and known local mount conflicts without rotating the token. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Refresh the selected local credential: + + ```bash + # ti atomically replaces the local credential after receiving the new token. + ti fs refresh-file-system-token --file-system-id "" + ``` + +- Refresh a token supplied by a secret manager: + + ```bash + # Capture the one-time replacement and update the external secret manager yourself. + TI_FS_TOKEN="" \ + TI_REGION_CODE="aws-us-east-1" \ + ti fs refresh-file-system-token > ./refreshed-token.json + ``` + +- Change the token lifetime during refresh: + + ```bash + # Rotate the token and set its new lifetime to 30 days. + TI_FS_TOKEN="" \ + TI_REGION_CODE="aws-us-east-1" \ + ti fs refresh-file-system-token --ttl 720h + ``` + +## Related documentation + +- [`ti fs generate-file-system-token`](/ai/ti/reference/commands/fs/ti-fs-generate-file-system-token.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-rollback-layer.md b/ai/ti/reference/commands/fs/ti-fs-rollback-layer.md new file mode 100644 index 0000000000000..fba8151d76427 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-rollback-layer.md @@ -0,0 +1,48 @@ +--- +title: ti fs rollback-layer +summary: Roll back a TiDB Cloud Filesystem layer. +--- + +# ti fs rollback-layer + +Rolls back changes in one layer without committing them to the base. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs rollback-layer + --layer-id + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--layer-id `: The ID of the layer. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Roll back a layer: + + ```bash + # Discard uncommitted changes and restore the layer's base view. + ti fs rollback-layer --file-system-id --layer-id "" + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-search-file-content.md b/ai/ti/reference/commands/fs/ti-fs-search-file-content.md new file mode 100644 index 0000000000000..df8f923ac1581 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-search-file-content.md @@ -0,0 +1,59 @@ +--- +title: ti fs search-file-content +summary: Search file content in a TiDB Cloud Filesystem. +--- + +# ti fs search-file-content + +Searches remote file content, optionally in a layer. The command alias is `ti fs grep`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs search-file-content + --pattern + [--file-system-id ] + [--fs-token ] + [--help] + [--layer-id ] + [--limit ] + [--path ] + [--version] +``` + +## Options + +- `--pattern `: Content search matching pattern. \[required] +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--layer-id `: Search within a file system layer. +- `--limit `: Maximum number of search results; 0 uses the service default. +- `--path `: File path prefix to be searched. \[default: /] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Search base Filesystem content: + + ```bash + # Find matching text under a remote directory and limit the result count. + ti fs search-file-content --file-system-id --path /workspace --pattern "TODO" --limit 50 + ``` + +- Search content in a layer: + + ```bash + # Inspect uncommitted layer content separately from the base Filesystem. + ti fs search-file-content --file-system-id --path /workspace --pattern "deprecated" --layer-id "" + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-unmount-file-system.md b/ai/ti/reference/commands/fs/ti-fs-unmount-file-system.md new file mode 100644 index 0000000000000..7e7c47db5b856 --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-unmount-file-system.md @@ -0,0 +1,54 @@ +--- +title: ti fs unmount-file-system +summary: Unmount a TiDB Cloud Filesystem. +--- + +# ti fs unmount-file-system + +Gracefully flushes and unmounts a background mount. The command alias is `ti fs umount`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs unmount-file-system + --mount-path + [--dry-run] + [--force] + [--help] + [--ignore-absent] + [--no-auto-pack] + [--pack-archive-path ] + [--timeout ] + [--version] +``` + +## Options + +- `--mount-path `: The local mounted path. \[required] +- `--dry-run`: Validate the request without applying changes. +- `--force`: Kill the mount process if graceful unmount times out. +- `--help`: Display help information. +- `--ignore-absent`: Return success when no file system mount state exists for the specified path. +- `--no-auto-pack`: Skip the portable mount profile's default auto-pack action. +- `--pack-archive-path `: Pack archive to write after unmount. +- `--timeout `: Time to wait for the mount process to exit. \[default: `30s`] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Unmount a Filesystem: + + ```bash + # Gracefully flush pending writes and detach the Filesystem mount. + ti fs unmount-file-system --mount-path /path/to/workspace + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/fs/ti-fs-unpack-file-system.md b/ai/ti/reference/commands/fs/ti-fs-unpack-file-system.md new file mode 100644 index 0000000000000..72f8ea7b7a85f --- /dev/null +++ b/ai/ti/reference/commands/fs/ti-fs-unpack-file-system.md @@ -0,0 +1,65 @@ +--- +title: ti fs unpack-file-system +summary: Restore local Filesystem overlay state. +--- + +# ti fs unpack-file-system + +Restores local overlay state from a remote archive. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti fs unpack-file-system + [--archive-path ] + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--local-root ] + [--mount-path ] + [--mount-profile ] + [--no-replace] + [--remote-root ] + [--version] +``` + +## Options + +- `--archive-path `: The path for the packed archive. +- `--dry-run`: Validate the request without applying changes. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the file system user token. If omitted, uses `TI_FS_TOKEN`. +- `--help`: Display help information. +- `--local-root `: The local overlay root to restore into. +- `--mount-path `: The local mounted path. +- `--mount-profile `: Mount profile: `coding-agent`, `portable`, or `none`. If omitted, uses `none`. +- `--no-replace`: Merge archive entries instead of replacing them. +- `--remote-root `: Find the packed archive under the specified root path when `--archive-path` is omitted. \[default: /] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Unpack into a mounted workspace: + + ```bash + # Restore the portable archive associated with an existing mount. + ti fs unpack-file-system --file-system-id --mount-path /path/to/workspace + ``` + +- Unpack explicit roots without replacement: + + ```bash + # Restore missing files while preserving existing destination entries. + ti fs unpack-file-system --file-system-id --local-root ./overlay --remote-root /workspace --mount-profile portable --no-replace + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/commands/ti/ti-configure.md b/ai/ti/reference/commands/ti/ti-configure.md new file mode 100644 index 0000000000000..ae2e8abc2b6c7 --- /dev/null +++ b/ai/ti/reference/commands/ti/ti-configure.md @@ -0,0 +1,58 @@ +--- +title: ti configure +summary: Configure a local TiDB Cloud CLI profile interactively or non-interactively. +--- + +# ti configure + +Configures a local TiDB Cloud CLI profile. Without flags, this is the only interactive TiDB Cloud CLI command. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti configure + [--help] + [--non-interactive] + [--region-code ] + [--tidb-cloud-private-key ] + [--tidb-cloud-public-key ] + [--version] +``` + +## Options + +- `--help`: Display help information. +- `--non-interactive`: Use this option to avoid being prompted for configuration values. You must provide at least three configuration values (`--tidb-cloud-public-key`, `--tidb-cloud-private-key`, and `--region-code`) when using this option. This is useful when running `ti` in a script or automated environment. +- `--region-code `: Default region code, for example `aws-us-east-1` or `aws-ap-southeast-1`. +- `--tidb-cloud-private-key `: TiDB Cloud API private key. +- `--tidb-cloud-public-key `: TiDB Cloud API public key. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Configure `ti` interactively: + + ```bash + # Enter the default region code and TiDB Cloud API keys when prompted. + ti configure + ``` + +- Configure `ti` for automation: + + ```bash + # Supply all required values without interactive prompts. + TI_REGION_CODE="aws-us-east-1" \ + TIDB_CLOUD_PUBLIC_KEY="" \ + TIDB_CLOUD_PRIVATE_KEY="" \ + ti configure --profile ci --non-interactive + ``` + +## Related documentation + +- [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) diff --git a/ai/ti/reference/commands/ti/ti-update.md b/ai/ti/reference/commands/ti/ti-update.md new file mode 100644 index 0000000000000..372ac3fb10cd5 --- /dev/null +++ b/ai/ti/reference/commands/ti/ti-update.md @@ -0,0 +1,62 @@ +--- +title: ti update +summary: Check for or install a TiDB Cloud CLI release update. +--- + +# ti update + +Checks for or installs a TiDB Cloud CLI release update. This command does not read or modify settings, profiles, credentials, operation logs, or other state under `~/.ti/`. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti update + [--check] + [--dry-run] + [--fail-if-update-available] + [--help] + [--target-version ] + [--version] +``` + +## Options + +- `--check`: Check whether a newer `ti` release is available without updating. +- `--dry-run`: Show the update plan without changing the local binary. +- `--fail-if-update-available`: With `--check`, exit with code 1 when an update is available. +- `--help`: Display help information. +- `--target-version `: Target `ti` version, such as `latest` or `vX.Y.Z`. \[default: latest] +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Check whether an update is available: + + ```bash + # Compare the installed version with the latest GitHub release without changing files. + ti update --check + ``` + +- Preview an update: + + ```bash + # Show the files and versions that an update would change. + ti update --dry-run + ``` + +- Install a specific release: + + ```bash + # Replace an eligible installation with the requested release version. + ti update --target-version + ``` + +## Related documentation + +- [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) diff --git a/ai/ti/reference/ti-agent-sandbox-example.md b/ai/ti/reference/ti-agent-sandbox-example.md new file mode 100644 index 0000000000000..b6d137351f7a4 --- /dev/null +++ b/ai/ti/reference/ti-agent-sandbox-example.md @@ -0,0 +1,114 @@ +--- +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 TiDB Cloud CLI configuration into the sandbox. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## The agent problem + +Coding agents often start in clean, short-lived sandboxes. The local disk disappears when the sandbox is replaced, but the agent still needs previous artifacts, repository state, and files produced by other workers. Rebuilding that state wastes task time, while copying `~/.ti/` or injecting TiDB Cloud API keys gives the sandbox control-plane credentials it does not need. + +## Limitations of local storage and full cloud credentials + +A sandbox-local directory is fast but not durable or shared. Generic object-storage APIs require application-specific download and upload logic instead of ordinary file operations. Giving every sandbox the user's complete cloud credentials solves access at the cost of a broader security boundary. + +## How TiDB Cloud CLI changes the workflow + +A trusted machine provisions the Filesystem once. The sandbox receives only the Filesystem owner token and region code, and can immediately use data-plane, mount, Git, journal, and vault workflows without `ti configure`. The token identifies the Filesystem. When an agent needs only selected secrets, use a delegated vault token instead of the owner token. + +## Prerequisites + +- Install and configure the TiDB Cloud CLI on a trusted machine. +- Install the TiDB Cloud CLI in the sandbox. The release installer includes `ti-drive9`. +- Use a secure secret manager or encrypted sandbox input for token transfer. + +## Step 1. Provision on the trusted machine + +```bash +umask 077 +ti fs create-file-system --wait > ./filesystem.json +export FILE_SYSTEM_ID="$(jq -r '.file_system_id' ./filesystem.json)" +export TI_FS_TOKEN="$(jq -r '.fs_token' ./filesystem.json)" +``` + +Store the token in a secret manager, record `FILE_SYSTEM_ID` for control-plane cleanup, and record the canonical region code used by the profile, for example `aws-us-east-1`. Delete `filesystem.json` after storing the token securely. + +## Step 2. Inject the minimum sandbox environment + +Configure the sandbox secret/environment mechanism with: + +```bash +TI_FS_TOKEN= +TI_REGION_CODE=aws-us-east-1 +``` + +The sandbox does not need `TI_PUBLIC_KEY`, `TI_PRIVATE_KEY`, `ti configure`, or files copied from `~/.ti/`. + +## Step 3. Verify direct access + +In the sandbox: + +```bash +printf 'sandbox ready\n' | ti fs copy-file \ + --from-stdin \ + --to-remote /sandbox/status.txt + +ti 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" +ti fs mount-file-system \ + --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 `ti fs-git`, `ti fs-journal`, and owner-authorized `ti fs-vault` commands with the same FS environment. Give agents a delegated `TI_VAULT_TOKEN` instead of the owner token when they need only selected secret fields. + +## Cleanup + +Stop writers and unmount. A graceful FUSE unmount automatically flushes and drains pending work: + +```bash +ti fs unmount-file-system --mount-path "$HOME/workspace" +``` + +Use `ti fs drain-file-system --mount-path "$HOME/workspace"` separately when you need to verify remote durability while keeping the mount online. Back on the trusted machine: + +```bash +ti fs delete-file-system \ + --file-system-id "$FILE_SYSTEM_ID" +``` + +## Security notes + +- Treat `TI_FS_TOKEN` as an owner credential. +- Do not place it in an image, repository, command flag, or operation log. +- Deleting the sandbox does not delete the remote Filesystem. +- Graceful unmount drains pending FUSE writes; deleting the sandbox without unmounting does not. + +## What's next + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/ti/reference/ti-ci-artifact-handoff-example.md b/ai/ti/reference/ti-ci-artifact-handoff-example.md new file mode 100644 index 0000000000000..dc9146d06e943 --- /dev/null +++ b/ai/ti/reference/ti-ci-artifact-handoff-example.md @@ -0,0 +1,80 @@ +--- +title: Hand Off CI Artifacts Between Isolated Jobs with TiDB Cloud Filesystem +summary: Persist build output in TiDB Cloud Filesystem and consume it from a later CI job without copying a complete TiDB Cloud CLI profile. +--- + +# Hand Off CI Artifacts Between Isolated Jobs with TiDB Cloud Filesystem + +This scenario uses a Filesystem as a durable handoff point between isolated CI jobs or runners. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — 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 TiDB Cloud CLI changes the workflow + +The pipeline injects one Filesystem token and region into both jobs. The token identifies the Filesystem. The producer uploads output under a run-specific path, and the consumer downloads or streams that exact path. Neither job needs TiDB Cloud API keys or a copied `~/.ti/` directory. + +## Prerequisites + +Provision a Filesystem on a trusted machine and store these values as protected CI secrets or variables: + +```text +TI_FS_TOKEN +TI_REGION_CODE +``` + +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 +ti 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 +ti 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 +ti 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 +ti fs delete-file --path "/ci/${RUN_ID}" --recursive +``` + +Use unique run IDs and do not delete the whole Filesystem from an individual job. Filesystem deletion requires the trusted control-plane configuration and should remain a separate owner operation. + +## Related reference + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/ti/reference/ti-cli-reference.md b/ai/ti/reference/ti-cli-reference.md new file mode 100644 index 0000000000000..735b6b2800ccd --- /dev/null +++ b/ai/ti/reference/ti-cli-reference.md @@ -0,0 +1,261 @@ +--- +title: TiDB Cloud CLI Command Reference +summary: Reference global options, output and query behavior, dry-run rules, help forms, errors, command families, and Filesystem aliases. +--- + +# TiDB Cloud CLI Command Reference + +This reference describes behavior shared across the `ti` command surface. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Syntax + +```text +ti [subcommand] [required options] [optional options] [global options] +``` + +The `ti` executable accepts long flags only. A one-letter flag such as `-p` is rejected. + +## Command tree + +```text +ti +├── configure +├── update +├── 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 +│ ├── import-file-system-token +│ ├── generate-file-system-token +│ ├── generate-file-system-scoped-token +│ ├── list-file-system-tokens +│ ├── enable-file-system-token +│ ├── disable-file-system-token +│ ├── delete-file-system-token +│ ├── refresh-file-system-token +│ ├── list-file-systems +│ ├── describe-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 `ti`, `db`, `fs`, `fs-git`, `fs-journal`, or `fs-vault`. + +Required options appear before optional options in generated usage. Optional options are enclosed in brackets: + +```text +ti db describe-db-cluster + --db-cluster-id + [--output ] + [--view ] +``` + +In command help, value types are enclosed in angle brackets and required options include `(required)` after the option name and type: + +```text +--db-cluster-name (required) Starter DB cluster display name +--wait Wait until the created cluster is active +``` + +## Global options + +- `--debug`: Enable redacted debug output. +- `--output `: Set the output format to `json` or `text`. \[default: json] +- `--profile `: Select a local profile. \[default: default] +- `--query `: Apply a JMESPath expression before rendering the output. +- `--region `: Override the profile's canonical region code for the current command, for example, `aws-us-east-1`. + +Command pages document `--help`, `--version`, and all command-specific options separately. + +## Output + +Structured control-plane commands return JSON by default: + +```bash +ti db list-db-clusters --db-cluster-type starter +``` + +Use text output for terminal inspection: + +```bash +ti db list-db-clusters --db-cluster-type starter --output text +``` + +Raw byte-oriented commands such as `ti fs read-file` and `ti fs copy-file --to-stdout` write file content directly. + +## JMESPath queries + +`--query` runs after successful command execution and before output rendering: + +```bash +ti db list-db-clusters \ + --db-cluster-type starter \ + --query 'clusters[].{id:id,name:display_name,state:state}' +``` + +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 +ti 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 `ti` without a command returns exit code `2` and prints a compact command-tree synopsis to stderr: + +```text +ti [ERROR]: the following arguments are required: command + +The TiDB Cloud Command Line Interface is a unified tool to manage your TiDB Cloud Filesystem (FS) and Starter services. + +usage: ti [] [parameters] +To see help information, you can run: + + ti help + ti help + ti help +``` + +Use an explicit help form to display commands and flags: + +```bash +ti help +ti db help +ti db create-db-cluster help +ti --help +ti db --help +ti db create-db-cluster --help +ti --version +ti fs --version +``` + +`help` is a command for navigating the command tree. `--help` is the conventional flag on each command; both intentionally coexist. + +## Errors and exit behavior + +Human-readable errors start with a blank line and use a stable prefix: + +```text +ti [ERROR]: +``` + +Errors are written to stderr and successful command output is written to stdout. Usage and configuration failures return a nonzero exit code before remote mutation. Runtime and remote API failures also return nonzero. An interrupted interactive configuration returns exit code `130`. + +`--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/ti/reference/ti-install-configure-update.md) | Install releases, configure profiles, update, and uninstall `ti` | +| [Starter Databases and SQL](/ai/ti/reference/ti-starter-database.md) | Manage Starter clusters, branches, and SQL | +| [Filesystem](/ai/ti/reference/ti-filesystem.md) | Manage Filesystems, files, layers, packs, and mounts | +| [Filesystem Git Workspaces](/ai/ti/reference/ti-filesystem-git.md) | Manage Git workspaces on mounted Filesystems | +| [Filesystem Journals](/ai/ti/reference/ti-filesystem-journal.md) | Manage verifiable journals | +| [Filesystem Vault](/ai/ti/reference/ti-filesystem-vault.md) | Manage secrets and delegated access | + +For complete commands and options, run: + +```bash +ti help +ti 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 TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/ti/reference/ti-configuration-and-credentials.md b/ai/ti/reference/ti-configuration-and-credentials.md new file mode 100644 index 0000000000000..6881bafdd49a8 --- /dev/null +++ b/ai/ti/reference/ti-configuration-and-credentials.md @@ -0,0 +1,235 @@ +--- +title: TiDB Cloud CLI Configuration and Credentials +summary: Reference TiDB Cloud CLI profiles, precedence rules, local state paths, Filesystem credentials, SQL credentials, mount locators, and operation logs. +--- + +# TiDB Cloud CLI Configuration and Credentials + +`ti` stores all product-owned local state under `~/.ti/` and separates non-sensitive configuration from credentials. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Main files + +```toml +# ~/.ti/config +[default] +region_code = "aws-us-east-1" +``` + +```toml +# ~/.ti/credentials +[default] +ti_public_key = "..." +ti_private_key = "..." +``` + +The credentials file uses owner-only permissions where the platform supports POSIX modes. + +Global preferences are separate from profiles and credentials: + +```toml +# ~/.ti/.preferences +schema_version = 1 + +[logging] +enabled = true +max_file_mb = 10 +max_files = 5 + +[telemetry] +enabled = false +``` + +The dot-prefixed preferences file is optional, hidden from ordinary directory listings, and applies to every profile. Fresh installs and `ti configure` do not create it. Reading a user-created file does not rewrite its permissions, comments, or formatting. + +## Profile selection + +The profile namespace is selected in this order: + +1. explicit `--profile`; +2. `TI_PROFILE`; +3. `default`. + +An explicit empty profile is invalid. + +## TiDB Cloud API credentials + +Credential selection is: + +1. `TI_PUBLIC_KEY` and `TI_PRIVATE_KEY`, when either is set; +2. the selected section of `~/.ti/credentials`. + +Both environment values are required together. `ti` never mixes one environment half with one file half. + +Placement selection is: + +1. explicit global `--region`; +2. `TI_REGION_CODE`; +3. profile `region_code`. + +Command flags, environment inputs, saved configuration, and command defaults are resolved per field. Values can therefore come from different levels when they do not form an atomic pair such as the API key pair. + +## Starter project placement + +The TiDB Cloud CLI does not accept or store a project selector. Starter cluster creation omits project placement and lets TiDB Cloud select its server-side default project. Project fields and labels returned by TiDB Cloud remain visible as resource metadata and are not reused for later requests. + +## Filesystem credentials and remote inventory + +One profile can access multiple Filesystems. Drive9's remote inventory is authoritative for resource existence and status. Local state stores only credentials and their routing hint: + +```text +~/.ti/fs_credentials///credentials +``` + +The credential contains the server-assigned file system ID, canonical region code, selected `api_key`, and optional authoritative token metadata, and uses owner-only permissions. `ti fs list-file-systems` reads remote resources and joins only the non-secret `has_local_token` hint. + +One remote Filesystem can have multiple tokens, but each profile stores at most one selected token per Filesystem. The local store is an operational selection, not a replica of remote token inventory. Credentials created by provisioning or older imports might not contain `token_id`, `scope_kind`, `token_name`, `expires_at`, or `scopes`; they remain valid for data-plane use, and `ti` does not guess missing metadata from token-list rows. + +`ti fs generate-file-system-token` does not change the selected credential unless `--store-locally` is set. `--replace` changes only the local selection and leaves the previous remote token active. A refresh sourced from the local credential atomically replaces it. A refresh sourced from a flag or `TI_FS_TOKEN` returns the replacement plaintext without writing local state. + +`ti fs generate-file-system-scoped-token` accepts only an owner token and can store its authoritative path scopes locally. The token JWT itself contains the Filesystem ID but not the token kind, token ID, or scopes. Therefore, an explicit or environment token is passed to the service for authorization instead of being classified locally. `TI_FS_TOKEN` can contain either an owner token or a scoped token; available operations depend on its server-side capability. + +Resource selection is: + +1. explicit `--file-system-id`; +2. `TI_FS_FILE_SYSTEM_ID`; +3. derive the ID from an explicitly supplied FS token; +4. otherwise fail with `fs.missing_file_system_id`. + +`ti` never infers a Filesystem from a saved default or from the number of local credentials. Use `--file-system-id` for one command or `TI_FS_FILE_SYSTEM_ID` for a shell, sandbox, or automation environment. + +FS owner credential selection for remote `fs`, `fs-git`, `fs-journal`, and owner `fs-vault` operations is: + +1. explicit `--fs-token`; +2. `TI_FS_TOKEN`; +3. selected resource credential. + +Prefer `TI_FS_TOKEN` over a flag because flags can remain in shell history or process listings. + +## Config-free Filesystem inputs + +A clean sandbox needs only: + +```bash +export TI_FS_TOKEN="" +export TI_REGION_CODE="aws-us-east-1" +``` + +These values form an in-memory namespace only. `ti` derives the ID from the token and does not write either value to `~/.ti/`. `TI_FS_FILE_SYSTEM_ID` is optional and, when present, must match the token. Remote list, describe, provisioning, and deletion require TiDB Cloud API credentials; deletion does not require a local FS token. + +## DB SQL credentials + +Generated SQL credentials are cluster-scoped: + +```text +~/.ti/db_users//credentials +``` + +```toml +[read_only] +username = "..." +password = "..." + +[read_write] +username = "..." +password = "..." + +[admin] +username = "..." +password = "..." +``` + +`ti db create-db-sql-users` creates or repairs these stable users. They are not stored in the main credentials file. + +## Companion state and mount locators + +Each registered Filesystem has an isolated companion home: + +```text +~/.ti/drive9-home/// +``` + +Do not edit this state or a standalone `~/.drive9` configuration for `ti` workflows. + +A successful background FS or vault mount writes a non-secret locator: + +```text +~/.ti/mounts/.locator.json +``` + +The locator records the placement and companion-home information required for drain and unmount from the same `HOME`. It does not contain the FS token. Successful unmount removes it. + +## Operation logs + +`ti` writes redacted local JSON Lines events to: + +```text +~/.ti/logs/ti.jsonl +``` + +This log is local audit/debug data, not telemetry. It can include command names, flag names, profile and region, duration, exit and stable error codes, HTTP method/status, operation, and request ID. It excludes flag values, SQL, file paths and contents, payloads, connection strings, and credentials. + +Disable it for one process: + +```bash +TI_LOGGING=off ti db list-db-clusters --db-cluster-type starter +``` + +Or create or edit `~/.ti/.preferences`: + +```toml +schema_version = 1 + +[logging] +enabled = false +``` + +Environment values `off`, `false`, `0`, and `no` disable logging; `on`, `true`, `1`, and `yes` enable it. Environment takes precedence over settings. Invalid settings disable operation logging without failing the requested command. + +Existing installations that stored `[logging]` in `~/.ti/config` migrate those values to `~/.ti/.preferences` automatically. The migration preserves profiles and credentials. `ti update` does not read or write settings, profiles, credentials, operation logs, or other state under `~/.ti/`. + +## Anonymous telemetry + +Release builds send one best-effort completion event for eligible commands to the TiDB Cloud CLI telemetry service. The event contains the canonical command and explicitly supplied flag names, stable exit and error codes, duration, region, CLI version, OS, architecture, install source, and a random pseudonymous installation ID. It does not contain flag values, credentials, tokens, SQL text, file paths or contents, command output, API payloads, profile names, or cloud resource IDs. + +Development builds and recognized CI environments default to disabled. Help, version, commandless usage, and every `ti update` mode are always excluded. Disable telemetry persistently by adding the following global preference: + +```toml +[telemetry] +enabled = false +``` + +Disable it for one process without changing the file: + +```bash +TI_TELEMETRY=off ti db list-db-clusters --db-cluster-type starter +``` + +The TiDB Cloud CLI creates `~/.ti/.telemetry-installation-id` lazily for the first eligible event and restricts it to the current user where POSIX permissions are available. Delete this file to reset the pseudonymous identity. Telemetry delivery is lossy and never changes command output, errors, or exit status. + +An integration can attach explicit process-scoped metadata without changing a profile or command. `TI_TELEMETRY_TAG` accepts a UTF-8 string up to 128 bytes. `TI_TELEMETRY_EXTRA` accepts one complete JSON value up to 2 KiB after compaction. Invalid, prohibited, deeply nested, or oversized metadata is omitted without affecting the command. Do not include credentials, tokens, SQL, paths, personal data, profile names, or cloud resource IDs in either value: + +```bash +TI_TELEMETRY_TAG="e2b-preview" \ +TI_TELEMETRY_EXTRA='{"campaign":"launch","runtime":"e2b"}' \ +ti fs list-files --file-system-id --path / +``` + +## 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 + +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) diff --git a/ai/ti/reference/ti-daily-workflow-example.md b/ai/ti/reference/ti-daily-workflow-example.md new file mode 100644 index 0000000000000..93957212654d6 --- /dev/null +++ b/ai/ti/reference/ti-daily-workflow-example.md @@ -0,0 +1,111 @@ +--- +title: Run a Daily TiDB Cloud CLI Workflow +summary: Inspect resources, manage a Starter cluster and Filesystem, check for TiDB Cloud CLI updates, and clean up resources. +--- + +# Run a Daily TiDB Cloud CLI Workflow + +This example follows a typical operator workflow across TiDB Cloud Starter and TiDB Cloud Filesystem. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Prerequisites + +- Install `ti` and run `ti configure`. +- Ensure your organization has capacity for one Starter cluster and one Filesystem. + +## Step 1. Inspect current resources + +```bash +ti db list-db-clusters --db-cluster-type starter --output text +ti fs list-file-systems --output text +``` + +## Step 2. Create a Starter cluster + +```bash +ti db create-db-cluster \ + --db-cluster-type starter \ + --db-cluster-name daily-demo \ + --dry-run + +ti db create-db-cluster \ + --db-cluster-type starter \ + --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 +ti db describe-db-cluster \ + --db-cluster-id "" \ + --output text +``` + +## Step 3. Verify SQL access + +```bash +ti db create-db-sql-users --db-cluster-id "" +ti db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --sql "SELECT CURRENT_TIMESTAMP AS checked_at" \ + --output text +``` + +## Step 4. Create and use a Filesystem + +```bash +export TI_FS_FILE_SYSTEM_ID="$(ti fs create-file-system --query file_system_id --output text)" + +printf 'daily workflow\n' | ti fs copy-file \ + --from-stdin \ + --to-remote /notes/today.txt + +ti fs list-files \ + --path /notes \ + --output text +``` + +The file in `/notes/today.txt` verifies that the explicitly selected resource is usable. + +## Step 5. Check for updates + +Unmount active filesystems before applying an update. A check is always non-mutating: + +```bash +ti update --check +``` + +Apply an update when appropriate: + +```bash +ti update --dry-run +ti update +``` + +## Cleanup + +```bash +ti fs delete-file-system \ + --file-system-id "$TI_FS_FILE_SYSTEM_ID" + +ti db delete-db-cluster \ + --db-cluster-id "" +``` + +Deleting local TiDB Cloud CLI 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 + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/ti-filesystem-git.md b/ai/ti/reference/ti-filesystem-git.md new file mode 100644 index 0000000000000..8e34605c55187 --- /dev/null +++ b/ai/ti/reference/ti-filesystem-git.md @@ -0,0 +1,116 @@ +--- +title: TiDB Cloud Filesystem Git CLI Command Reference +summary: Reference every `ti fs-git` command for cloning, hydrating, and managing linked Git worktrees. +--- + +# TiDB Cloud Filesystem Git CLI Command Reference + +`ti fs-git` accelerates Git workspace setup on mounted TiDB Cloud Filesystem paths. It augments Git; you continue to use ordinary `git` commands for status, edit, add, commit, fetch, and push. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Command tree + +```text +ti 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. | `ti fs-git clone-git-workspace --repo-url https://github.com/pingcap/tidb.git --target-path /workspace/tidb --blobless --hydrate background` | +| `hydrate-git-workspace` | Materializes clean Git data for an existing fast or blobless workspace. | `ti fs-git hydrate-git-workspace --target-path /workspace/tidb --timeout 30m` | +| `add-git-worktree` | Creates a linked worktree from a base workspace. | `ti fs-git add-git-worktree --base-path /workspace/tidb --worktree-path /workspace/feature --branch-name feature-x` | +| `remove-git-worktree` | Removes a linked worktree; dirty worktrees require explicit `--force`. | `ti fs-git remove-git-worktree --worktree-path /workspace/feature` | + +## Prerequisites + +- 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 +ti 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 +ti 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 +ti 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 +ti 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 +ti fs-git remove-git-worktree \ + --worktree-path /path/to/workspace/tidb-feature +``` + +The command refuses a dirty worktree by default. Use `--force` only after deciding that local changes can be discarded: + +```bash +ti 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/ti/reference/ti-git-workspace-for-agents-example.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/ti-filesystem-journal.md b/ai/ti/reference/ti-filesystem-journal.md new file mode 100644 index 0000000000000..4ececd10dc4cf --- /dev/null +++ b/ai/ti/reference/ti-filesystem-journal.md @@ -0,0 +1,101 @@ +--- +title: TiDB Cloud Filesystem Journal CLI Command Reference +summary: Reference every `ti fs-journal` command for creating, appending, reading, searching, and verifying journals. +--- + +# TiDB Cloud Filesystem Journal CLI Command Reference + +`ti fs-journal` provides an append-only, verifiable ledger for agent and workflow events. Unlike a mutable text file, a journal assigns ordered sequence numbers, supports structured search, and maintains a hash chain that can detect alteration. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Command tree + +```text +ti 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. | `ti fs-journal create-journal --journal-kind agent --title "review task" --actor agent:reviewer` | +| `append-journal-entries` | Appends JSON entries from repeatable flags, JSON Lines stdin, or a JSON array. | `ti fs-journal append-journal-entries --journal-id jrn-demo --entry-json '{"type":"task.started"}'` | +| `read-journal-entries` | Reads ordered entries after a sequence number. | `ti fs-journal read-journal-entries --journal-id jrn-demo --after-seq 0 --limit 100` | +| `search-journal-entries` | Searches journals and entries by type, kind, actor, status, subject, label, or time. | `ti fs-journal search-journal-entries --entry-type task.started --include-entries` | +| `verify-journal` | Recalculates and verifies one journal's ordered hash chain. | `ti fs-journal verify-journal --journal-id jrn-demo --output text` | + +## Prerequisites + +Select a Filesystem by ID with locally stored credentials, or provide only `TI_FS_TOKEN` and `TI_REGION_CODE`; `TI_FS_FILE_SYSTEM_ID` is an optional assertion. + +## Create a journal + +```bash +ti fs-journal create-journal \ + --journal-id jrn-demo \ + --journal-kind agent \ + --title "demo task" \ + --actor agent:ti \ + --label env=dev +``` + +`--journal-id` is optional and generated when omitted. Labels are repeatable. + +## Append entries + +Append one or more JSON objects: + +```bash +ti fs-journal append-journal-entries \ + --journal-id jrn-demo \ + --entry-json '{"type":"task.started","status":"running"}' \ + --entry-json '{"type":"tool.called","tool":"ti"}' +``` + +Use `--entry-type` as a default for entries without `type`, and add `--source` or repeatable `--subject` metadata. `--idempotency-key` makes a retry deterministic; the CLI generates one when omitted. + +For pipelines, send JSON Lines on stdin, or use `--json-array` for a JSON array. + +## Read and search + +Read entries after a sequence: + +```bash +ti fs-journal read-journal-entries \ + --journal-id jrn-demo \ + --after-seq 0 \ + --limit 100 +``` + +Search across journals: + +```bash +ti 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 +ti 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/ti/reference/ti-journal-agent-workflow-example.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/ti/reference/ti-filesystem-vault.md b/ai/ti/reference/ti-filesystem-vault.md new file mode 100644 index 0000000000000..92e746a8483a2 --- /dev/null +++ b/ai/ti/reference/ti-filesystem-vault.md @@ -0,0 +1,172 @@ +--- +title: TiDB Cloud Filesystem Vault CLI Command Reference +summary: Reference every `ti fs-vault` command for secrets, grants, audit events, process injection, and read-only mounts. +--- + +# TiDB Cloud Filesystem Vault CLI Command Reference + +`ti fs-vault` stores structured secrets and delegates limited, expiring access to agents. Owner operations use the Filesystem owner credential; delegated reads use a vault token scoped to selected secrets or fields. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Command tree + +```text +ti 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. | `ti fs-vault create-secret --secret-name db-prod --field PASSWORD=@./password.txt` | +| `replace-secret` | Replaces all fields from files in one directory. | `ti fs-vault replace-secret --secret-path /n/vault/db-prod --from-directory ./secret-fields` | +| `read-secret` | Reads all fields or one field as structured, raw, or environment output. | `ti fs-vault read-secret --secret-name db-prod --field DB_URL --format raw` | +| `list-secrets` | Lists secrets visible to the active owner or delegated credential. | `ti fs-vault list-secrets` | +| `delete-secret` | Deletes one owner-visible secret. | `ti fs-vault delete-secret --secret-name db-prod` | +| `create-grant` | Creates a scoped, expiring delegated token for one agent. | `ti fs-vault create-grant --agent-id deploy-agent --scope db-prod/DB_URL --permission read --ttl 10m` | +| `delete-grant` | Revokes one grant by ID. | `ti fs-vault delete-grant --grant-id "" --reason completed` | +| `list-audit-events` | Lists vault access events using secret, agent, time, and limit filters. | `ti fs-vault list-audit-events --secret-name db-prod --limit 20` | +| `run-with-secret` | Runs a child command with secret fields injected as environment variables. | `ti fs-vault run-with-secret --secret-path /n/vault/db-prod -- ./deploy.sh` | +| `mount-vault` | Mounts delegated readable fields as a local read-only FUSE filesystem. | `ti fs-vault mount-vault --mount-path /path/to/vault --vault-token "$TI_VAULT_TOKEN"` | +| `unmount-vault` | Unmounts a local vault mount. | `ti fs-vault unmount-vault --mount-path /path/to/vault` | + +## Prerequisites + +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 +ti 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 +ti fs-vault replace-secret \ + --secret-path /n/vault/db-prod \ + --from-directory ./secret-fields +``` + +## Read, list, and delete + +```bash +ti fs-vault list-secrets +ti fs-vault read-secret --secret-name db-prod +ti fs-vault read-secret --secret-name db-prod --field DB_URL --format raw +ti fs-vault read-secret --secret-name db-prod --field DB_URL --format env +``` + +Delete an owner-visible secret: + +```bash +ti 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 TI_VAULT_TOKEN="$(ti 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 +ti fs-vault read-secret \ + --secret-name db-prod \ + --field DB_URL \ + --format raw +``` + +`TI_VAULT_TOKEN` is preferred over `--vault-token` because command-line values can remain in process listings or shell history. + +## Inject a secret into a process + +```bash +ti 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 +ti fs-vault list-audit-events \ + --secret-name db-prod \ + --agent-id deploy-agent \ + --since 24h \ + --limit 20 + +ti 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 +ti fs-vault mount-vault \ + --mount-path /path/to/vault \ + --vault-token "$TI_VAULT_TOKEN" +``` + +The mount is read-only. `--foreground` keeps it attached to the terminal, and `--ready-timeout` changes the background readiness wait. + +Unmount: + +```bash +ti fs-vault unmount-vault --mount-path /path/to/vault +``` + +Unmount also supports `--timeout`, `--force`, and `--ignore-absent`. Vault mount is unavailable on Windows and requires FUSE support; direct `read-secret` and `run-with-secret` do not require a mount. + +## 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 TiDB Cloud CLI configuration or operation logs. +- Stop processes using a vault mount before unmounting. +- Revoke a grant after the task finishes. + +## What's next + +- [Delegate Secrets to an Agent](/ai/ti/reference/ti-vault-agent-secrets-example.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/ti/reference/ti-filesystem.md b/ai/ti/reference/ti-filesystem.md new file mode 100644 index 0000000000000..6035e1babba68 --- /dev/null +++ b/ai/ti/reference/ti-filesystem.md @@ -0,0 +1,546 @@ +--- +title: TiDB Cloud Filesystem CLI Command Reference +summary: Reference every `ti fs` command for Filesystem resources, files, layers, packs, and mounts. +--- + +# TiDB Cloud Filesystem CLI Command Reference + +Use `ti fs` to provision TiDB Cloud Filesystem resources and access their data from commands or local mounts. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Command tree + +```text +ti fs +├── create-file-system +├── import-file-system-token +├── generate-file-system-token +├── generate-file-system-scoped-token +├── list-file-system-tokens +├── enable-file-system-token +├── disable-file-system-token +├── delete-file-system-token +├── refresh-file-system-token +├── list-file-systems +├── describe-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 with a server-assigned ID; `--wait` waits until data-plane access is ready. | `ti fs create-file-system --wait` | +| `import-file-system-token` | Validates and stores an existing token under its embedded file system ID. | `ti fs import-file-system-token --from-file ./fs-token --region aws-us-east-1` | +| `generate-file-system-token` | Generates an additional owner token and returns its plaintext once. | `ti fs generate-file-system-token --file-system-id --token-name ci --ttl 24h` | +| `generate-file-system-scoped-token` | Uses an owner token to generate a finite path-and-operation-limited token. | `ti fs generate-file-system-scoped-token --ttl 24h --allow /workspace:read,list` | +| `list-file-system-tokens` | Lists non-secret token metadata for one Filesystem. | `ti fs list-file-system-tokens --file-system-id ` | +| `enable-file-system-token` | Re-enables a disabled token by immutable token ID. | `ti fs enable-file-system-token --file-system-id --token-id ` | +| `disable-file-system-token` | Temporarily disables a token by immutable token ID. | `ti fs disable-file-system-token --file-system-id --token-id ` | +| `delete-file-system-token` | Permanently revokes a token by immutable token ID. | `ti fs delete-file-system-token --file-system-id --token-id ` | +| `refresh-file-system-token` | Rotates the supplied token and returns its replacement plaintext once. | `ti fs refresh-file-system-token --file-system-id ` | +| `list-file-systems` | Lists remote resources available to the TiDB Cloud credentials in the effective region. | `ti fs list-file-systems --output text` | +| `describe-file-system` | Reads one remote resource by ID without requiring its FS token. | `ti fs describe-file-system --file-system-id ` | +| `check-file-system` | Verifies resource selection, endpoint resolution, credentials, and companion access. | `ti fs check-file-system --file-system-id ` | +| `delete-file-system` | Requests asynchronous deletion by ID and removes a matching local credential after acceptance. | `ti fs delete-file-system --file-system-id ` | + +### Data and namespace commands + +| Command | Purpose and key inputs | Example | +| --- | --- | --- | +| `copy-file` | Uploads, downloads, streams, appends, resumes, or recursively copies local and remote paths. | `ti fs copy-file --from-local ./report.md --to-remote /reports/report.md` | +| `read-file` | Writes a complete file or byte range to stdout. | `ti fs read-file --path /reports/report.md --offset 0 --length 1024` | +| `list-files` | Lists entries under a remote path. | `ti fs list-files --path /reports --output text` | +| `describe-file` | Returns metadata for one remote path. | `ti fs describe-file --path /reports/report.md` | +| `move-file` | Moves or renames one remote path. | `ti fs move-file --from-remote /draft.md --to-remote /reports/final.md` | +| `delete-file` | Deletes one remote path; `--recursive` is required for non-empty directories. | `ti fs delete-file --path /scratch --recursive` | +| `create-directory` | Creates a remote directory and optionally sets its mode. | `ti fs create-directory --path /reports/archive --mode 0755` | +| `chmod-file` | Changes remote POSIX mode metadata. | `ti fs chmod-file --path /reports/final.md --mode 0600` | +| `create-symlink` | Creates a symbolic link with a target string and link path. | `ti fs create-symlink --target final.md --link-path /reports/latest.md` | +| `create-hardlink` | Creates a hard link from an existing remote path. | `ti fs create-hardlink --source-path /reports/final.md --link-path /reports/final-copy.md` | +| `search-file-content` | Searches file contents below a path, optionally within a layer. | `ti fs search-file-content --path /reports --pattern "TODO"` | +| `find-files` | Finds paths by name, type, tags, size, or timestamps. | `ti fs find-files --path /reports --file-name-pattern "*.md" --tag stage=review` | + +### Layer and portability commands + +| Command | Purpose and key inputs | Example | +| --- | --- | --- | +| `create-layer` | Creates an isolated change layer over `--base-root-path`; returns a generated layer ID when one is not supplied. | `ti fs create-layer --base-root-path /workspace --layer-name task` | +| `list-layers` | Lists layers for the selected Filesystem. | `ti fs list-layers --output text` | +| `describe-layer` | Reads one layer by ID. | `ti fs describe-layer --layer-id ""` | +| `diff-layer` | Lists changes recorded in one layer. | `ti fs diff-layer --layer-id ""` | +| `create-layer-checkpoint` | Records a named checkpoint for a layer. | `ti fs create-layer-checkpoint --layer-id "" --checkpoint-id before-review` | +| `rollback-layer` | Restores a layer to its rollback state without committing it to the base. | `ti fs rollback-layer --layer-id ""` | +| `commit-layer` | Applies a layer's changes to the base Filesystem. | `ti fs commit-layer --layer-id ""` | +| `pack-file-system` | Stores selected local overlay state in a remote archive. | `ti fs pack-file-system --mount-path /path/to/workspace` | +| `unpack-file-system` | Restores local overlay state from a remote archive. | `ti fs unpack-file-system --mount-path /path/to/workspace` | + +### Mount commands + +| Command | Purpose and key inputs | Example | +| --- | --- | --- | +| `mount-file-system` | Mounts a resource through automatic, FUSE, or WebDAV mode. Requires `--mount-path`; select the resource with a flag or environment variable. | `ti fs mount-file-system --file-system-id --mount-path /path/to/workspace` | +| `drain-file-system` | Flushes pending FUSE work while leaving the mount online. | `ti fs drain-file-system --mount-path /path/to/workspace --timeout 30s` | +| `unmount-file-system` | Gracefully flushes and unmounts a background FUSE or WebDAV mount. | `ti fs unmount-file-system --mount-path /path/to/workspace` | + +## Prerequisites + +- Run `ti configure` before provisioning, listing, describing, or deleting Filesystems. +- Install `ti` with the release installer so the `ti-drive9` companion is next to the `ti` binary. +- Install `jq` to run the JSON extraction examples as written, or use an equivalent JSON processor. +- Treat the returned FS owner token as a secret. + +Data-plane commands can instead use an existing Filesystem with only `TI_FS_TOKEN` and `TI_REGION_CODE`, without TiDB Cloud API keys. `TI_FS_FILE_SYSTEM_ID` is an optional assertion. + +## Manage Filesystem resources + +Create a resource, wait until data-plane access is ready, and save the server-assigned ID and one-time owner token without making the file world-readable: + +```bash +umask 077 +ti fs create-file-system --wait > ./filesystem.json +export TI_FS_FILE_SYSTEM_ID="$(jq -r '.file_system_id' ./filesystem.json)" +export TI_FS_TOKEN="$(jq -r '.fs_token' ./filesystem.json)" +``` + +Without `--wait`, `ti` returns after Drive9 accepts provisioning. With the flag, `ti` waits up to 10 minutes until the root is readable through the public Drive9 data-plane CLI. A failed wait leaves the resource and locally stored credential intact. + +The JSON response includes `fs_token` exactly once. Store it in a secret manager, then delete `filesystem.json`. A configured machine can use the locally stored credential by ID without exporting the token. + +List remote resources in the effective region and describe one by ID: + +```bash +ti fs list-file-systems +ti fs describe-file-system --file-system-id +``` + +Select a resource for subsequent commands in the current shell: + +```bash +export TI_FS_FILE_SYSTEM_ID="" +``` + +Check the selected resource and companion: + +```bash +ti fs check-file-system --file-system-id +``` + +Delete a resource only after removing data you need: + +```bash +ti fs delete-file-system \ + --file-system-id +``` + +Create and delete support `--dry-run`. Deletion requires TiDB Cloud API keys and an ID, but not a local FS token. Drive9 deletion is asynchronous, so a successfully accepted request reports `status: "deleting"` while `ti` removes only a matching ID-keyed local credential. + +## Manage Filesystem tokens + +One Filesystem can have multiple owner or scoped tokens. The remote service is authoritative for token inventory and lifecycle state. Each local profile stores only one selected operational token per Filesystem; it does not mirror every remote token. + +Generate an additional owner token for CI and save its one-time plaintext response securely: + +```bash +umask 077 +ti fs generate-file-system-token \ + --file-system-id "" \ + --token-name ci-deploy \ + --ttl 24h > ./ci-token.json +``` + +Generation does not change local selection by default. Add `--store-locally` to select the generated token. If another local token exists, `--replace` is also required. Replacing local selection does not disable or revoke the old remote token. + +List token metadata and use the immutable token ID for state changes: + +```bash +ti fs list-file-system-tokens --file-system-id "" --output text +ti fs disable-file-system-token --file-system-id "" --token-id "" +ti fs enable-file-system-token --file-system-id "" --token-id "" +ti fs delete-file-system-token --file-system-id "" --token-id "" +``` + +Token names are not unique. List output never contains token plaintext, and revoked tokens do not appear. Authentication changes can take approximately 10 seconds to converge. + +Refresh a selected local token atomically: + +```bash +ti fs refresh-file-system-token --file-system-id "" +``` + +To refresh a token held by an external secret manager, supply `TI_FS_TOKEN` and `TI_REGION_CODE`. The command returns the replacement plaintext but cannot update the external store. Refresh is non-idempotent: when the request might have committed but the response was lost, do not retry with the old token. Generate another owner token with TiDB Cloud credentials instead. + +Before refreshing, disabling, or deleting a token used by a known local mount, drain and unmount it: + +```bash +ti fs drain-file-system --mount-path /path/to/workspace +ti fs unmount-file-system --mount-path /path/to/workspace +``` + +Older credentials created or imported before token lifecycle metadata was available can continue to access data, but `ti` cannot correlate them with a remote token row. It never guesses a token ID from name, timestamp, or list order. + +## Select one of multiple Filesystems + +One profile can own multiple resources. Selection precedence is: + +1. `--file-system-id`; +2. `TI_FS_FILE_SYSTEM_ID`; +3. the ID embedded in an explicitly supplied FS token; +4. otherwise fail with `fs.missing_file_system_id`. + +`ti` does not infer a resource from local credential count, even when only one credential exists. This makes scripts deterministic when resources are added or removed. + +## Copy and read data + +Upload, download, and copy remotely: + +```bash +ti fs copy-file --from-local ./README.md --to-remote /workspace/README.md +ti fs copy-file --from-remote /workspace/README.md --to-local ./README.copy.md --create-parents +ti fs copy-file --from-remote /workspace/README.md --to-remote /archive/README.md +``` + +Use `--overwrite` to replace an existing target, `--resume` for a supported interrupted upload or download, and `--recursive` for directories: + +```bash +ti fs copy-file --from-local ./src --to-remote /workspace/src --recursive +ti fs copy-file --from-local ./large.bin --to-remote /workspace/large.bin --resume +``` + +Append and stream: + +```bash +ti fs copy-file --from-local ./tail.log --to-remote /logs/app.log --append +printf 'hello\n' | ti fs copy-file --from-stdin --to-remote /workspace/stdin.txt +ti fs copy-file --from-remote /workspace/stdin.txt --to-stdout +``` + +Add metadata during upload: + +```bash +ti 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 +ti fs read-file --path /workspace/report.md +ti fs read-file --path /workspace/large.bin --offset 1024 --length 4096 +``` + +## Inspect and modify the namespace + +```bash +ti fs list-files --path /workspace +ti fs describe-file --path /workspace/report.md +ti fs create-directory --path /workspace/archive --mode 0755 +ti fs move-file --from-remote /workspace/report.md --to-remote /workspace/archive/report.md +ti fs chmod-file --path /workspace/archive/report.md --mode 0600 +ti fs create-symlink --target archive/report.md --link-path /workspace/report.link +ti fs create-hardlink --source-path /workspace/archive/report.md --link-path /workspace/report.hard +ti fs delete-file --path /workspace/report.link +ti fs delete-file --path /workspace/archive --recursive +``` + +Mutating namespace commands support `--dry-run`. + +Search content and metadata: + +```bash +ti fs search-file-content --path /workspace --pattern "TODO" --limit 50 +ti fs find-files --path /workspace --file-name-pattern "*.md" --tag stage=review +``` + +`find-files` also supports resource type, time, size, and result-limit filters. Both search commands accept `--layer-id`. + +## Use layers and checkpoints + +A layer records changes over a base root before you commit or discard them: + +```bash +ti fs create-layer \ + --base-root-path /workspace \ + --layer-name agent-task \ + --durability-mode restore-safe \ + --tag task=review +``` + +Use the returned layer ID: + +```bash +ti fs copy-file \ + --from-local ./proposal.md \ + --to-remote /workspace/proposal.md \ + --layer-id "" + +ti fs list-layers +ti fs describe-layer --layer-id "" +ti fs diff-layer --layer-id "" +ti fs create-layer-checkpoint \ + --layer-id "" \ + --checkpoint-id before-review \ + --label "before review" +``` + +Finish the layer by rolling it back or committing it: + +```bash +ti fs rollback-layer --layer-id "" +ti fs commit-layer --layer-id "" +``` + +These two commands represent alternative outcomes for the same work; do not run both in sequence in a real workflow. + +## 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 +ti fs pack-file-system --mount-path /path/to/workspace +ti fs unpack-file-system --mount-path /path/to/workspace +``` + +Without an active mount, provide `--local-root`, `--remote-root`, and `--mount-profile`. `--archive-path` selects the remote archive, repeatable `--path` limits pack contents, and `--no-replace` makes unpack merge rather than replace manifest paths. + +## Mount a Filesystem + +Create the local mount path and mount in the background: + +```bash +mkdir -p /path/to/workspace +ti fs mount-file-system \ + --file-system-id \ + --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 does not enable mounts by itself. The Docker host must provide `/dev/fuse`, and the container must receive permission to perform the mount. The following Dockerfile installs the required Ubuntu package and `ti` without storing any cloud or Filesystem credentials in the image: + +```dockerfile +FROM ubuntu:24.04 + +ARG TI_VERSION=latest + +RUN apt-get update \ + && apt-get install -y --no-install-recommends ca-certificates curl fuse3 \ + && rm -rf /var/lib/apt/lists/* + +RUN curl -fsSL https://github.com/tidbcloud/ti/releases/latest/download/install.sh \ + | sh -s -- --yes --version "${TI_VERSION}" + +ENV PATH="/root/.ti/bin:${PATH}" + +RUN mkdir -p /workspace + +CMD ["bash"] +``` + +Build the image, then pass the Filesystem owner token and canonical region code at runtime: + +```bash +docker build -t ti-fuse . + +docker run --rm -it \ + --device /dev/fuse \ + --cap-add SYS_ADMIN \ + --security-opt apparmor=unconfined \ + --env TI_FS_TOKEN \ + --env TI_REGION_CODE \ + ti-fuse +``` + +The two environment variables must already exist in the host shell. Inside the container, mount and use the Filesystem normally: + +```bash +ti fs mount --mount-path /workspace +printf 'hello from Docker\n' > /workspace/hello.txt +ti fs umount --mount-path /workspace +``` + +Use the equivalent runtime settings in `compose.yaml`: + +```yaml +services: + agent: + build: + context: . + args: + TI_VERSION: latest + devices: + - /dev/fuse:/dev/fuse + cap_add: + - SYS_ADMIN + security_opt: + - apparmor=unconfined + environment: + TI_FS_TOKEN: ${TI_FS_TOKEN} + TI_REGION_CODE: ${TI_REGION_CODE} + TI_FS_FILE_SYSTEM_ID: ${TI_FS_FILE_SYSTEM_ID} + 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 `ti fs` data-plane commands without a mount when FUSE cannot be granted. The mount exists in the container mount namespace and disappears when the container stops, so wait for graceful unmount to succeed before stopping a container that might have pending writes. + +macOS intentionally keeps WebDAV as the automatic choice even when macFUSE is installed. To use FUSE, install a supported release from the [official macFUSE site](https://macfuse.github.io/), complete any approval or restart requested by its installer, and run: + +```bash +ti fs mount-file-system \ + --file-system-id \ + --mount-path /path/to/workspace \ + --driver fuse +``` + +Explicit FUSE supports cache controls: + +```bash +ti fs mount-file-system \ + --file-system-id \ + --mount-path /path/to/workspace \ + --driver fuse \ + --cache-dir "$HOME/.ti/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" +ti fs mount-file-system \ + --file-system-id \ + --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 +ti fs mount-file-system \ + --file-system-id \ + --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 +ti fs unmount-file-system \ + --mount-path /path/to/workspace +``` + +Use drain when you need an explicit durability barrier while keeping a FUSE mount online, for example before handing the mount to another process or checking remote visibility: + +```bash +ti fs drain-file-system \ + --mount-path /path/to/workspace \ + --timeout 30s +``` + +Drain flushes dirty handles and waits for pending writes, but the mount remains available and can accept new writes afterward. It is not supported for WebDAV. `unmount-file-system` also supports `--timeout`, `--force`, `--ignore-absent`, `--pack-archive-path`, and `--no-auto-pack`. + +A successful background mount writes a non-secret locator under `~/.ti/mounts/`. Drain and unmount can use that locator from the same `HOME` without `TI_FS_TOKEN` or `TI_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 | +| --- | --- | +| `ti fs cp` | `ti fs copy-file` | +| `ti fs cat` | `ti fs read-file` | +| `ti fs ls` | `ti fs list-files` | +| `ti fs stat` | `ti fs describe-file` | +| `ti fs mv` | `ti fs move-file` | +| `ti fs rm` | `ti fs delete-file` | +| `ti fs mkdir` | `ti fs create-directory` | +| `ti fs chmod` | `ti fs chmod-file` | +| `ti fs symlink` | `ti fs create-symlink` | +| `ti fs hardlink` | `ti fs create-hardlink` | +| `ti fs grep` | `ti fs search-file-content` | +| `ti fs find` | `ti fs find-files` | +| `ti fs mount` | `ti fs mount-file-system` | +| `ti fs drain` | `ti fs drain-file-system` | +| `ti fs umount` | `ti fs unmount-file-system` | + +## What's next + +- [Use a Filesystem in an Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) +- [Share a Filesystem Across Machines](/ai/ti/reference/ti-share-filesystem-across-machines-example.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/ti/reference/ti-git-workspace-for-agents-example.md b/ai/ti/reference/ti-git-workspace-for-agents-example.md new file mode 100644 index 0000000000000..9b10bd8d6e891 --- /dev/null +++ b/ai/ti/reference/ti-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:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## The agent problem + +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. + +## Limitations of a normal clone or partial clone + +A normal clone blocks until the initial object transfer and checkout finish. A native blobless partial clone reduces the first transfer, but later Git commands and file reads can still trigger repeated on-demand fetches on the agent's critical path. Neither approach by itself provides a shared Filesystem workspace that can be restored across agent runtimes. + +## How TiDB Cloud CLI changes the workflow + +`ti fs-git clone-git-workspace --blobless --hydrate background` registers the Git workspace and exposes its file tree before all clean blobs finish downloading. The command returns so the agent can inspect paths and start working while `ti` hydrates the clean tree and local Git object database in the background. Reads that arrive before hydration completes fall back to Git's lazy fetch for correctness. Ordinary Git remains responsible for edits, commits, fetches, and pushes. + +## Prerequisites + +- 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 +ti fs mount-file-system \ + --mount-path /path/to/workspace \ + --driver fuse +``` + +## Step 2. Create the workspace and hydrate in the background + +```bash +ti 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 +ti fs-git hydrate-git-workspace \ + --target-path /path/to/workspace/tidb \ + --timeout 30m +``` + +## Step 3. Create an agent worktree + +```bash +ti 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 +ti fs-git remove-git-worktree \ + --worktree-path /path/to/workspace/tidb-agent-task + +ti fs unmount-file-system --mount-path /path/to/workspace +``` + +Use `--force` for worktree removal only when uncommitted changes can be discarded. Filesystem unmount performs a graceful drain automatically; use `ti fs drain-file-system` separately only when you need to flush remote work without unmounting. + +## Security and durability notes + +- Repository credentials are managed by Git, not `ti`. +- The coding-agent profile keeps `.git` and ignored generated files locally for performance. +- Preserve or pack local overlay state before deleting an ephemeral machine when it cannot be rebuilt. + +## What's next + +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/ti-install-configure-update.md b/ai/ti/reference/ti-install-configure-update.md new file mode 100644 index 0000000000000..a3ffa6e8fadac --- /dev/null +++ b/ai/ti/reference/ti-install-configure-update.md @@ -0,0 +1,190 @@ +--- +title: Install, Configure, and Update TiDB Cloud CLI +summary: Install TiDB Cloud CLI releases, configure profiles, check versions, apply updates, and uninstall the CLI. +--- + +# Install, Configure, and Update TiDB Cloud CLI + +This reference documents the supported release installers, top-level configuration and update commands, help and version behavior, and uninstallation. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Command tree + +```text +ti +├── configure +└── update +``` + +| Command | Required inputs | Main optional inputs | Example | +| --- | --- | --- | --- | +| `ti configure` | Interactive input, or region and TiDB Cloud API keys in non-interactive mode | `--profile`, `--non-interactive`, `--region-code`, key flags | `ti configure --profile staging` | +| `ti update` | None | `--check`, `--fail-if-update-available`, `--dry-run`, `--target-version` | `ti update --check` | + +Run `ti configure help` or `ti update help` for the complete generated flag list. + +## Install TiDB Cloud CLI + +### macOS and Linux + +Run the installer: + +```bash +curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh -s -- --yes +``` + +After installation, add `ti` to the current shell and verify it: + +```bash +export PATH="$HOME/.ti/bin:$PATH" +ti --version +``` + +The installer places `ti` and its `ti-drive9` companion in `~/.ti/bin`. Add the `PATH` export to your shell profile. The installer does not require `sudo` and does not write credentials. + +After installation, the installer displays the anonymous telemetry fields, prohibited data, persistent opt-out path, and process-scoped `TI_TELEMETRY=off` override. It does not prompt for a telemetry choice or create the optional preferences file. + +### Windows + +Run the installer: + +```powershell +$script = "$env:TEMP\install-ti.ps1" +iwr https://github.com/tidbcloud/ti-cli/releases/latest/download/install.ps1 -OutFile $script +powershell -ExecutionPolicy Bypass -File $script -Yes +``` + +After installation, add `ti` to the current PowerShell session and verify it: + +```powershell +$env:Path = "$HOME\.ti\bin;$env:Path" +ti --version +``` + +Add `$HOME\.ti\bin` to your user `PATH` to keep `ti` available in new PowerShell sessions. + +The Windows installer displays the same anonymous telemetry and opt-out notice without creating a preference or installation identity. + +## Configure a profile + +Interactive configuration is the only TiDB Cloud CLI workflow that prompts: + +```bash +ti configure +``` + +The TiDB Cloud CLI requests a TiDB Cloud API public key, private key, and canonical region code, validates those values locally, and stores the selected profile. Configuration makes no network request. The first remote command reports authentication or authorization errors for the permission it requires. + +Configure a named profile: + +```bash +ti configure --profile staging +``` + +For CI or another non-interactive environment, prefer environment variables: + +```bash +TIDB_CLOUD_PUBLIC_KEY="" \ +TIDB_CLOUD_PRIVATE_KEY="" \ +TI_REGION_CODE="aws-us-east-1" \ +ti configure --profile ci --non-interactive +``` + +You can also provide `--tidb-cloud-public-key`, `--tidb-cloud-private-key`, and `--region-code`, but secret flags can remain in shell history or process listings. + +Configuration precedence is command flag, environment variable, then saved profile. The global `--region` overrides only the placement for the current command: + +```bash +ti db list-db-clusters --db-cluster-type starter --profile staging --region aws-us-west-2 +``` + +## Get help and version information + +All command levels support `help`, `--help`, and `--version`: + +```bash +ti help +ti fs help +ti db create-db-cluster help +ti --version +ti fs --version +``` + +Required flags appear before optional flags in generated usage. The TiDB Cloud CLI supports long flags only. + +## Update TiDB Cloud CLI + +Check without changing files: + +```bash +ti update --check +``` + +In automation, fail when an update exists: + +```bash +ti update --check --fail-if-update-available +``` + +Preview and apply an update: + +```bash +ti update --dry-run +ti update +``` + +Install a specific TiDB Cloud CLI release: + +```bash +ti update --target-version v0.1.2 +``` + +The update command replaces both binaries in the user-owned install directory. An active Filesystem mount keeps running the already loaded companion process. To avoid mixing the old mount runtime with new CLI commands, stop writers and unmount before updating. Graceful unmount automatically flushes and drains pending FUSE work: + +```bash +ti fs unmount-file-system --mount-path /path/to/workspace +ti update +``` + +For WebDAV, close writers and unmount. Use the FUSE-only drain command separately only when you need a durability barrier without unmounting. Installations in protected or package-manager-owned locations are not modified. Run the installer once to migrate an older `/usr/local/bin` installation to `~/.ti/bin`. + +## Migrate from tdc v0.1.x + +The `ti` installer and the first non-update `ti` command migrate supported local state from `~/.tdc/` to `~/.ti/` when `~/.tdc/` exists and `~/.ti/` does not. The migration includes profiles, TiDB Cloud API credentials, global preferences, the telemetry installation identity, DB SQL credentials, and Filesystem registrations and credentials. It preserves `~/.tdc/` as a rollback copy and does not copy binaries, logs, caches, local overlays, mount locators, or companion runtime state. A hidden owner-only marker under `~/.ti/` records that the old and new directories coexist because migration completed successfully. + +Before installing `ti`, unmount active tdc Filesystem and Vault mounts. The migration refuses to proceed while an old mount is active because copying runtime state cannot transfer a live FUSE or WebDAV process safely. + +If both directories were created independently, or the migration marker is absent, invalid, or points to a different source, `ti` stops without merging or overwriting either directory. Move or remove the directory that is not your intended source of truth, and then run the command again. Do not combine credential or Filesystem registry directories manually. + +During the v0.2.x transition, `ti` accepts legacy `TDC_*` environment variables only when the corresponding canonical variable is absent. If both forms are set to different values, the command fails before changing local or remote state. New automation should use `TI_*` and `TIDB_CLOUD_*` variables. Legacy environment variable support is removed in v0.3.0. + +## Uninstall TiDB Cloud CLI + +Remove only the binaries: + +```bash +rm -f "$HOME/.ti/bin/ti" "$HOME/.ti/bin/ti-drive9" +``` + +On Windows: + +```powershell +Remove-Item "$HOME\.ti\bin\ti.exe", "$HOME\.ti\bin\ti-drive9.exe" +``` + +Removing binaries preserves profiles, credentials, Filesystem registrations, DB SQL credentials, logs, and mount locators. Remove `~/.ti/` only when you intend to delete all local TiDB Cloud CLI state: + +```bash +rm -rf "$HOME/.ti" +``` + +Deleting local state does not delete remote Starter clusters or Filesystem resources. + +## What's next + +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/ti-journal-agent-workflow-example.md b/ai/ti/reference/ti-journal-agent-workflow-example.md new file mode 100644 index 0000000000000..0bf91750e457e --- /dev/null +++ b/ai/ti/reference/ti-journal-agent-workflow-example.md @@ -0,0 +1,96 @@ +--- +title: Record an Agent Workflow in a TiDB Cloud Filesystem Journal +summary: Create a journal, append structured agent events, search the workflow, and verify the journal hash chain. +--- + +# Record an Agent Workflow in a TiDB Cloud Filesystem Journal + +This example records an agent task as a structured, ordered, and verifiable event history. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## The agent problem + +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. + +## Limitations of appending to a normal file + +A text file can be edited or truncated after an event is written, has no intrinsic sequence or hash chain, and requires every producer to invent parsing and concurrency rules. Retrying an append can also create duplicate events unless the application builds its own idempotency layer. + +## How TiDB Cloud CLI changes the workflow + +A Filesystem journal stores structured append-only entries with sequence information, searchable fields, optional idempotency keys, and hash-chain verification. Agents append semantic events such as `task.started` and `test.finished`; operators can query the workflow and verify the stored chain without treating a mutable log file as evidence. + +## Prerequisites + +Select a Filesystem through a configured profile or FS token environment. + +## Step 1. Create the journal + +```bash +ti 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 +ti fs-journal append-journal-entries \ + --journal-id jrn-agent-demo \ + --idempotency-key dependency-update-start \ + --entry-json '{"type":"task.started","status":"running"}' + +ti fs-journal append-journal-entries \ + --journal-id jrn-agent-demo \ + --entry-json '{"type":"test.finished","status":"passed","suite":"unit"}' \ + --entry-json '{"type":"task.finished","status":"completed"}' +``` + +## Step 3. Read and search + +```bash +ti fs-journal read-journal-entries \ + --journal-id jrn-agent-demo \ + --after-seq 0 \ + --limit 100 \ + --output text + +ti 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 +ti 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 public `ti` command surface. Use a synthetic journal ID and retain it as workflow evidence. Delete the containing Filesystem only when its complete contents are no longer needed. + +## Security notes + +- 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 + +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) +- [Delegate Secrets to an Agent](/ai/ti/reference/ti-vault-agent-secrets-example.md) diff --git a/ai/ti/reference/ti-parallel-agent-dataset-example.md b/ai/ti/reference/ti-parallel-agent-dataset-example.md new file mode 100644 index 0000000000000..06f3d7ed429b1 --- /dev/null +++ b/ai/ti/reference/ti-parallel-agent-dataset-example.md @@ -0,0 +1,80 @@ +--- +title: Share a Read-Only Dataset Across Parallel Agents with TiDB Cloud Filesystem +summary: Upload one unstructured dataset and expose the same read-only mounted namespace to multiple agent workers. +--- + +# Share a Read-Only Dataset Across Parallel Agents with TiDB Cloud Filesystem + +This scenario gives multiple short-lived workers one shared corpus without copying it into every sandbox. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — 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 TiDB Cloud CLI changes the workflow + +An owner uploads the corpus once. Every worker selects the same Filesystem and mounts it read-only, so ordinary tools can traverse a common namespace. Workers write results to separate task paths or a different output Filesystem. + +## Step 1. Upload the corpus + +On a trusted machine: + +```bash +umask 077 +ti fs create-file-system --wait > ./filesystem.json +export TI_FS_FILE_SYSTEM_ID="$(jq -r '.file_system_id' ./filesystem.json)" +export TI_FS_TOKEN="$(jq -r '.fs_token' ./filesystem.json)" + +ti fs copy-file \ + --from-local ./corpus \ + --to-remote /datasets/corpus \ + --recursive + +ti fs find-files \ + --path /datasets/corpus \ + --file-name-pattern "*.pdf" \ + --output text +``` + +Transfer the FS token and canonical region code through a secret manager. Delete `filesystem.json` after storing the token securely. + +## Step 2. Mount in each worker + +Inject `TI_FS_TOKEN` and `TI_REGION_CODE` into each worker, then run: + +```bash +mkdir -p "$HOME/corpus" +ti fs mount-file-system \ + --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 +ti fs unmount-file-system --mount-path "$HOME/corpus" +``` + +## Operational notes + +- `--read-only` prevents writes through that mount. The underlying FS owner token remains an owner credential and is not a read-only security token. +- Do not let workers use direct mutating `ti fs` commands when the workflow requires read-only behavior. +- Partition result paths by agent or run ID if workers write to the same output Filesystem. +- On platforms where FUSE or WebDAV mounting is unavailable, use `read-file`, `find-files`, and `copy-file --to-local` directly. + +## Related reference + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [Use a Filesystem in an Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/ti/reference/ti-persistent-agent-state-example.md b/ai/ti/reference/ti-persistent-agent-state-example.md new file mode 100644 index 0000000000000..7029871be2189 --- /dev/null +++ b/ai/ti/reference/ti-persistent-agent-state-example.md @@ -0,0 +1,82 @@ +--- +title: Persist Agent State Across Disposable Sandboxes with TiDB Cloud Filesystem +summary: Preserve plans, checkpoints, outputs, and workflow history in a TiDB Cloud Filesystem while replacing agent sandboxes. +--- + +# Persist Agent State Across Disposable Sandboxes with TiDB Cloud Filesystem + +This scenario keeps an agent's durable state in TiDB Cloud Filesystem while its compute environment remains disposable. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — 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 TiDB Cloud CLI changes the workflow + +A trusted machine provisions one Filesystem. Each sandbox receives only the Filesystem token and region code. The token identifies the Filesystem, so the agent can write durable task state to the remote namespace and record workflow transitions in a journal without receiving TiDB Cloud control-plane keys. + +## Step 1. Provision the state Filesystem + +On a trusted machine: + +```bash +export TI_FS_TOKEN="$(ti fs create-file-system \ + --wait \ + --query fs_token \ + --output text)" +``` + +Store `TI_FS_TOKEN` in a secret manager. Also record the configured canonical region code. The token contains the server-assigned Filesystem ID. + +## Step 2. Start the first sandbox + +Inject the following environment variables: + +```bash +export TI_FS_TOKEN="" +export TI_REGION_CODE="aws-us-east-1" +``` + +Write a plan and create a workflow journal: + +```bash +printf '%s\n' '# Plan' '1. inspect' '2. change' '3. verify' \ + | ti fs copy-file --from-stdin --to-remote /tasks/task-42/plan.md + +ti fs-journal create-journal \ + --journal-id task-42 \ + --journal-kind agent \ + --title "task 42" \ + --actor agent:worker-1 + +ti 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 two FS variables into the new sandbox, then restore the durable state: + +```bash +ti fs read-file --path /tasks/task-42/plan.md +ti fs-journal read-journal-entries --journal-id task-42 --after-seq 0 +``` + +Continue writing results under the same task path. Use a unique task ID so parallel agents do not overwrite each other's files. + +## 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 + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/ti/reference/ti-query-sql-with-roles-example.md b/ai/ti/reference/ti-query-sql-with-roles-example.md new file mode 100644 index 0000000000000..fd8cccf3d2d5b --- /dev/null +++ b/ai/ti/reference/ti-query-sql-with-roles-example.md @@ -0,0 +1,115 @@ +--- +title: Query TiDB Cloud Starter with Explicit SQL Roles +summary: Prepare TiDB Cloud CLI-managed SQL users and run read-only, read-write, and admin statements with explicit privilege intent. +--- + +# Query TiDB Cloud Starter with Explicit SQL Roles + +This example lets an agent perform schema, data, and verification work while making the required privilege level explicit for every statement. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## The agent problem + +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. + +## Limitations of one native database connection + +TiDB supports SQL privileges, but a conventional client session uses the privileges of the one credential used to connect. Users must create, store, and switch among credentials themselves, and an agent can silently keep using an overly privileged connection across task phases. + +## How TiDB Cloud CLI changes the workflow + +`ti db create-db-sql-users` creates stable read-only, read-write, and admin identities and stores their credentials locally. Each `execute-sql-statement` invocation selects one role explicitly, uses the corresponding credential, and executes one statement. The agent can therefore use admin for schema changes, read-write for data changes, and read-only for verification without handling passwords directly. + +## Prerequisites + +- Configure `ti`. +- Select an active Starter cluster ID. + +## Step 1. Prepare users + +```bash +ti 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 +ti db execute-sql-statement \ + --db-cluster-id "" \ + --admin \ + --sql "CREATE DATABASE IF NOT EXISTS role_demo" + +ti 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 +ti 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 +ti 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 +ti 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 +ti 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. +- `ti` accepts one SQL statement per invocation. +- HTTPS is the default transport; `--transport mysql` is an explicit fallback. +- Connection strings and environment output contain credentials. + +## What's next + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/ti/reference/ti-regions-security-and-limitations.md b/ai/ti/reference/ti-regions-security-and-limitations.md new file mode 100644 index 0000000000000..2c06d2e967493 --- /dev/null +++ b/ai/ti/reference/ti-regions-security-and-limitations.md @@ -0,0 +1,109 @@ +--- +title: TiDB Cloud CLI Regions, Security, and Limitations +summary: Reference supported regions, authentication boundaries, platform dependencies, preview constraints, and Filesystem companion behavior. +--- + +# TiDB Cloud CLI Regions, Security, and Limitations + +This reference describes current placement, authentication, platform, and preview boundaries. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## TiDB Cloud regions + +The TiDB Cloud CLI 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 the Singapore region in the TiDB Cloud CLI. 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 | +| --- | --- | +| `ti configure`, all `ti db` control-plane operations | TiDB Cloud API public/private key | +| `ti fs create-file-system` | TiDB Cloud API key | +| `ti fs delete-file-system` | TiDB Cloud API key and file system ID | +| Generate, list, enable, disable, or delete Filesystem tokens | TiDB Cloud API key and explicit file system ID | +| Refresh a Filesystem token | The current FS bearer token only | +| Remote file, layer, pack, mount, Git, journal, and owner vault operations | FS owner token or registered resource credential | +| Delegated vault read, list, run, or mount | Scope-appropriate delegated vault token | +| Drain and unmount after a successful background mount | Non-secret mount locator in the same `HOME` | + +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 access required for the workflow. Do not reuse a personal administrator key in unattended automation. +- Inject automation credentials from a CI secret store or runtime secret manager. Do not place credentials in source control, container images, shell scripts, or command-line arguments that can appear in process listings and shell history. +- Do not copy the complete `~/.ti/` directory into an agent sandbox. For an existing Filesystem, pass only `TI_FS_TOKEN` and `TI_REGION_CODE`; use `TI_FS_FILE_SYSTEM_ID` only as an optional assertion. +- Treat an FS owner token as full access to that Filesystem. When an agent needs only selected secrets, create a vault grant with the narrowest field scope and shortest practical TTL, and pass the delegated vault token instead. +- Use a separate Filesystem token for each machine, CI workflow, or sandbox class so that one environment can be disabled or revoked without interrupting others. Token names are operational labels, not unique identifiers; mutate tokens only by `token_id`. +- Capture generated and refreshed token plaintext immediately because it is returned only once. A token refreshed from `TI_FS_TOKEN` is not written back to an external secret manager. Refresh is non-idempotent, so do not retry after an ambiguous network failure. +- For shared-token rotation, generate and distribute a replacement, validate access, then disable and delete the old token. Allow approximately 10 seconds for authentication caches to converge after a state change. +- Use `--read-only` for SQL inspection by untrusted or exploratory agents. Use `--admin` only for DDL or privilege management, and use `--read-write` only when data changes are intended. +- Use `--dry-run` before destructive control-plane operations. Keep `~/.ti/credentials`, resource credentials, and DB SQL credentials owner-readable only. +- Grant Docker access to `/dev/fuse`, `SYS_ADMIN`, and an unconfined AppArmor profile only to dedicated, trusted containers. These settings reduce container isolation. +- Review local operation logs before sharing diagnostics. The logs exclude SQL text, paths, payloads, and credential values, but command names, flag names, profile and region metadata, status codes, and operational timing can still be sensitive. + +## Mount platform limitations + +| 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. The TiDB Cloud CLI does not fall back to a separate native mount implementation. + +Ubuntu 26.04 additionally confines `fusermount3` with AppArmor. Use a mount path under `$HOME` or `/mnt`; `/workspace` requires an explicit local AppArmor rule even when `ti` 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 the TiDB Cloud CLI. +- Remote-committed Filesystem data survives client or sandbox deletion; deleting the machine does not delete the remote resource. + +## Product limitations + +- The TiDB Cloud CLI is in preview, and command contracts can change. +- Database management targets TiDB Cloud Starter, not every TiDB Cloud cluster tier. +- SQL execution accepts one statement per invocation. +- Read-write is the default SQL role; use explicit role flags in security-sensitive automation. +- Journals are append-only and the current public command surface has no journal delete command. +- Filesystem list and describe commands query the region-scoped remote inventory with TiDB Cloud credentials. They do not aggregate across regions. +- The local credential store keeps one selected token per profile and Filesystem. It does not mirror all remote tokens. Older create/import credentials without a known token ID remain usable, but cannot be correlated with remote token metadata. +- Telemetry management commands are intentionally not implemented. Control telemetry through `~/.ti/.preferences` or `TI_TELEMETRY`; serverless-function deployment, Homebrew, and Scoop distribution are not implemented. +- The TiDB Cloud CLI depends on its installed `ti-drive9` companion for all public Filesystem runtime behavior. + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) diff --git a/ai/ti/reference/ti-share-filesystem-across-machines-example.md b/ai/ti/reference/ti-share-filesystem-across-machines-example.md new file mode 100644 index 0000000000000..ced810173d5e2 --- /dev/null +++ b/ai/ti/reference/ti-share-filesystem-across-machines-example.md @@ -0,0 +1,111 @@ +--- +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:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## The agent problem + +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. + +## Limitations of native local disks and manual synchronization + +Local disks do not provide a shared namespace. Commands such as `scp` and archive upload transfer point-in-time copies rather than live state, while object storage does not by itself behave like the mounted directory expected by editors, build tools, and agents. + +## How TiDB Cloud CLI changes the workflow + +Both machines select the same TiDB Cloud Filesystem with separate owner tokens. Data-plane commands and the mounted path address one remote namespace, so a write from either interface becomes visible through the other after it is flushed. Machine B needs only its Filesystem token and region code; the token identifies the Filesystem, so it does not need TiDB Cloud API keys or a copied profile. Separate tokens let you revoke machine B without interrupting machine A. + +## Prerequisites + +- Machine A has configured `ti`. +- Both machines have `ti` installed. +- You have a secure secret-transfer channel. + +## Step 1. Create the Filesystem on machine A + +```bash +umask 077 +ti fs create-file-system --wait > ./filesystem.json +export FILE_SYSTEM_ID="$(jq -r '.file_system_id' ./filesystem.json)" +export TI_FS_TOKEN="$(jq -r '.fs_token' ./filesystem.json)" + +ti fs generate-file-system-token \ + --file-system-id "$FILE_SYSTEM_ID" \ + --token-name machine-b \ + --ttl 720h > ./machine-b-token.json + +printf 'from machine A\n' | ti fs copy-file \ + --from-stdin \ + --to-remote /shared/origin.txt +``` + +Transfer the `fs_token` from `machine-b-token.json` through a secret manager and communicate the canonical region code. Keep `FILE_SYSTEM_ID` on machine A for control-plane operations, then delete both JSON files after storing their tokens securely. + +## Step 2. Configure machine B in memory + +```bash +export TI_FS_TOKEN="" +export TI_REGION_CODE="aws-us-east-1" +``` + +No `ti configure` is required. + +## Step 3. Verify direct visibility on machine B + +```bash +ti fs read-file --path /shared/origin.txt +printf 'from machine B\n' | ti fs copy-file --from-stdin --to-remote /shared/second.txt +``` + +## Step 4. Verify mount and data-plane visibility + +```bash +mkdir -p /path/to/shared-workspace +ti fs mount-file-system \ + --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 +ti fs read-file --path /shared/mounted.txt +``` + +The first read proves data-plane writes are visible through the mount. The final read proves mount writes are visible through the data plane after they are flushed. + +## Cleanup + +Stop writers and unmount either driver. A graceful FUSE unmount automatically drains pending work: + +```bash +ti fs unmount-file-system --mount-path /path/to/shared-workspace +unset TI_FS_TOKEN TI_REGION_CODE +``` + +On machine A: + +```bash +ti fs list-file-system-tokens --file-system-id "$FILE_SYSTEM_ID" --output text +ti fs delete-file-system-token \ + --file-system-id "$FILE_SYSTEM_ID" \ + --token-id "" +ti fs delete-file-system \ + --file-system-id "$FILE_SYSTEM_ID" +``` + +## Security notes + +- Each FS token grants owner access. Transfer it as a secret, not in chat or command history, and use a separate token for each machine. +- Concurrent writers can overwrite the same paths; coordinate ownership at the workflow level. +- Do not terminate a machine before graceful unmount completes. Use an explicit drain only when you need remote durability while keeping the FUSE mount online. + +## What's next + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [Use a Filesystem in an Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) diff --git a/ai/ti/reference/ti-starter-database.md b/ai/ti/reference/ti-starter-database.md new file mode 100644 index 0000000000000..78938615800ef --- /dev/null +++ b/ai/ti/reference/ti-starter-database.md @@ -0,0 +1,229 @@ +--- +title: TiDB Cloud Starter CLI Command Reference +summary: Reference every `ti db` command for Starter clusters, branches, SQL users, connection strings, and SQL execution. +--- + +# TiDB Cloud Starter CLI Command Reference + +Use `ti db` to manage TiDB Cloud Starter clusters, branches, and SQL access. The TiDB Cloud CLI validates the cluster service plan before every cluster-scoped operation and rejects Essential or unverifiable clusters before continuing. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## Command tree + +```text +ti 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-type starter` and `--db-cluster-name`. Use `--wait` for an `ACTIVE` result. | `ti db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --wait` | +| `list-db-clusters` | Lists Starter clusters in the effective region. Requires `--db-cluster-type starter` and supports pagination, filtering, ordering, and queries. | `ti db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name}'` | +| `describe-db-cluster` | Reads one cluster by `--db-cluster-id`; `--view FULL` requests expanded fields. | `ti db describe-db-cluster --db-cluster-id "" --view FULL` | +| `update-db-cluster` | Changes the name or monthly spending limit of one cluster. Supports `--dry-run`. | `ti db update-db-cluster --db-cluster-id "" --db-cluster-name app-db-v2` | +| `delete-db-cluster` | Deletes one cluster by ID. Use `--wait` to wait until deletion is observable. | `ti db delete-db-cluster --db-cluster-id "" --wait` | +| `create-db-cluster-branch` | Creates a branch from a cluster. Requires cluster ID and branch name; supports `--wait`. | `ti db create-db-cluster-branch --db-cluster-id "" --db-cluster-branch-name dev --wait` | +| `list-db-cluster-branches` | Lists branches for one cluster with pagination. | `ti db list-db-cluster-branches --db-cluster-id "" --output text` | +| `describe-db-cluster-branch` | Reads one branch by cluster ID and branch ID. | `ti db describe-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id ""` | +| `delete-db-cluster-branch` | Deletes one branch. Supports `--dry-run`. | `ti db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id ""` | +| `create-db-sql-users` | Idempotently creates or repairs read-only, read-write, and admin users for one cluster. | `ti db create-db-sql-users --db-cluster-id ""` | +| `format-db-connection-string` | Formats stored SQL credentials as a MySQL URI, JDBC, Go, SQLAlchemy, or environment output. | `ti db format-db-connection-string --db-cluster-id "" --read-only --format env` | +| `execute-sql-statement` | Executes exactly one statement using read-write by default or an explicit SQL role. | `ti db execute-sql-statement --db-cluster-id "" --read-only --sql "SELECT 1"` | + +## Prerequisites + +- Configure `ti` with `ti configure`. +- Ensure the API key can manage Starter clusters in the selected project. +- Use synthetic names in automation so cleanup can identify only resources created by that run. + +## Manage clusters + +Preview and create a Starter cluster: + +```bash +ti db create-db-cluster \ + --db-cluster-type starter \ + --db-cluster-name demo-cluster \ + --dry-run + +ti db create-db-cluster \ + --db-cluster-type starter \ + --db-cluster-name demo-cluster +``` + +The TiDB Cloud CLI omits project selection and lets TiDB Cloud select its server-side default project. Any project metadata in the response remains visible. `--db-cluster-type starter` is required for cluster creation and listing; no type is inferred. `--monthly-spending-limit-usd-cents` is optional; setting it can require a payment method. + +List and filter clusters: + +```bash +ti db list-db-clusters --db-cluster-type starter +ti db list-db-clusters --db-cluster-type starter --page-size 20 --order-by "createTime desc" +ti db list-db-clusters --db-cluster-type starter --query 'clusters[].{id:id,name:display_name,state:state}' +ti --region aws-us-west-2 db list-db-clusters --db-cluster-type starter +``` + +The list command also accepts `--page-token` and `--filter`. It always scopes the API request to the effective region, which resolves from global `--region`, then `TI_REGION_CODE`, then the selected profile. The shared TiDB Cloud API can return multiple service plans or unverifiable resources, so the TiDB Cloud CLI scans upstream pages and incrementally fills a ti result page with verified Starter clusters in that region. Its opaque `next_page_token` binds the profile, type, region, filter, and ordering; it omits `total_size`, because the server total can include clusters outside the verified result. A user `--filter` is combined with the mandatory region filter and cannot expand the result to another region. + +Describe and update a cluster: + +```bash +ti db describe-db-cluster \ + --db-cluster-id "" \ + --view FULL + +ti 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 +ti db delete-db-cluster \ + --db-cluster-id "" \ + --dry-run + +ti db delete-db-cluster \ + --db-cluster-id "" \ + --wait +``` + +`ti` resolves the cluster name internally; no name-confirmation flag is required. Without `--wait`, delete returns after TiDB Cloud accepts the asynchronous request. The wait flag waits up to 12 minutes and returns when the cluster is `DELETED` or no longer accessible. + +## Manage branches + +Every branch command verifies that the parent cluster is Starter before calling a branch endpoint. + +Create and list branches: + +```bash +ti db create-db-cluster-branch \ + --db-cluster-id "" \ + --db-cluster-branch-name development \ + --wait + +ti 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 +ti db describe-db-cluster-branch \ + --db-cluster-id "" \ + --db-cluster-branch-id "" \ + --view FULL + +ti db delete-db-cluster-branch \ + --db-cluster-id "" \ + --db-cluster-branch-id "" +``` + +Create and delete support `--dry-run`. + +## Create SQL users + +SQL access commands verify that the target cluster is Starter before reading or writing local SQL credentials, calling SQL-user APIs, or contacting a SQL endpoint. + +Create or repair the three TiDB Cloud CLI-managed SQL roles: + +```bash +ti db create-db-sql-users \ + --db-cluster-id "" +``` + +The operation is idempotent. It reuses stable role names and stores generated credentials under `~/.ti/db_users//credentials`. It creates: + +- `read_only`; +- `read_write`; +- `admin`. + +Preview the operation without changing users: + +```bash +ti 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 +ti db format-db-connection-string \ + --db-cluster-id "" \ + --read-write \ + --database app \ + --format mysql-uri + +ti db format-db-connection-string \ + --db-cluster-id "" \ + --read-only \ + --format env \ + --env-prefix TIDB_ + +ti 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 +ti db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --database app \ + --sql "SELECT COUNT(*) AS row_count FROM messages" \ + --output text + +ti db execute-sql-statement \ + --db-cluster-id "" \ + --read-write \ + --database app \ + --sql "INSERT INTO messages(id, body) VALUES (1, 'hello')" + +ti 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/ti/reference/ti-query-sql-with-roles-example.md) +- [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) diff --git a/ai/ti/reference/ti-troubleshooting.md b/ai/ti/reference/ti-troubleshooting.md new file mode 100644 index 0000000000000..66f4d00782f69 --- /dev/null +++ b/ai/ti/reference/ti-troubleshooting.md @@ -0,0 +1,244 @@ +--- +title: Troubleshoot TiDB Cloud CLI +summary: Diagnose TiDB Cloud CLI authentication, project, Filesystem selection, companion, quota, SQL user, mount, and interrupted-cleanup failures. +--- + +# Troubleshoot TiDB Cloud CLI + +Use this reference to diagnose common current TiDB Cloud CLI failures. Add `--debug` only when needed; debug output is redacted but should still be reviewed before sharing. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## API authentication fails + +Symptoms include missing credentials, Digest authentication failure, or permission denied. + +Check that both environment values are set together: + +```bash +test -n "$TI_PUBLIC_KEY" +test -n "$TI_PRIVATE_KEY" +``` + +If you intend to use saved credentials, unset both variables and verify the profile: + +```bash +unset TI_PUBLIC_KEY TI_PRIVATE_KEY +ti db list-db-clusters --db-cluster-type starter --profile default +``` + +An API key can authenticate successfully but still lack the permission declared by a command. Use a key with the access required by that operation. `ti configure` validates and stores local values without contacting TiDB Cloud, so credential failures first appear on a remote command. + +## Filesystem token is missing + +For a clean sandbox, provide the token and region. `ti` derives the file system ID from the token: + +```bash +export TI_FS_TOKEN="" +export TI_REGION_CODE="aws-us-east-1" +ti fs check-file-system +``` + +The FS token is not the TiDB Cloud API private key. `TI_FS_FILE_SYSTEM_ID` is optional when a token is supplied; set it only when you want `ti` to verify that a separately distributed ID matches the token. + +If the token is known but is not stored on the current machine, import it and then select the derived ID: + +```bash +# Store a known token without requiring TiDB Cloud API keys. +chmod 600 ./fs-token +ti fs import-file-system-token --from-file ./fs-token --region aws-us-east-1 +ti fs list-files --file-system-id --path / +``` + +If every known token is lost or revoked, use TiDB Cloud API keys to generate another owner token: + +```bash +ti fs generate-file-system-token \ + --file-system-id "" \ + --token-name recovery \ + --ttl 24h +``` + +The new plaintext appears once in the response. Store it securely or add `--store-locally` to select it on the current machine. + +## Filesystem token is rejected + +A data-plane HTTP 401 cannot distinguish a token that was disabled, expired, refreshed on another machine, or revoked. Inspect remote metadata with TiDB Cloud API keys: + +```bash +ti fs list-file-system-tokens \ + --file-system-id "" \ + --include-expired \ + --output text +``` + +Token names are not unique. Use the immutable `token_id` from this output for enable, disable, or delete operations. Old credentials created or imported without token lifecycle metadata can remain valid, but `ti` cannot safely identify their list row and never guesses a match. + +After enable, disable, delete, or refresh, allow approximately 10 seconds for authentication caches to converge. If refresh reports `fs.token_refresh_ambiguous`, the server might have rotated the token even though the response was lost. Do not retry with the old token. Generate another owner token through TiDB Cloud credentials. + +If token mutation reports `fs.token_mount_active`, use the exact mount path in the error: + +```bash +ti fs drain-file-system --mount-path /path/to/workspace +ti fs unmount-file-system --mount-path /path/to/workspace +``` + +Then retry the token operation. A mount on another machine is not visible locally; coordinate rotation with that machine separately. + +## Filesystem selection is missing + +List remote resources in the configured region with TiDB Cloud API keys and select one explicitly: + +```bash +ti fs list-file-systems --output text +ti fs list-files --file-system-id --path / +``` + +Or select the Filesystem for subsequent commands in the current shell: + +```bash +export TI_FS_FILE_SYSTEM_ID="" +``` + +The TiDB Cloud CLI intentionally does not infer a Filesystem from local credential count, including when only one credential exists. Supply its ID or an FS token whose embedded ID can be derived. + +## Filesystem region is unsupported + +The configured TiDB Cloud region might not have a `tidb_cloud_native` Filesystem endpoint. Compare it with [current Filesystem regions](/ai/ti/reference/ti-regions-security-and-limitations.md#filesystem-regions). Change placement with a valid profile or command-scoped `--region`; do not configure a raw server URL. + +## Companion is missing or incompatible + +The release installer places `ti-drive9` next to `ti`. Re-run the current installer when the TiDB Cloud CLI reports a missing companion: + +```bash +curl -fsSL https://github.com/tidbcloud/ti/releases/latest/download/install.sh | sh -s -- --yes +``` + +Verify that `PATH` resolves the expected `ti`: + +```bash +command -v ti +ti --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 +ti db list-db-clusters --db-cluster-type starter --output text +ti fs list-file-systems --output text +``` + +Never delete an unrelated resource to make automation pass. A Starter spending limit can require configured billing. + +## SQL credentials are missing + +Prepare or repair users for the exact cluster: + +```bash +ti db create-db-sql-users --db-cluster-id "" +``` + +Then retry with an explicit role: + +```bash +ti db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --sql "SELECT 1" +``` + +Deleting `~/.ti/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 +ti 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" +ti fs mount-file-system --mount-path "$HOME/workspace" +``` + +Changing the owner or mode of `/workspace` does not bypass AppArmor. If the path cannot change, add explicit `/workspace` mount and unmount rules to `/etc/apparmor.d/local/fusermount3` as described in [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md#ubuntu-2604-mount-paths). + +## Mount becomes stale after a process crash + +If the companion is killed without graceful unmount, FUSE access can return `EIO` or `Transport endpoint is not connected`. Stop processes with open files, then try: + +```bash +ti 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 +ti fs unmount-file-system --mount-path /path/to/workspace +``` + +Unmount performs the graceful FUSE drain automatically. Running `drain-file-system` separately does not close file descriptors or resolve a busy mount; use it only when you need to flush pending work while leaving the mount online. Drain is not supported for WebDAV. + +## An interrupted command leaves resources + +List resources and identify only those created by your workflow. Use describe before delete: + +```bash +ti db describe-db-cluster --db-cluster-id "" +ti fs describe-file-system --file-system-id "" +``` + +Preview supported cleanup: + +```bash +ti db delete-db-cluster --db-cluster-id "" --dry-run +ti fs delete-file-system \ + --file-system-id "" \ + --dry-run +``` + +## Report a problem + +Include the TiDB Cloud CLI version, OS and architecture, command name, stable error code, and redacted logs. Never include API keys, FS or vault tokens, DB passwords, SQL containing private data, or file contents. Report issues at [github.com/tidbcloud/ti/issues](https://github.com/tidbcloud/ti/issues). diff --git a/ai/ti/reference/ti-vault-agent-secrets-example.md b/ai/ti/reference/ti-vault-agent-secrets-example.md new file mode 100644 index 0000000000000..00f31cf949f31 --- /dev/null +++ b/ai/ti/reference/ti-vault-agent-secrets-example.md @@ -0,0 +1,109 @@ +--- +title: Delegate TiDB Cloud Filesystem Vault Secrets to an Agent +summary: Store a secret, grant one field to an agent, inject it into a process, audit access, and revoke the grant. +--- + +# Delegate TiDB Cloud Filesystem Vault Secrets to an Agent + +This example gives an agent temporary access to one secret field without sharing the Filesystem owner token or the complete secret. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## The agent problem + +An agent might need one API endpoint or token to complete a short task. Putting the complete secret in a prompt, `.env` file, or sandbox image exposes it beyond the process and lifetime that need it. Sharing the Filesystem owner token also grants broader access than one secret field requires. + +## Limitations of ordinary environment variables and files + +Environment variables and files can deliver a secret, but they do not create a scoped, expiring delegation or an access audit trail. A separate cloud secret manager can provide those controls, but it requires another identity, policy, and integration path for every sandbox. + +## How TiDB Cloud CLI changes the workflow + +The Filesystem owner stores the secret once and creates a short-lived grant scoped to the required field. The agent receives only the delegated vault token and can inject the allowed value into a child process. The owner can inspect audit events and revoke the grant without rotating or exposing the Filesystem owner credential. + +## Prerequisites + +- Select a Filesystem with owner access. +- Store the source secret value in a protected file. + +## Step 1. Create a secret + +```bash +ti 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 TI_VAULT_TOKEN="$(ti 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 +ti fs-vault read-secret \ + --secret-name service-demo \ + --field ENDPOINT \ + --format raw +``` + +Inject the allowed fields into a command: + +```bash +ti 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 +ti fs-vault list-audit-events \ + --secret-name service-demo \ + --agent-id example-agent \ + --limit 20 + +ti fs-vault delete-grant \ + --grant-id "" \ + --revoked-by operator \ + --reason task-complete +``` + +Unset the local token: + +```bash +unset TI_VAULT_TOKEN +``` + +## Cleanup + +```bash +ti 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 + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/ti/ti-overview.md b/ai/ti/ti-overview.md new file mode 100644 index 0000000000000..ef2107e00f321 --- /dev/null +++ b/ai/ti/ti-overview.md @@ -0,0 +1,101 @@ +--- +title: TiDB Cloud Command Line Interface Overview +summary: Learn when to use the TiDB Cloud CLI to manage TiDB Cloud Starter databases and persistent Filesystems for users, automation, and AI agents. +--- + +# TiDB Cloud Command Line Interface Overview + +The TiDB Cloud Command Line Interface—`ti`—is the new CLI for managing TiDB Cloud Starter databases and TiDB Cloud Filesystem. It is designed for repeatable automation: commands are non-interactive except for configuration, structured output is JSON by default, and database and Filesystem credentials have separate security boundaries. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## When to use TiDB Cloud CLI + +Use the TiDB Cloud CLI when a workflow needs to manage TiDB Cloud from a terminal, script, CI job, or AI agent environment. Typical scenarios include: + +- **Automate Starter database lifecycle operations.** Create a cluster or branch, wait until it is ready, inspect it as JSON, and delete only the resource identified by your workflow. +- **Separate SQL privileges by task.** Give an agent read-only access for inspection, read-write access for application work, or admin access for schema and privilege management without passing database passwords in every command. +- **Keep sandbox work after the sandbox disappears.** Provision a Filesystem on a trusted machine, then pass only its token, region, and name to an ephemeral environment. +- **Share one workspace across machines and interfaces.** Read and write the same remote namespace through direct data-plane commands or a FUSE or WebDAV mount. +- **Start large Git workspaces sooner.** Expose a repository file tree while clean Git data continues hydrating in the background. +- **Record and delegate agent work.** Store append-only workflow events in journals and grant temporary, scoped access to selected vault fields. + +For a visual, interactive workflow, use the TiDB Cloud console instead. For TiDB Cloud Essential or CLI operations that the TiDB Cloud CLI does not provide, use `ticloud`. + +## TiDB Cloud CLI, ticloud, and the TiDB Cloud console + +TiDB Cloud currently has two command-line interfaces with different product scopes. `ti` is the new CLI for Starter and TiDB Cloud Filesystem. `ticloud` remains the CLI for Essential and also supports existing Starter workflows. + +| Interface | Use it for | Interaction model | +| --- | --- | --- | +| `ti` (Preview) | New TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows | Predictable commands, JSON output by default, and non-interactive operation except for `ti configure` | +| `ticloud` | TiDB Cloud Essential and operations not available in the TiDB Cloud CLI, such as import, export, and audit-log commands | Traditional CLI workflows with interactive and non-interactive modes | +| TiDB Cloud console | Visual resource inspection, guided setup, and manual operations | Browser-based and interactive | + +New Starter and Filesystem automation should use the TiDB Cloud CLI. Use `ticloud` for Essential and any command that has no TiDB Cloud CLI equivalent. The TiDB Cloud CLI replaces `ticloud` only for the Starter workflows it supports; the TiDB Cloud CLI does not replace `ticloud` for Essential. + +## What TiDB Cloud CLI manages + +The TiDB Cloud CLI covers the following functional areas: + +- Starter cluster and branch lifecycle operations; +- read-only, read-write, and admin SQL users, connection strings, and one-statement SQL execution; +- Filesystem provisioning, direct file operations, and FUSE or WebDAV mounts; +- Filesystem layers, packs, Git workspaces, journals, and vault operations; +- profiles, regional endpoint selection, local credentials, updates, structured output, and JMESPath queries. + +The `ti` executable has a two-level command model: + +```text +ti +``` + +Examples include `ti db list-db-clusters --db-cluster-type starter`, `ti fs copy-file`, and `ti fs-journal verify-journal`. The top-level `ti configure` and `ti update` commands configure and maintain the CLI. + +## TiDB Cloud CLI and Drive9 + +The TiDB Cloud CLI installs a bundled [Drive9](https://github.com/mem9-ai/drive9) companion named `ti-drive9`. The TiDB Cloud CLI owns profile selection, TiDB Cloud credentials, region and Filesystem selection, output formatting, and `ti` error behavior. The companion owns Filesystem data-plane semantics, FUSE and WebDAV mounts, layers, pack and unpack, Git workspace acceleration, journals, and vault operations. + +You do not need to install, configure, or invoke Drive9 separately for normal TiDB Cloud CLI workflows. + +## Find the right documentation + +Follow the [Quick Start](/ai/ti/ti-quick-start.md) to install the TiDB Cloud CLI and complete your first Starter or Filesystem workflow. Use these guides for task-oriented instructions: + +- [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) + +### Scenario references + +Use scenarios to follow a complete workflow that combines multiple commands and features: + +For users and automation: + +- [Run a Daily TiDB Cloud CLI Workflow](/ai/ti/reference/ti-daily-workflow-example.md) +- [Query SQL with Explicit Roles](/ai/ti/reference/ti-query-sql-with-roles-example.md) +- [Share a Filesystem Across Machines](/ai/ti/reference/ti-share-filesystem-across-machines-example.md) +- [Hand Off CI Artifacts Between Jobs](/ai/ti/reference/ti-ci-artifact-handoff-example.md) + +For AI agents: + +- [Use a Filesystem in an Agent Sandbox](/ai/ti/reference/ti-agent-sandbox-example.md) +- [Persist Agent State Across Sandboxes](/ai/ti/reference/ti-persistent-agent-state-example.md) +- [Share a Read-Only Dataset Across Parallel Agents](/ai/ti/reference/ti-parallel-agent-dataset-example.md) +- [Prepare a Git Workspace for Agents](/ai/ti/reference/ti-git-workspace-for-agents-example.md) +- [Record an Agent Workflow in a Journal](/ai/ti/reference/ti-journal-agent-workflow-example.md) +- [Delegate Secrets to an Agent](/ai/ti/reference/ti-vault-agent-secrets-example.md) + +### Reference + +- [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) + +To report a problem or suggest an improvement, create an issue in the [TiDB Cloud CLI GitHub repository](https://github.com/tidbcloud/ti-cli/issues). diff --git a/ai/ti/ti-quick-start.md b/ai/ti/ti-quick-start.md new file mode 100644 index 0000000000000..bf780b7513b8d --- /dev/null +++ b/ai/ti/ti-quick-start.md @@ -0,0 +1,153 @@ +--- +title: Get Started with TiDB Cloud CLI +summary: Install and configure the TiDB Cloud CLI, then complete a first TiDB Cloud Starter database or Filesystem operation. +--- + +# Get Started with TiDB Cloud CLI + +This quick start installs the TiDB Cloud CLI, configures one profile, and gets a successful result from either TiDB Cloud Starter or TiDB Cloud Filesystem. + +> **Note:** +> +> The TiDB Cloud Command Line Interface — `ti` — is currently in preview. Its features and command-line interface might change without prior notice. + +## When to use this quick start + +Use this quick start when you want to automate a new Starter database or create a persistent workspace for a user, script, or AI agent. It follows the TiDB Cloud CLI workflow. If you manage TiDB Cloud Essential or need an operation that the TiDB Cloud CLI does not provide, use the [`ticloud` CLI documentation](/tidb-cloud/get-started-with-cli.md). + +## Prerequisites + +Before you begin, obtain a TiDB Cloud API public key and private key from the [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys) page. + +## Step 1. Install TiDB Cloud CLI + +On macOS or Linux, run the installer: + +```bash +curl -fsSL https://github.com/tidbcloud/ti/releases/latest/download/install.sh | sh -s -- --yes +``` + +After installation, add `ti` to the current shell and verify it: + +```bash +export PATH="$HOME/.ti/bin:$PATH" +ti --version +``` + +Add `export PATH="$HOME/.ti/bin:$PATH"` to your shell profile to keep `ti` available in new terminals. + +On Windows PowerShell, run the installer: + +```powershell +$script = "$env:TEMP\install-ti.ps1" +iwr https://github.com/tidbcloud/ti/releases/latest/download/install.ps1 -OutFile $script +powershell -ExecutionPolicy Bypass -File $script -Yes +``` + +After installation, add `ti` to the current PowerShell session and verify it: + +```powershell +$env:Path = "$HOME\.ti\bin;$env:Path" +ti --version +``` + +Add `$HOME\.ti\bin` to your user `PATH` to keep `ti` available in new PowerShell sessions. + +## Step 2. Configure TiDB Cloud CLI + +Run the interactive configuration: + +```bash +ti configure +``` + +Enter your API public key, private key, and a canonical region code such as `aws-us-east-1`. + +Run a read-only command to verify the saved credentials and selected region: + +```bash +ti db list-db-clusters --db-cluster-type starter --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, wait until it is ready, and save its server-assigned ID: + +```bash +export TI_FS_FILE_SYSTEM_ID="$(ti fs create-file-system \ + --wait \ + --query file_system_id \ + --output text)" +``` + +`ti` stores the Filesystem credential locally. Write and read a file directly: + +```bash +printf 'hello from ti\n' | ti fs copy-file \ + --from-stdin \ + --to-remote /hello.txt + +ti fs read-file \ + --path /hello.txt +``` + +Expected output: + +```text +hello from ti +``` + +Clean up: + +```bash +ti fs delete-file-system \ + --file-system-id "$TI_FS_FILE_SYSTEM_ID" +unset TI_FS_FILE_SYSTEM_ID +``` + +### Option B: Query a Starter database + +Create a Starter cluster and save its ID: + +```bash +export TI_DB_CLUSTER_ID="$(ti db create-db-cluster \ + --db-cluster-type starter \ + --db-cluster-name quickstart-db \ + --wait \ + --query id \ + --output text)" +``` + +Create the SQL users and run a read-only verification query: + +```bash +ti db create-db-sql-users \ + --db-cluster-id "$TI_DB_CLUSTER_ID" + +ti db execute-sql-statement \ + --db-cluster-id "$TI_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 +ti db delete-db-cluster \ + --db-cluster-id "$TI_DB_CLUSTER_ID" \ + --wait +unset TI_DB_CLUSTER_ID +``` + +## What's next + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/tidb-cloud/cli-reference.md b/tidb-cloud/cli-reference.md index 742ddb62356e7..af87e74fdb990 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. `ti` does not replace `ticloud` for Essential. For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use the [TiDB Cloud Command Line Interface](/ai/ti/ti-overview.md). Continue to use `ticloud` for Essential and for operations that `ti` does not provide, such as import, export, and audit-log commands. + +The `ticloud` CLI is a command-line interface that lets you operate TiDB Cloud from your terminal. It manages {{{ .starter }}} and Essential instances, imports and exports data, and supports other CLI workflows. ## Before you begin diff --git a/tidb-cloud/get-started-with-cli.md b/tidb-cloud/get-started-with-cli.md index 425c141e73763..42635ff3a8417 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. `ti` does not replace `ticloud` for Essential. For new TiDB Cloud Starter automation and TiDB Cloud Filesystem workflows, use the [TiDB Cloud Command Line Interface](/ai/ti/ti-overview.md). Continue to use `ticloud` for Essential and for operations that `ti` does not provide, such as import, export, and audit-log commands. + +TiDB Cloud provides the command-line interface (CLI) [`ticloud`](https://github.com/tidbcloud/tidbcloud-cli) for you to interact with TiDB Cloud Starter and Essential from your terminal with a few lines of commands. For example, you can perform the following operations using `ticloud`: - Create, delete, and list your {{{ .starter }}} or Essential instances. - Import data to your {{{ .starter }}} or Essential instances.