diff --git a/TOC-ai.md b/TOC-ai.md index 6437c43935a39..e4a251b30ec68 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -5,45 +5,162 @@ ## QUICK START -- [Get Started via Python](/ai/quickstart-via-python.md) -- [Get Started via SQL](/ai/quickstart-via-sql.md) - -## CONCEPTS - -- [Vector Search](/ai/concepts/vector-search-overview.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) ## GUIDES -- [Connect to TiDB](/ai/guides/connect.md) -- [Working with Tables](/ai/guides/tables.md) -- Search Features - - [Vector Search](/ai/guides/vector-search.md) +- [Connect to TiDB via Python](/ai/guides/connect.md) +- Search & Retrieval + - Vector Search + - [Overview](/ai/guides/vector-search-overview.md) + - [Vector Search Guide](/ai/guides/vector-search.md) + - [Vector Search Example](/ai/guides/vector-search-with-pytidb.md) - Full-Text Search - [Full-Text Search via Python](/ai/guides/vector-search-full-text-search-python.md) - [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 - - [Auto Embedding](/ai/guides/auto-embedding.md) - - [Filtering](/ai/guides/filtering.md) + - [Full-Text Search Example](/ai/guides/fulltext-search-with-pytidb.md) + - Hybrid Search + - [Hybrid Search Guide](/ai/guides/vector-search-hybrid-search.md) + - [Hybrid Search Example](/ai/guides/hybrid-search-with-pytidb.md) + - Auto Embeddings + - [Auto Embedding Guide](/ai/guides/auto-embedding.md) + - [Auto Embedding Example](/ai/guides/auto-embedding-with-pytidb.md) + - Image Search + - [Image Search Guide](/ai/guides/image-search.md) + - [Image Search Example](/ai/guides/image-search-with-pytidb.md) - [Reranking](/ai/guides/reranking.md) +- Work with Data + - [Work with Tables](/ai/guides/tables.md) + - [Filtering](/ai/guides/filtering.md) - [Join Queries](/ai/guides/join-queries.md) - [Raw SQL Queries](/ai/guides/raw-queries.md) - [Transactions](/ai/guides/transactions.md) - -## EXAMPLES - -- [Basic CRUD Operations](/ai/examples/basic-with-pytidb.md) -- [Auto Embedding](/ai/examples/auto-embedding-with-pytidb.md) -- Search & Retrieval - - [Vector Search](/ai/examples/vector-search-with-pytidb.md) - - [Full-Text Search](/ai/examples/fulltext-search-with-pytidb.md) - - [Hybrid Search](/ai/examples/hybrid-search-with-pytidb.md) - - [Image Search](/ai/examples/image-search-with-pytidb.md) -- AI Applications - - [RAG Application](/ai/examples/rag-with-pytidb.md) - - [Conversational Memory](/ai/examples/memory-with-pytidb.md) - - [Text-to-SQL](/ai/examples/text2sql-with-pytidb.md) +- Build AI Applications + - [RAG Example](/ai/guides/rag-with-pytidb.md) + - [Conversational Memory Example](/ai/guides/memory-with-pytidb.md) + - [Text-to-SQL Example](/ai/guides/text2sql-with-pytidb.md) +- TiDB Cloud CLI + - [Overview](/ai/ti/ti-overview.md) + - [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) + - [Manage TiDB Cloud Starter Instances](/ai/ti/guides/manage-starter-instances.md) + - Manage TiDB Cloud Filesystem + - [Manage Filesystem Resources](/ai/ti/guides/manage-filesystem-resources.md) + - [Configure Filesystem AI Providers](/ai/ti/guides/configure-filesystem-ai-providers.md) + - [Manage Filesystem Tokens](/ai/ti/guides/manage-filesystem-tokens.md) + - [Work with Filesystem Data](/ai/ti/guides/work-with-filesystem-data.md) + - [Manage Filesystem Layers and Checkpoints](/ai/ti/guides/manage-filesystem-layers.md) + - [Mount a TiDB Cloud Filesystem](/ai/ti/guides/mount-filesystem.md) + - [Manage Git Workspaces](/ai/ti/guides/manage-git-workspaces.md) + - [Use Filesystem Journals](/ai/ti/guides/use-filesystem-journals.md) + - [Manage Filesystem Vault Secrets](/ai/ti/guides/manage-filesystem-vault-secrets.md) + - Scenarios for Users and Automation + - [Run a Daily TiDB Cloud CLI Workflow](/ai/ti/guides/ti-daily-workflow-example.md) + - [Query TiDB Cloud Starter with Explicit SQL Roles](/ai/ti/guides/ti-query-sql-with-roles-example.md) + - [Share a TiDB Cloud Filesystem Across Machines](/ai/ti/guides/ti-share-filesystem-across-machines-example.md) + - [Hand Off CI Artifacts Between Isolated Jobs with TiDB Cloud Filesystem](/ai/ti/guides/ti-ci-artifact-handoff-example.md) + - Scenarios for AI Agents + - [Use TiDB Cloud Filesystem in an Agent Sandbox](/ai/ti/guides/ti-agent-sandbox-example.md) + - [Persist Agent State Across Disposable Sandboxes with TiDB Cloud Filesystem](/ai/ti/guides/ti-persistent-agent-state-example.md) + - [Share a Read-Only Dataset Across Parallel Agents with TiDB Cloud Filesystem](/ai/ti/guides/ti-parallel-agent-dataset-example.md) + - [Prepare a Git Workspace for Agents on TiDB Cloud Filesystem](/ai/ti/guides/ti-git-workspace-for-agents-example.md) + - [Record an Agent Workflow in a TiDB Cloud Filesystem Journal](/ai/ti/guides/ti-journal-agent-workflow-example.md) + - [Delegate TiDB Cloud Filesystem Vault Secrets to an Agent](/ai/ti/guides/ti-vault-agent-secrets-example.md) + - Command Reference + - [Overview](/ai/ti/reference/ti-cli-reference.md) + - [configure](/ai/ti/reference/ti-configure.md) + - [update](/ai/ti/reference/ti-update.md) + - `ti db` commands for managing TiDB Cloud Starter instances + - [Overview](/ai/ti/reference/ti-starter-database.md) + - [create-db-cluster](/ai/ti/reference/ti-db-create-db-cluster.md) + - [list-db-clusters](/ai/ti/reference/ti-db-list-db-clusters.md) + - [describe-db-cluster](/ai/ti/reference/ti-db-describe-db-cluster.md) + - [update-db-cluster](/ai/ti/reference/ti-db-update-db-cluster.md) + - [delete-db-cluster](/ai/ti/reference/ti-db-delete-db-cluster.md) + - [create-db-cluster-branch](/ai/ti/reference/ti-db-create-db-cluster-branch.md) + - [list-db-cluster-branches](/ai/ti/reference/ti-db-list-db-cluster-branches.md) + - [describe-db-cluster-branch](/ai/ti/reference/ti-db-describe-db-cluster-branch.md) + - [delete-db-cluster-branch](/ai/ti/reference/ti-db-delete-db-cluster-branch.md) + - [create-db-sql-users](/ai/ti/reference/ti-db-create-db-sql-users.md) + - [format-db-connection-string](/ai/ti/reference/ti-db-format-db-connection-string.md) + - [execute-sql-statement](/ai/ti/reference/ti-db-execute-sql-statement.md) + - `ti fs` commands for managing TiDB Cloud Filesystems + - [Overview](/ai/ti/reference/ti-filesystem.md) + - [create-file-system](/ai/ti/reference/ti-fs-create-file-system.md) + - [import-file-system-token](/ai/ti/reference/ti-fs-import-file-system-token.md) + - [generate-file-system-token](/ai/ti/reference/ti-fs-generate-file-system-token.md) + - [generate-file-system-scoped-token](/ai/ti/reference/ti-fs-generate-file-system-scoped-token.md) + - [list-file-system-tokens](/ai/ti/reference/ti-fs-list-file-system-tokens.md) + - [enable-file-system-token](/ai/ti/reference/ti-fs-enable-file-system-token.md) + - [disable-file-system-token](/ai/ti/reference/ti-fs-disable-file-system-token.md) + - [delete-file-system-token](/ai/ti/reference/ti-fs-delete-file-system-token.md) + - [refresh-file-system-token](/ai/ti/reference/ti-fs-refresh-file-system-token.md) + - [list-file-systems](/ai/ti/reference/ti-fs-list-file-systems.md) + - [describe-file-system](/ai/ti/reference/ti-fs-describe-file-system.md) + - [describe-file-system-extract-configuration](/ai/ti/reference/ti-fs-describe-file-system-extract-configuration.md) + - [update-file-system-extract-configuration](/ai/ti/reference/ti-fs-update-file-system-extract-configuration.md) + - [describe-file-system-embedding-configuration](/ai/ti/reference/ti-fs-describe-file-system-embedding-configuration.md) + - [update-file-system-embedding-configuration](/ai/ti/reference/ti-fs-update-file-system-embedding-configuration.md) + - [check-file-system](/ai/ti/reference/ti-fs-check-file-system.md) + - [delete-file-system](/ai/ti/reference/ti-fs-delete-file-system.md) + - [copy-file](/ai/ti/reference/ti-fs-copy-file.md) + - [read-file](/ai/ti/reference/ti-fs-read-file.md) + - [list-files](/ai/ti/reference/ti-fs-list-files.md) + - [describe-file](/ai/ti/reference/ti-fs-describe-file.md) + - [move-file](/ai/ti/reference/ti-fs-move-file.md) + - [delete-file](/ai/ti/reference/ti-fs-delete-file.md) + - [create-directory](/ai/ti/reference/ti-fs-create-directory.md) + - [chmod-file](/ai/ti/reference/ti-fs-chmod-file.md) + - [create-symlink](/ai/ti/reference/ti-fs-create-symlink.md) + - [create-hardlink](/ai/ti/reference/ti-fs-create-hardlink.md) + - [search-file-content](/ai/ti/reference/ti-fs-search-file-content.md) + - [find-files](/ai/ti/reference/ti-fs-find-files.md) + - [create-layer](/ai/ti/reference/ti-fs-create-layer.md) + - [list-layers](/ai/ti/reference/ti-fs-list-layers.md) + - [fork-layer](/ai/ti/reference/ti-fs-fork-layer.md) + - [list-layer-chain](/ai/ti/reference/ti-fs-list-layer-chain.md) + - [describe-layer](/ai/ti/reference/ti-fs-describe-layer.md) + - [diff-layer](/ai/ti/reference/ti-fs-diff-layer.md) + - [create-layer-checkpoint](/ai/ti/reference/ti-fs-create-layer-checkpoint.md) + - [delete-layer](/ai/ti/reference/ti-fs-delete-layer.md) + - [rollback-layer](/ai/ti/reference/ti-fs-rollback-layer.md) + - [commit-layer](/ai/ti/reference/ti-fs-commit-layer.md) + - [pack-file-system](/ai/ti/reference/ti-fs-pack-file-system.md) + - [unpack-file-system](/ai/ti/reference/ti-fs-unpack-file-system.md) + - [mount-file-system](/ai/ti/reference/ti-fs-mount-file-system.md) + - [drain-file-system](/ai/ti/reference/ti-fs-drain-file-system.md) + - [unmount-file-system](/ai/ti/reference/ti-fs-unmount-file-system.md) + - `ti fs-git` commands for managing TiDB Cloud Filesystem Git workspaces + - [Overview](/ai/ti/reference/ti-filesystem-git.md) + - [clone-git-workspace](/ai/ti/reference/ti-fs-git-clone-git-workspace.md) + - [hydrate-git-workspace](/ai/ti/reference/ti-fs-git-hydrate-git-workspace.md) + - [add-git-worktree](/ai/ti/reference/ti-fs-git-add-git-worktree.md) + - [remove-git-worktree](/ai/ti/reference/ti-fs-git-remove-git-worktree.md) + - `ti fs-journal` commands for managing TiDB Cloud Filesystem journals + - [Overview](/ai/ti/reference/ti-filesystem-journal.md) + - [create-journal](/ai/ti/reference/ti-fs-journal-create-journal.md) + - [append-journal-entries](/ai/ti/reference/ti-fs-journal-append-journal-entries.md) + - [read-journal-entries](/ai/ti/reference/ti-fs-journal-read-journal-entries.md) + - [search-journal-entries](/ai/ti/reference/ti-fs-journal-search-journal-entries.md) + - [verify-journal](/ai/ti/reference/ti-fs-journal-verify-journal.md) + - `ti fs-vault` commands for managing TiDB Cloud Filesystem vault secrets + - [Overview](/ai/ti/reference/ti-filesystem-vault.md) + - [create-secret](/ai/ti/reference/ti-fs-vault-create-secret.md) + - [replace-secret](/ai/ti/reference/ti-fs-vault-replace-secret.md) + - [read-secret](/ai/ti/reference/ti-fs-vault-read-secret.md) + - [list-secrets](/ai/ti/reference/ti-fs-vault-list-secrets.md) + - [delete-secret](/ai/ti/reference/ti-fs-vault-delete-secret.md) + - [create-grant](/ai/ti/reference/ti-fs-vault-create-grant.md) + - [delete-grant](/ai/ti/reference/ti-fs-vault-delete-grant.md) + - [list-audit-events](/ai/ti/reference/ti-fs-vault-list-audit-events.md) + - [run-with-secret](/ai/ti/reference/ti-fs-vault-run-with-secret.md) + - [mount-vault](/ai/ti/reference/ti-fs-vault-mount-vault.md) + - [unmount-vault](/ai/ti/reference/ti-fs-vault-unmount-vault.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) + - [Migrate from tdc to TiDB Cloud CLI](/ai/ti/reference/ti-migrate-from-tdc.md) + - [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) ## INTEGRATIONS diff --git a/TOC-tidb-cloud-essential.md b/TOC-tidb-cloud-essential.md index 697c30ab0ce5f..5022e21679486 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) @@ -463,7 +463,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..78b4767293763 100644 --- a/ai/_index.md +++ b/ai/_index.md @@ -1,67 +1,123 @@ --- title: TiDB for AI -summary: Build modern AI applications with TiDB's integrated vector search, full-text search, and seamless Python SDK. +summary: Build AI applications and agent workflows with TiDB using SQL, integrated search, TiDB Cloud Starter, and persistent shared Filesystems. --- # TiDB for AI -TiDB is a distributed SQL database designed for modern AI applications, offering integrated vector search, full-text search, and hybrid search capabilities. This document provides an overview of the AI features and tools available for building AI-powered applications with TiDB. +TiDB provides data and workspace capabilities for building AI applications and running AI agent workflows. -## Quick start +- For application development, you can use SQL or [Python SDK for TiDB AI (`pytidb`)](https://github.com/pingcap/pytidb) with structured data, vector search, full-text search, hybrid search, and AI-powered retrieval. +- For AI agents and automation, you can use [TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) to manage TiDB Cloud Starter instances and SQL workflows, and use TiDB Cloud Filesystems as persistent, shared storage across local machines, CI jobs, and ephemeral agent sandboxes. Filesystems also support mounted workspaces, Git workflows, journals, and delegated secrets. -Get up and running quickly with TiDB's AI capabilities. +## Get started + +Choose a path based on what you want to build: + +| Goal | Start here | +| --- | --- | +| Build an AI application with vector search | [Get Started with Vector Search via Python](/ai/quickstart-via-python.md) or [Get Started with Vector Search via SQL](/ai/quickstart-via-sql.md) | +| Build agent and automation workflows with TiDB Cloud | [Get Started with TiDB Cloud CLI](/ai/ti/ti-quick-start.md) | + +## Build AI applications with TiDB + +Use the [`pytidb`](https://github.com/pingcap/pytidb) SDK or SQL to connect to TiDB, search and retrieve data, and build AI-powered applications. + +### Connect to TiDB | Document | Description | | --- | --- | -| [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. | +| [Connect to TiDB via Python](/ai/guides/connect.md) | Connect to TiDB Cloud or TiDB Self-Managed using `pytidb`. | + +### Search & retrieval + +#### Vector search -## Concepts +| Document | Description | +| --- | --- | +| [Vector Search Overview](/ai/guides/vector-search-overview.md) | Comprehensive overview of vector search, including concepts, how it works, and use cases. | +| [Vector Search Guide](/ai/guides/vector-search.md) | Perform semantic similarity searches using `pytidb`. | +| [Vector Search Example](/ai/guides/vector-search-with-pytidb.md) | Semantic similarity search example with `pytidb`. | -Understand the foundational concepts behind AI-powered search in TiDB. +#### Full-text search | Document | Description | | --- | --- | -| [Vector Search](/ai/concepts/vector-search-overview.md) | Comprehensive overview of vector search, including concepts, how it works, and use cases. | +| [Full-Text Search via Python](/ai/guides/vector-search-full-text-search-python.md) | Keyword-based text search with BM25 ranking using `pytidb`. | +| [Full-Text Search via SQL](/ai/guides/vector-search-full-text-search-sql.md) | Keyword-based text search with BM25 ranking using SQL. | +| [Full-Text Search Example](/ai/guides/fulltext-search-with-pytidb.md) | Full-text search example with `pytidb`. | -## Guides +#### Hybrid search + +| Document | Description | +| --- | --- | +| [Hybrid Search Guide](/ai/guides/vector-search-hybrid-search.md) | Combine vector and full-text search for better results. | +| [Hybrid Search Example](/ai/guides/hybrid-search-with-pytidb.md) | Hybrid search example with `pytidb`. | -Step-by-step guides for building AI applications with TiDB using the [`pytidb`](https://github.com/pingcap/pytidb) SDK or SQL. +#### Auto embeddings + +| Document | Description | +| --- | --- | +| [Auto Embedding Guide](/ai/guides/auto-embedding.md) | Automatically generate embeddings on data insertion. | +| [Auto Embedding Example](/ai/guides/auto-embedding-with-pytidb.md) | Auto embedding example with `pytidb`. | + +#### Image search + +| Document | Description | +| --- | --- | +| [Image Search Guide](/ai/guides/image-search.md) | Search images using multimodal embeddings. | +| [Image Search Example](/ai/guides/image-search-with-pytidb.md) | Multimodal image search example with Jina AI embeddings. | + +#### Reranking + +| Document | Description | +| --- | --- | +| [Reranking](/ai/guides/reranking.md) | Rerank search results for improved relevance. | + +### Work with data | Document | Description | | --- | --- | -| [Connect to TiDB](/ai/guides/connect.md) | Connect to TiDB Cloud or TiDB Self-Managed using `pytidb`. | | [Working with Tables](/ai/guides/tables.md) | Create, query, and manage tables with vector fields. | -| [Vector Search](/ai/guides/vector-search.md) | Perform semantic similarity searches using `pytidb`. | -| [Full-Text Search](/ai/guides/vector-search-full-text-search-python.md) | Keyword-based text search with BM25 ranking. | -| [Hybrid Search](/ai/guides/vector-search-hybrid-search.md) | Combine vector and full-text search for better results. | -| [Image Search](/ai/guides/image-search.md) | Search images using multimodal embeddings. | -| [Auto Embedding](/ai/guides/auto-embedding.md) | Automatically generate embeddings on data insertion. | | [Filtering](/ai/guides/filtering.md) | Filter search results with metadata conditions. | +| [Join Queries](/ai/guides/join-queries.md) | Perform join queries across tables. | +| [Raw SQL Queries](/ai/guides/raw-queries.md) | Execute raw SQL queries directly. | +| [Transactions](/ai/guides/transactions.md) | Use transactions for data consistency. | -## Examples - -Complete code examples and demos showcasing TiDB's AI capabilities. +### Application examples | Document | Description | | --- | --- | -| [Basic CRUD Operations](/ai/examples/basic-with-pytidb.md) | Fundamental table operations with `pytidb`. | -| [Vector Search](/ai/examples/vector-search-with-pytidb.md) | Semantic similarity search example. | -| [RAG Application](/ai/examples/rag-with-pytidb.md) | Build a Retrieval-Augmented Generation application. | -| [Image Search](/ai/examples/image-search-with-pytidb.md) | Multimodal image search with Jina AI embeddings. | -| [Conversational Memory](/ai/examples/memory-with-pytidb.md) | Persistent memory for AI agents and chatbots. | -| [Text-to-SQL](/ai/examples/text2sql-with-pytidb.md) | Convert natural language to SQL queries. | +| [RAG Example](/ai/guides/rag-with-pytidb.md) | Build a Retrieval-Augmented Generation application. | +| [Conversational Memory Example](/ai/guides/memory-with-pytidb.md) | Persistent memory for AI agents and chatbots. | +| [Text-to-SQL Example](/ai/guides/text2sql-with-pytidb.md) | Convert natural language to SQL queries. | + +## Build agent and automation workflows with TiDB Cloud CLI + +The TiDB Cloud CLI (`ti`) lets users, scripts, CI jobs, and AI agents manage TiDB Cloud from a terminal. Use it to automate TiDB Cloud Starter and SQL operations or to keep files and workspaces available independently of the machines and sandboxes that use them. + +| What you want to do | Start here | +| --- | --- | +| Understand what `ti` manages and when to use it | [TiDB Cloud CLI Overview](/ai/ti/ti-overview.md) | +| Install and configure `ti`, then complete a first workflow | [Get Started with TiDB Cloud CLI](/ai/ti/ti-quick-start.md) | +| Automate TiDB Cloud Starter instance, branch, and SQL operations | [Manage TiDB Cloud Starter Instances](/ai/ti/guides/manage-starter-instances.md) | +| Persist and share files across machines, CI jobs, and sandboxes | [Manage Filesystem Resources](/ai/ti/guides/manage-filesystem-resources.md) and [Work with Filesystem Data](/ai/ti/guides/work-with-filesystem-data.md) | +| Use mounted workspaces, Git workspaces, journals, or delegated secrets | [Mount a Filesystem](/ai/ti/guides/mount-filesystem.md), [Manage Git Workspaces](/ai/ti/guides/manage-git-workspaces.md), [Use Filesystem Journals](/ai/ti/guides/use-filesystem-journals.md), and [Manage Filesystem Vault Secrets](/ai/ti/guides/manage-filesystem-vault-secrets.md) | +| Follow an end-to-end automation or agent example | [Run a Daily TiDB Cloud CLI Workflow](/ai/ti/guides/ti-daily-workflow-example.md) or [Use TiDB Cloud Filesystem in an Agent Sandbox](/ai/ti/guides/ti-agent-sandbox-example.md) | +| Look up commands, global options, output behavior, and errors | [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) | ## Integrations -Integrate TiDB with popular AI frameworks, embedding providers, and development tools. +Connect TiDB to embedding providers, AI frameworks, application libraries, cloud services, and AI development tools. -| Document | Description | +| Integration area | Start here | | --- | --- | -| [Integration Overview](/ai/integrations/vector-search-integration-overview.md) | Overview of all available integrations. | -| [Embedding Providers](/ai/integrations/vector-search-auto-embedding-overview.md#available-text-embedding-models) | Unified interface for OpenAI, Cohere, Jina AI, and more. | -| [LlamaIndex](/ai/integrations/vector-search-integrate-with-llamaindex.md) | Use TiDB as a vector store with LlamaIndex. | -| [MCP Server](/ai/integrations/tidb-mcp-server.md) | Connect TiDB to Claude Code, Cursor, and other AI-powered IDEs. | +| All integrations | [AI Integrations for TiDB](/ai/integrations/vector-search-integration-overview.md) | +| Auto Embedding providers | [Auto Embedding Overview](/ai/integrations/vector-search-auto-embedding-overview.md) | +| AI frameworks | [LlamaIndex](/ai/integrations/vector-search-integrate-with-llamaindex.md) | +| ORM libraries | [SQLAlchemy](/ai/integrations/vector-search-integrate-with-sqlalchemy.md), [Django ORM](/ai/integrations/vector-search-integrate-with-django-orm.md), and [Peewee](/ai/integrations/vector-search-integrate-with-peewee.md) | +| Cloud embedding services | [Jina AI Embedding](/ai/integrations/vector-search-integrate-with-jinaai-embedding.md) and [Amazon Bedrock](/ai/integrations/vector-search-integrate-with-amazon-bedrock.md) | +| MCP clients and AI development tools | [TiDB MCP Server](/ai/integrations/tidb-mcp-server.md) | ## Reference @@ -70,7 +126,7 @@ Technical reference documentation for TiDB's AI and vector search features. | Document | Description | | --- | --- | | [Vector Data Types](/ai/reference/vector-search-data-types.md) | Vector column types and usage. | -| [Functions and Operators](/ai/reference/vector-search-functions-and-operators.md) | Distance functions and vector operations. | +| [Vector Functions and Operators](/ai/reference/vector-search-functions-and-operators.md) | Distance functions and vector operations. | | [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. | +| [Vector Search Performance Tuning](/ai/reference/vector-search-improve-performance.md) | Optimize vector search performance. | +| [Vector Search Limitations](/ai/reference/vector-search-limitations.md) | Current limitations and constraints. | diff --git a/ai/examples/basic-with-pytidb.md b/ai/examples/basic-with-pytidb.md deleted file mode 100644 index 32d47d39341d3..0000000000000 --- a/ai/examples/basic-with-pytidb.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Basic CRUD Operations -summary: Learn fundamental `pytidb` operations including database connection, table creation, and data manipulation. ---- - -# Basic CRUD Operations - -This example demonstrates basic CRUD (Create, Read, Update, Delete) operations using [`pytidb`](https://github.com/pingcap/pytidb) (the official Python SDK for TiDB). - -1. Connect to TiDB using the `pytidb` client. -2. Create a table with text, vector, and JSON columns. -3. Run basic CRUD operations on the data. - -## Prerequisites - -Before you begin, ensure you have the following: - -- **Python (>=3.10)**: Install [Python](https://www.python.org/downloads/) 3.10 or a later version. -- **A {{{ .starter }}} instance**: You can create a free {{{ .starter }}} instance on [TiDB Cloud](https://tidbcloud.com/free-trial). - -## How to run - -### Step 1. Clone the `pytidb` repository - -```bash -git clone https://github.com/pingcap/pytidb.git -cd pytidb/examples/basic/ -``` - -### Step 2. Install the required packages - -```bash -python -m venv .venv -source .venv/bin/activate -pip install -r reqs.txt -``` - -### Step 3. Set environment variables - -1. In the [TiDB Cloud console](https://tidbcloud.com/), navigate to the [**My TiDB**](https://tidbcloud.com/tidbs) page, and then click the name of your target {{{ .starter }}} instance to go to its overview page. -2. Click **Connect** in the upper-right corner. A connection dialog is displayed, with connection parameters listed. -3. Set environment variables according to the connection parameters as follows: - -```bash -cat > .env < **Note:** > -> For a complete example of auto embedding, see [Auto Embedding Example](/ai/examples/auto-embedding-with-pytidb.md). +> For a complete example of auto embedding, see [Auto Embedding Example](/ai/guides/auto-embedding-with-pytidb.md). ## Basic usage diff --git a/ai/examples/fulltext-search-with-pytidb.md b/ai/guides/fulltext-search-with-pytidb.md similarity index 100% rename from ai/examples/fulltext-search-with-pytidb.md rename to ai/guides/fulltext-search-with-pytidb.md diff --git a/ai/examples/hybrid-search-with-pytidb.md b/ai/guides/hybrid-search-with-pytidb.md similarity index 100% rename from ai/examples/hybrid-search-with-pytidb.md rename to ai/guides/hybrid-search-with-pytidb.md diff --git a/ai/examples/image-search-with-pytidb.md b/ai/guides/image-search-with-pytidb.md similarity index 100% rename from ai/examples/image-search-with-pytidb.md rename to ai/guides/image-search-with-pytidb.md diff --git a/ai/guides/image-search.md b/ai/guides/image-search.md index abe6518341e0c..d57d9921a5ba8 100644 --- a/ai/guides/image-search.md +++ b/ai/guides/image-search.md @@ -11,7 +11,7 @@ TiDB enables image search through **vector search**. With automatic embedding, y > **Note:** > -> For a complete example of image search, see [Image Search Example](/ai/examples/image-search-with-pytidb.md). +> For a complete example of image search, see [Image Search Example](/ai/guides/image-search-with-pytidb.md). ## Basic usage @@ -107,5 +107,5 @@ Then, the multimodal embedding model converts the keyword text into an embedding ## See also - [Automatic embedding guide](/ai/guides/auto-embedding.md) -- [Vector search guide](/ai/concepts/vector-search-overview.md) -- [Image Search Example](/ai/examples/image-search-with-pytidb.md) +- [Vector search guide](/ai/guides/vector-search-overview.md) +- [Image Search Example](/ai/guides/image-search-with-pytidb.md) diff --git a/ai/examples/memory-with-pytidb.md b/ai/guides/memory-with-pytidb.md similarity index 100% rename from ai/examples/memory-with-pytidb.md rename to ai/guides/memory-with-pytidb.md diff --git a/ai/examples/rag-with-pytidb.md b/ai/guides/rag-with-pytidb.md similarity index 100% rename from ai/examples/rag-with-pytidb.md rename to ai/guides/rag-with-pytidb.md diff --git a/ai/guides/tables.md b/ai/guides/tables.md index dceda111b6fd6..dd493c7fe350c 100644 --- a/ai/guides/tables.md +++ b/ai/guides/tables.md @@ -1,6 +1,7 @@ --- title: Working with Tables summary: Learn how to work with tables in TiDB. +aliases: ['/ai/basic-with-pytidb/'] --- # Working with Tables @@ -13,10 +14,6 @@ This document shows how to work with tables using [`pytidb`](https://github.com/ `pytidb` is the official Python SDK for TiDB, designed to help developers build AI applications efficiently. -> **Note:** -> -> For a complete working example, see the [basic example](https://github.com/pingcap/pytidb/tree/main/examples/basic) in our repository. - ## Create a table ### Using TableModel @@ -445,4 +442,52 @@ SHOW TABLES; ``` - \ No newline at end of file + + +## Run the complete `pytidb` CRUD example + +The `pytidb` repository provides a complete example that connects to TiDB, creates a table with text, vector, and JSON columns, and performs CRUD operations. + +Before you begin, make sure you have: + +- Python 3.10 or later. +- A {{{ .starter }}} instance. You can create one on [TiDB Cloud](https://tidbcloud.com/free-trial). + +To run the example: + +1. Clone the `pytidb` repository and go to the example directory: + + ```bash + git clone https://github.com/pingcap/pytidb.git + cd pytidb/examples/basic/ + ``` + +2. Create and activate a virtual environment, and then install the required packages: + + ```bash + python -m venv .venv + source .venv/bin/activate + pip install -r reqs.txt + ``` + +3. In the [TiDB Cloud console](https://tidbcloud.com/), go to the [**My TiDB**](https://tidbcloud.com/tidbs) page, click the name of your {{{ .starter }}} instance, and then click **Connect** in the upper-right corner to get the connection parameters. + +4. Create a `.env` file and set the connection parameters: + + ```bash + cat > .env <<'EOF' + TIDB_HOST={gateway-region}.prod.aws.tidbcloud.com + TIDB_PORT=4000 + TIDB_USERNAME={prefix}.root + TIDB_PASSWORD={password} + TIDB_DATABASE=test + EOF + ``` + +5. Run the example: + + ```bash + python main.py + ``` + +The example prints the results of each CRUD operation and drops the example table when it finishes. To inspect the implementation, see the [`pytidb` basic example](https://github.com/pingcap/pytidb/tree/main/examples/basic). diff --git a/ai/examples/text2sql-with-pytidb.md b/ai/guides/text2sql-with-pytidb.md similarity index 100% rename from ai/examples/text2sql-with-pytidb.md rename to ai/guides/text2sql-with-pytidb.md diff --git a/ai/guides/vector-search-full-text-search-python.md b/ai/guides/vector-search-full-text-search-python.md index 5a0e40bf47da3..05f3107d64220 100644 --- a/ai/guides/vector-search-full-text-search-python.md +++ b/ai/guides/vector-search-full-text-search-python.md @@ -6,7 +6,7 @@ aliases: ['/tidb/stable/vector-search-full-text-search-python/','/tidbcloud/vect # Full-Text Search with Python -Unlike [Vector Search](/ai/concepts/vector-search-overview.md), which focuses on semantic similarity, full-text search lets you retrieve documents for exact keywords. In Retrieval-Augmented Generation (RAG) scenarios, you can use full-text search together with vector search to improve the retrieval quality. +Unlike [Vector Search](/ai/guides/vector-search-overview.md), which focuses on semantic similarity, full-text search lets you retrieve documents for exact keywords. In Retrieval-Augmented Generation (RAG) scenarios, you can use full-text search together with vector search to improve the retrieval quality. The full-text search feature in TiDB provides the following capabilities: diff --git a/ai/guides/vector-search-full-text-search-sql.md b/ai/guides/vector-search-full-text-search-sql.md index 22f89e1eb8dbf..cd437b395b82a 100644 --- a/ai/guides/vector-search-full-text-search-sql.md +++ b/ai/guides/vector-search-full-text-search-sql.md @@ -6,7 +6,7 @@ aliases: ['/tidb/stable/vector-search-full-text-search-sql/','/tidbcloud/vector- # Full-Text Search with SQL -Unlike [Vector Search](/ai/concepts/vector-search-overview.md), which focuses on semantic similarity, full-text search lets you retrieve documents for exact keywords. In Retrieval-Augmented Generation (RAG) scenarios, you can use full-text search together with vector search to improve the retrieval quality. +Unlike [Vector Search](/ai/guides/vector-search-overview.md), which focuses on semantic similarity, full-text search lets you retrieve documents for exact keywords. In Retrieval-Augmented Generation (RAG) scenarios, you can use full-text search together with vector search to improve the retrieval quality. The full-text search feature in TiDB provides the following capabilities: diff --git a/ai/concepts/vector-search-overview.md b/ai/guides/vector-search-overview.md similarity index 100% rename from ai/concepts/vector-search-overview.md rename to ai/guides/vector-search-overview.md diff --git a/ai/examples/vector-search-with-pytidb.md b/ai/guides/vector-search-with-pytidb.md similarity index 100% rename from ai/examples/vector-search-with-pytidb.md rename to ai/guides/vector-search-with-pytidb.md diff --git a/ai/guides/vector-search.md b/ai/guides/vector-search.md index 2c14019a5e680..6d8aabd72c48f 100644 --- a/ai/guides/vector-search.md +++ b/ai/guides/vector-search.md @@ -9,7 +9,7 @@ Vector search uses semantic similarity to help you find the most relevant record > **Note:** > -> For a complete example of vector search, see [Vector Search Example](/ai/examples/vector-search-with-pytidb.md). +> For a complete example of vector search, see [Vector Search Example](/ai/guides/vector-search-with-pytidb.md). ## Basic usage @@ -113,7 +113,7 @@ VALUES > **Note:** > -> In real-world applications, embeddings are usually generated by an [embedding model](/ai/concepts/vector-search-overview.md#embedding-model). +> In real-world applications, embeddings are usually generated by an [embedding model](/ai/guides/vector-search-overview.md#embedding-model). For convenience, pytidb provides an auto embedding feature that can automatically generate vector embeddings for your text fields when you insert, update, or search—no manual processing needed. diff --git a/ai/integrations/vector-search-auto-embedding-amazon-titan.md b/ai/integrations/vector-search-auto-embedding-amazon-titan.md index 92fe6432efae3..0ddfb69ba2ac1 100644 --- a/ai/integrations/vector-search-auto-embedding-amazon-titan.md +++ b/ai/integrations/vector-search-auto-embedding-amazon-titan.md @@ -130,6 +130,6 @@ Result: ## See also - [Auto Embedding Overview](/ai/integrations/vector-search-auto-embedding-overview.md) -- [Vector Search](/ai/concepts/vector-search-overview.md) +- [Vector Search](/ai/guides/vector-search-overview.md) - [Vector Functions and Operators](/ai/reference/vector-search-functions-and-operators.md) - [Hybrid Search](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-cohere.md b/ai/integrations/vector-search-auto-embedding-cohere.md index 1b9b4bc2cc760..1a198ca145119 100644 --- a/ai/integrations/vector-search-auto-embedding-cohere.md +++ b/ai/integrations/vector-search-auto-embedding-cohere.md @@ -336,6 +336,6 @@ For all available options, see [Cohere Documentation](https://docs.cohere.com/v2 ## See also - [Auto Embedding Overview](/ai/integrations/vector-search-auto-embedding-overview.md) -- [Vector Search](/ai/concepts/vector-search-overview.md) +- [Vector Search](/ai/guides/vector-search-overview.md) - [Vector Functions and Operators](/ai/reference/vector-search-functions-and-operators.md) - [Hybrid Search](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-gemini.md b/ai/integrations/vector-search-auto-embedding-gemini.md index 2ce4bfb5f77e6..f293a1ec8e5e5 100644 --- a/ai/integrations/vector-search-auto-embedding-gemini.md +++ b/ai/integrations/vector-search-auto-embedding-gemini.md @@ -282,6 +282,6 @@ For all available options, see [Gemini documentation](https://ai.google.dev/gemi ## See also - [Auto Embedding Overview](/ai/integrations/vector-search-auto-embedding-overview.md) -- [Vector Search](/ai/concepts/vector-search-overview.md) +- [Vector Search](/ai/guides/vector-search-overview.md) - [Vector Functions and Operators](/ai/reference/vector-search-functions-and-operators.md) - [Hybrid Search](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-huggingface.md b/ai/integrations/vector-search-auto-embedding-huggingface.md index f03c9cf24b60f..becc4fa9820d7 100644 --- a/ai/integrations/vector-search-auto-embedding-huggingface.md +++ b/ai/integrations/vector-search-auto-embedding-huggingface.md @@ -324,6 +324,6 @@ for doc in results: ## See also - [Auto Embedding Overview](/ai/integrations/vector-search-auto-embedding-overview.md) -- [Vector Search](/ai/concepts/vector-search-overview.md) +- [Vector Search](/ai/guides/vector-search-overview.md) - [Vector Functions and Operators](/ai/reference/vector-search-functions-and-operators.md) - [Hybrid Search](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-jina-ai.md b/ai/integrations/vector-search-auto-embedding-jina-ai.md index 4611b6e417ea7..76708b5302dcc 100644 --- a/ai/integrations/vector-search-auto-embedding-jina-ai.md +++ b/ai/integrations/vector-search-auto-embedding-jina-ai.md @@ -260,6 +260,6 @@ For all available options, see [Jina AI Documentation](https://jina.ai/embedding ## See also - [Auto Embedding Overview](/ai/integrations/vector-search-auto-embedding-overview.md) -- [Vector Search](/ai/concepts/vector-search-overview.md) +- [Vector Search](/ai/guides/vector-search-overview.md) - [Vector Functions and Operators](/ai/reference/vector-search-functions-and-operators.md) - [Hybrid Search](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-nvidia-nim.md b/ai/integrations/vector-search-auto-embedding-nvidia-nim.md index 7bf7d87b52256..45a3529257ca3 100644 --- a/ai/integrations/vector-search-auto-embedding-nvidia-nim.md +++ b/ai/integrations/vector-search-auto-embedding-nvidia-nim.md @@ -250,6 +250,6 @@ LIMIT 3; ## See also - [Auto Embedding Overview](/ai/integrations/vector-search-auto-embedding-overview.md) -- [Vector Search](/ai/concepts/vector-search-overview.md) +- [Vector Search](/ai/guides/vector-search-overview.md) - [Vector Functions and Operators](/ai/reference/vector-search-functions-and-operators.md) - [Hybrid Search](/ai/guides/vector-search-hybrid-search.md) diff --git a/ai/integrations/vector-search-auto-embedding-openai.md b/ai/integrations/vector-search-auto-embedding-openai.md index 79a8748dcfd87..7068131f6bfcb 100644 --- a/ai/integrations/vector-search-auto-embedding-openai.md +++ b/ai/integrations/vector-search-auto-embedding-openai.md @@ -292,6 +292,6 @@ For all available options, see [OpenAI Documentation](https://platform.openai.co ## See also - [Auto Embedding Overview](/ai/integrations/vector-search-auto-embedding-overview.md) -- [Vector Search](/ai/concepts/vector-search-overview.md) +- [Vector Search](/ai/guides/vector-search-overview.md) - [Vector Functions and Operators](/ai/reference/vector-search-functions-and-operators.md) - [Hybrid Search](/ai/guides/vector-search-hybrid-search.md) \ No newline at end of file diff --git a/ai/integrations/vector-search-integrate-with-amazon-bedrock.md b/ai/integrations/vector-search-integrate-with-amazon-bedrock.md index 942eeb304a098..dfc5a9bc84ccc 100644 --- a/ai/integrations/vector-search-integrate-with-amazon-bedrock.md +++ b/ai/integrations/vector-search-integrate-with-amazon-bedrock.md @@ -10,7 +10,7 @@ aliases: ['/tidbcloud/vector-search-integrate-with-amazon-bedrock/'] > > This document is applicable to TiDB Cloud only and not applicable to TiDB Self-Managed. -This tutorial demonstrates how to integrate [TiDB Vector Search](/ai/concepts/vector-search-overview.md) with [Amazon Bedrock](https://aws.amazon.com/bedrock/) to build a Retrieval-Augmented Generation (RAG) Q&A bot. +This tutorial demonstrates how to integrate [TiDB Vector Search](/ai/guides/vector-search-overview.md) with [Amazon Bedrock](https://aws.amazon.com/bedrock/) to build a Retrieval-Augmented Generation (RAG) Q&A bot. > **Note:** > diff --git a/ai/integrations/vector-search-integrate-with-django-orm.md b/ai/integrations/vector-search-integrate-with-django-orm.md index 995dc3bf306ee..e82031b2aade7 100644 --- a/ai/integrations/vector-search-integrate-with-django-orm.md +++ b/ai/integrations/vector-search-integrate-with-django-orm.md @@ -6,7 +6,7 @@ aliases: ['/tidb/stable/vector-search-integrate-with-django-orm/','/tidb/dev/vec # Integrate TiDB Vector Search with Django ORM -This tutorial walks you through how to use the [Django](https://www.djangoproject.com/) ORM to interact with [TiDB Vector Search](/ai/concepts/vector-search-overview.md), store embeddings, and perform vector search queries. +This tutorial walks you through how to use the [Django](https://www.djangoproject.com/) ORM to interact with [TiDB Vector Search](/ai/guides/vector-search-overview.md), store embeddings, and perform vector search queries. > **Note:** > diff --git a/ai/integrations/vector-search-integrate-with-langchain.md b/ai/integrations/vector-search-integrate-with-langchain.md index b307bebb69598..8e56eeda87091 100644 --- a/ai/integrations/vector-search-integrate-with-langchain.md +++ b/ai/integrations/vector-search-integrate-with-langchain.md @@ -6,7 +6,7 @@ aliases: ['/tidb/stable/vector-search-integrate-with-langchain/','/tidb/dev/vect # Integrate Vector Search with LangChain -This tutorial demonstrates how to integrate [TiDB Vector Search](/ai/concepts/vector-search-overview.md) with [LangChain](https://python.langchain.com/). +This tutorial demonstrates how to integrate [TiDB Vector Search](/ai/guides/vector-search-overview.md) with [LangChain](https://python.langchain.com/). > **Note:** > diff --git a/ai/integrations/vector-search-integrate-with-llamaindex.md b/ai/integrations/vector-search-integrate-with-llamaindex.md index 67d709673f9db..51ec67602f2d0 100644 --- a/ai/integrations/vector-search-integrate-with-llamaindex.md +++ b/ai/integrations/vector-search-integrate-with-llamaindex.md @@ -6,7 +6,7 @@ aliases: ['/tidb/stable/vector-search-integrate-with-llamaindex/','/tidb/dev/vec # Integrate Vector Search with LlamaIndex -This tutorial demonstrates how to integrate [TiDB Vector Search](/ai/concepts/vector-search-overview.md) with [LlamaIndex](https://www.llamaindex.ai). +This tutorial demonstrates how to integrate [TiDB Vector Search](/ai/guides/vector-search-overview.md) with [LlamaIndex](https://www.llamaindex.ai). > **Note:** > diff --git a/ai/integrations/vector-search-integrate-with-peewee.md b/ai/integrations/vector-search-integrate-with-peewee.md index ac91d992f07dd..12738e9f667fa 100644 --- a/ai/integrations/vector-search-integrate-with-peewee.md +++ b/ai/integrations/vector-search-integrate-with-peewee.md @@ -6,7 +6,7 @@ aliases: ['/tidb/stable/vector-search-integrate-with-peewee/','/tidb/dev/vector- # Integrate TiDB Vector Search with peewee -This tutorial walks you through how to use [peewee](https://docs.peewee-orm.com/) to interact with [TiDB Vector Search](/ai/concepts/vector-search-overview.md), store embeddings, and perform vector search queries. +This tutorial walks you through how to use [peewee](https://docs.peewee-orm.com/) to interact with [TiDB Vector Search](/ai/guides/vector-search-overview.md), store embeddings, and perform vector search queries. > **Note:** > diff --git a/ai/integrations/vector-search-integrate-with-sqlalchemy.md b/ai/integrations/vector-search-integrate-with-sqlalchemy.md index 77e68fe5360e2..ba38fe583d233 100644 --- a/ai/integrations/vector-search-integrate-with-sqlalchemy.md +++ b/ai/integrations/vector-search-integrate-with-sqlalchemy.md @@ -6,7 +6,7 @@ aliases: ['/tidb/stable/vector-search-integrate-with-sqlalchemy/','/tidb/dev/vec # Integrate TiDB Vector Search with SQLAlchemy -This tutorial walks you through how to use [SQLAlchemy](https://www.sqlalchemy.org/) to interact with [TiDB Vector Search](/ai/concepts/vector-search-overview.md), store embeddings, and perform vector search queries. +This tutorial walks you through how to use [SQLAlchemy](https://www.sqlalchemy.org/) to interact with [TiDB Vector Search](/ai/guides/vector-search-overview.md), store embeddings, and perform vector search queries. > **Note:** > diff --git a/ai/quickstart-via-python.md b/ai/quickstart-via-python.md index 8697cd1a4f1f3..a5c72f4e8e56f 100644 --- a/ai/quickstart-via-python.md +++ b/ai/quickstart-via-python.md @@ -6,7 +6,7 @@ aliases: ['/tidb/stable/vector-search-get-started-using-python/','/tidb/dev/vect # Get Started with TiDB + AI via Python -This document demonstrates how to get started with [Vector Search](/ai/concepts/vector-search-overview.md) in TiDB using Python SDK. Follow along to build your first AI application working with TiDB. +This document demonstrates how to get started with [Vector Search](/ai/guides/vector-search-overview.md) in TiDB using Python SDK. Follow along to build your first AI application working with TiDB. By following this document, you will learn how to: @@ -108,7 +108,7 @@ Once connected, you can use the `client` object to operate tables, query data, a ## Create an embedding function -When working with [embedding models](/ai/concepts/vector-search-overview.md#embedding-model), you can leverage the embedding function to automatically vectorize your data at both insertion and query stages. It natively supports popular embedding models like OpenAI, Jina AI, Hugging Face, Sentence Transformers, and others. +When working with [embedding models](/ai/guides/vector-search-overview.md#embedding-model), you can leverage the embedding function to automatically vectorize your data at both insertion and query stages. It natively supports popular embedding models like OpenAI, Jina AI, Hugging Face, Sentence Transformers, and others.
diff --git a/ai/quickstart-via-sql.md b/ai/quickstart-via-sql.md index 272b5693b8db2..45b5f34cd6b77 100644 --- a/ai/quickstart-via-sql.md +++ b/ai/quickstart-via-sql.md @@ -6,7 +6,7 @@ aliases: ['/tidb/stable/vector-search-get-started-using-sql/','/tidb/dev/vector- # Get Started with TiDB + AI via SQL -TiDB extends MySQL syntax to support [Vector Search](/ai/concepts/vector-search-overview.md) and introduce new [Vector data types](/ai/reference/vector-search-data-types.md) and several [vector functions](/ai/reference/vector-search-functions-and-operators.md). +TiDB extends MySQL syntax to support [Vector Search](/ai/guides/vector-search-overview.md) and introduce new [Vector data types](/ai/reference/vector-search-data-types.md) and several [vector functions](/ai/reference/vector-search-functions-and-operators.md). This document demonstrates how to get started with TiDB Vector Search just using SQL statements. You will learn how to use the [MySQL command-line client](https://dev.mysql.com/doc/refman/8.4/en/mysql.html) to complete the following operations: @@ -72,7 +72,7 @@ mysql --comments --host 127.0.0.1 --port 4000 -u root ### Step 2. Create a vector table -When creating a table, you can define a column as a [vector](/ai/concepts/vector-search-overview.md#vector-embedding) column by specifying the `VECTOR` data type. +When creating a table, you can define a column as a [vector](/ai/guides/vector-search-overview.md#vector-embedding) column by specifying the `VECTOR` data type. For example, to create a table `embedded_documents` with a three-dimensional `VECTOR` column, execute the following SQL statements using your MySQL CLI: @@ -95,7 +95,7 @@ Query OK, 0 rows affected (0.27 sec) ### Step 3. Insert vector embeddings to the table -Insert three documents with their [vector embeddings](/ai/concepts/vector-search-overview.md#vector-embedding) into the `embedded_documents` table: +Insert three documents with their [vector embeddings](/ai/guides/vector-search-overview.md#vector-embedding) into the `embedded_documents` table: ```sql INSERT INTO embedded_documents @@ -116,7 +116,7 @@ Records: 3 Duplicates: 0 Warnings: 0 > > This example simplifies the dimensions of the vector embeddings and uses only 3-dimensional vectors for demonstration purposes. > -> In real-world applications, [embedding models](/ai/concepts/vector-search-overview.md#embedding-model) often produce vector embeddings with hundreds or thousands of dimensions. +> In real-world applications, [embedding models](/ai/guides/vector-search-overview.md#embedding-model) often produce vector embeddings with hundreds or thousands of dimensions. ### Step 4. Query the vector table diff --git a/ai/reference/vector-search-index.md b/ai/reference/vector-search-index.md index 1cacf20fb439f..d490721a53e8a 100644 --- a/ai/reference/vector-search-index.md +++ b/ai/reference/vector-search-index.md @@ -6,7 +6,7 @@ aliases: ['/tidb/stable/vector-search-index/','/tidb/dev/vector-search-index/',' # Vector Search Index -As described in the [Vector Search](/ai/concepts/vector-search-overview.md) document, vector search identifies the Top K-Nearest Neighbors (KNN) to a given vector by calculating the distance between the given vector and all vectors stored in the database. While this approach provides accurate results, it can be slow when the table contains a large number of vectors because it involves a full table scan. [^1] +As described in the [Vector Search](/ai/guides/vector-search-overview.md) document, vector search identifies the Top K-Nearest Neighbors (KNN) to a given vector by calculating the distance between the given vector and all vectors stored in the database. While this approach provides accurate results, it can be slow when the table contains a large number of vectors because it involves a full table scan. [^1] To improve search efficiency, you can create vector search indexes in TiDB for approximate KNN (ANN) search. When using vector indexes for vector search, TiDB can greatly improve query performance with only a slight reduction in accuracy, generally maintaining a search recall rate above 90%. diff --git a/ai/ti/guides/configure-filesystem-ai-providers.md b/ai/ti/guides/configure-filesystem-ai-providers.md new file mode 100644 index 0000000000000..138ee6f720ee4 --- /dev/null +++ b/ai/ti/guides/configure-filesystem-ai-providers.md @@ -0,0 +1,114 @@ +--- +title: Configure TiDB Cloud Filesystem AI Providers +summary: Learn how to inspect and configure media extraction and embedding providers for a TiDB Cloud Filesystem by using the CLI. +--- + +# Configure TiDB Cloud Filesystem AI Providers + +A TiDB Cloud Filesystem can optionally extract text from media files and generate embeddings for stored content. To enable these capabilities, you can configure one or more AI providers through the CLI. + +## Prerequisites + +- [Install and configure TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md). +- Obtain the target Filesystem ID. +- Obtain the API key required by your selected AI provider. + +The configuration commands require TiDB Cloud API credentials and an explicit Filesystem ID. Set the provider key through `TI_FS_AI_PROVIDER_API_KEY`. The CLI does not persist the key locally. The Filesystem service stores it encrypted and returns only a masked value in subsequent configuration output. + +For an interactive shell, read and export the provider key without placing it in shell history: + +```bash +printf 'Provider API key: ' >&2 +read -r -s TI_FS_AI_PROVIDER_API_KEY +printf '\n' >&2 +export TI_FS_AI_PROVIDER_API_KEY +``` + +In CI, inject `TI_FS_AI_PROVIDER_API_KEY` from a masked secret. Unset the variable after you finish configuring providers. + +> **Note:** +> +> When you enable, re-enable, or replace a provider configuration, the Filesystem service sends a small built-in request to the provider endpoint to validate the credentials, connectivity, and model response. This validation request might incur a provider charge. A disable-only or prompt-only update does not make a validation request. + +## Inspect media extraction configuration + +Read the effective extraction configuration for a media type: + +```shell +ti fs describe-file-system-extract-configuration \ + --file-system-id "" \ + --media-type image +``` + +## Update media extraction configuration + +Use [`update-file-system-extract-configuration`](/ai/ti/reference/ti-fs-update-file-system-extract-configuration.md) to enable, update, or disable image, audio, or video extraction. For example, configure image extraction through an OpenAI-compatible provider: + +```shell +ti fs update-file-system-extract-configuration \ + --file-system-id "" \ + --media-type image \ + --enabled true \ + --provider-api-base https://api.openai.com/v1 \ + --provider-model "" \ + --provider-protocol openai +``` + +The `openai` protocol supports image, audio, and video extraction. The `qwen-asr` protocol is supported only for audio extraction through Alibaba Cloud Model Studio. An endpoint from another provider might work if it implements the required OpenAI-compatible API contract. Native interfaces for Anthropic, Gemini, Vertex AI, Amazon Bedrock, and Azure OpenAI are not supported. + +To disable extraction for a media type: + +```shell +ti fs update-file-system-extract-configuration \ + --file-system-id "" \ + --media-type image \ + --enabled false +``` + +## Inspect embedding configuration + +Read whether embeddings are managed by the application or database: + +```shell +ti fs describe-file-system-embedding-configuration \ + --file-system-id "" +``` + +## Update embedding configuration + +Use [`update-file-system-embedding-configuration`](/ai/ti/reference/ti-fs-update-file-system-embedding-configuration.md) to update the optional application-managed embedding configuration. For example: + +```shell +ti fs update-file-system-embedding-configuration \ + --file-system-id "" \ + --enabled true \ + --provider-api-base https://api.openai.com/v1 \ + --provider-model text-embedding-3-small +``` + +Application-managed embeddings require an OpenAI-compatible endpoint that returns 1024-dimensional vectors. They are available for Shared Filesystems and Native Filesystems whose effective embedding mode is `fts_only`. If a Native Filesystem uses database-managed automatic embeddings, the service rejects this update and reports `source=database_auto`. + +After you finish configuring providers, remove the key from the current shell: + +```shell +unset TI_FS_AI_PROVIDER_API_KEY +``` + +To disable that configuration: + +```shell +ti fs update-file-system-embedding-configuration \ + --file-system-id "" \ + --enabled false +``` + +## Data flow after configuration + +After you enable extraction, the Filesystem service sends media content to the configured extraction provider. It sends the extracted text or descriptions to the configured embedding provider. Choose provider accounts and retention policies appropriate for your data. + +If an update fails because of a timeout, lost response, or another ambiguous network error, run the matching `describe-file-system-*-configuration` command before retrying. The provider validation request might have succeeded and incurred a charge even if the CLI did not receive the response. + +## What's next + +- [Work with TiDB Cloud Filesystem Data](/ai/ti/guides/work-with-filesystem-data.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/guides/manage-filesystem-layers.md b/ai/ti/guides/manage-filesystem-layers.md new file mode 100644 index 0000000000000..1ece63ff88283 --- /dev/null +++ b/ai/ti/guides/manage-filesystem-layers.md @@ -0,0 +1,116 @@ +--- +title: Manage TiDB Cloud Filesystem Layers and Checkpoints +summary: Learn how to safely create, inspect, fork, checkpoint, roll back, commit, pack, and restore TiDB Cloud Filesystem layers. +--- + +# Manage TiDB Cloud Filesystem Layers and Checkpoints + +Use layers to record isolated changes over a Filesystem base path before you commit or discard them. + +## Prerequisites + +- [Install and configure TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md). +- Select a Filesystem by passing `--file-system-id`, setting `TI_FS_FILE_SYSTEM_ID`, or supplying an FS token that identifies the Filesystem. +- Provide an FS token with the required read or write permission by using `--fs-token`, `TI_FS_TOKEN`, or the local credential stored for the selected Filesystem. +- Choose the base path whose data the layer overlays. + +## Create and inspect a layer + +```shell +ti fs create-layer \ + --base-root-path /workspace \ + --layer-name agent-task \ + --durability-mode restore-safe \ + --tag task=review +``` + +Use the returned layer ID to write and inspect changes: + +```shell +ti fs copy-file \ + --from-local ./proposal.md \ + --to-remote /workspace/proposal.md \ + --layer-id "" + +ti fs describe-layer --layer-id "" +ti fs diff-layer --layer-id "" +``` + +> **Note:** +> +> `copy-file` with `--layer-id` does not support recursive copy. To seed a directory tree into a layer, mount the layer as a writable FUSE mount and copy files through the mount path. + +Do not mount the same writable layer at multiple local paths concurrently. Reuse its existing mount, or unmount it before mounting the layer elsewhere. + +## Create a checkpoint and fork a layer + +```shell +ti fs create-layer-checkpoint \ + --layer-id "" \ + --checkpoint-id seed \ + --label "before review" + +ti fs fork-layer \ + --parent-layer-ref "" \ + --layer-name experiment \ + --checkpoint-id seed +``` + +Use `list-layer-chain` to inspect the pinned ancestry of the fork: + +```shell +ti fs list-layer-chain --layer-ref experiment +``` + +A checkpoint mount is read-only. To continue working from a checkpoint, fork a new writable layer from it. + +## Finish work in a layer + +> **Warning:** +> +> Before you create a checkpoint for a layer with a writable FUSE mount, run [`drain-file-system`](/ai/ti/guides/mount-filesystem.md#drain-or-unmount). A checkpoint includes only changes that have reached the service. Before you roll back or commit the layer, drain and then [`unmount-file-system`](/ai/ti/guides/mount-filesystem.md#drain-or-unmount). The CLI does not perform these steps automatically. + +Choose one outcome for a layer: + +- Roll back the layer to discard its changes: + + ```shell + ti fs rollback-layer --layer-id "" + ``` + +- Commit the layer to apply its changes to the base path: + + ```shell + ti fs commit-layer --layer-id "" + ``` + +> **Note:** +> +> Do not run both `rollback-layer` and `commit-layer` in sequence for the same layer. + +## Move local state to another machine + +When a FUSE mount uses write-back cache, some data can remain in its local overlay directory. To move this local state to another machine, pack it to an explicit remote archive path: + +```shell +ti fs pack-file-system \ + --mount-path /path/to/workspace \ + --archive-path /workspace-overlay.tar.gz +``` + +On the destination machine, restore the archive into a local overlay root: + +```shell +ti fs unpack-file-system \ + --local-root /path/to/local-overlay \ + --remote-root /workspace \ + --mount-profile portable \ + --archive-path /workspace-overlay.tar.gz +``` + +Use the same local overlay root when you mount the Filesystem on the destination machine. For all pack and unpack options, see the [`pack-file-system`](/ai/ti/reference/ti-fs-pack-file-system.md) and [`unpack-file-system`](/ai/ti/reference/ti-fs-unpack-file-system.md) references. + +## What's next + +- [Mount a TiDB Cloud Filesystem](/ai/ti/guides/mount-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/guides/manage-filesystem-resources.md b/ai/ti/guides/manage-filesystem-resources.md new file mode 100644 index 0000000000000..0ba5d578fd957 --- /dev/null +++ b/ai/ti/guides/manage-filesystem-resources.md @@ -0,0 +1,85 @@ +--- +title: Manage TiDB Cloud Filesystem Resources +summary: Learn how to safely create, inspect, check, select, and delete TiDB Cloud Filesystem resources by using TiDB Cloud CLI. +--- + +# Manage TiDB Cloud Filesystem Resources + +TiDB Cloud Filesystem is a serverless distributed file system designed for AI agents and automation workloads. It provides a persistent, shareable file namespace that remains available independently of the local machine, sandbox, or CI runner that accesses it. + +You can access files directly through TiDB Cloud CLI commands or mount a Filesystem into a supported environment and work with it like a local file system. This makes it useful for preserving agent state, sharing files across isolated environments, handing off CI artifacts, and maintaining reusable workspaces. + +This document describes how to use [`ti fs` commands](/ai/ti/reference/ti-filesystem.md) to create, inspect, select, and delete Filesystem resources. + +## Prerequisites + +- [Install and configure TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md). +- Configure a profile with TiDB Cloud API credentials. +- Install `jq`, or use another JSON processor to capture command output safely. + +## Create a Filesystem + +Create a Filesystem and save the returned ID and one-time owner token in a file that is not world-readable. The `--wait` flag tells the CLI to poll until data-plane access is ready before returning: + +```shell +umask 077 +ti fs create-file-system \ + --display-name agent-workspace \ + --label environment=development \ + --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)" +``` + +> **Warning:** +> +> The JSON response includes `fs_token` only once. The CLI also stores this token in its local credential directory automatically. However, if the local storage is lost, you cannot retrieve the token again. Store a backup copy in a secret manager, and then delete `filesystem.json`. + +> **Note:** +> +> Do not put credentials, connection strings, private paths, or personal data in Filesystem labels. + +## List and inspect Filesystems + +List the Filesystems available in the effective region: + +```shell +ti fs list-file-systems --output text +``` + +Read authoritative metadata for one Filesystem: + +```shell +ti fs describe-file-system --file-system-id "" +``` + +If you have access to more than one Filesystem, pass `--file-system-id` explicitly or set the `TI_FS_FILE_SYSTEM_ID` environment variable. The CLI does not automatically select a Filesystem for you. + +## Check access + +Verify resource selection, endpoint resolution, credentials, and companion access: + +```shell +ti fs check-file-system --file-system-id "" +``` + +## Delete a Filesystem + +> **Warning:** +> +> Before deleting a Filesystem, drain and unmount any active local mounts for it. The CLI does not do this automatically. + +Delete a Filesystem by explicit ID: + +```shell +ti fs delete-file-system --file-system-id "" +``` + +Filesystem deletion is asynchronous. After the service accepts the request, the CLI reports the Filesystem status as `deleting` and removes the matching local credential. This output does not mean that remote deletion has finished. + +## What's next + +- [Manage TiDB Cloud Filesystem Tokens](/ai/ti/guides/manage-filesystem-tokens.md) +- [Work with TiDB Cloud Filesystem Data](/ai/ti/guides/work-with-filesystem-data.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/guides/manage-filesystem-tokens.md b/ai/ti/guides/manage-filesystem-tokens.md new file mode 100644 index 0000000000000..b7a861d775410 --- /dev/null +++ b/ai/ti/guides/manage-filesystem-tokens.md @@ -0,0 +1,79 @@ +--- +title: Manage TiDB Cloud Filesystem Tokens +summary: Learn how to import, generate, scope, inspect, disable, refresh, and revoke access tokens for a TiDB Cloud Filesystem. +--- + +# Manage TiDB Cloud Filesystem Tokens + +You can use Filesystem tokens to give users or automation access to a TiDB Cloud Filesystem without sharing TiDB Cloud API credentials. + +## Prerequisites + +- [Install and configure TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md). +- For owner-token generation and TiDB Cloud-authenticated token management, configure TiDB Cloud API credentials and obtain the Filesystem ID. +- For scoped-token generation or bearer-authenticated token management, obtain an owner FS token. You can pass it through `--fs-token`, set `TI_FS_TOKEN`, or use the local token stored for an explicitly selected Filesystem. + +> **Note:** +> +> To avoid security risks, treat token plaintext as a secret. Token creation and rotation commands return plaintext only once when the token is issued. You cannot retrieve the plaintext later. + +## Import an existing token + +When you run `import-file-system-token`, the CLI validates the token format, extracts the Filesystem ID embedded in it, verifies connectivity by making a remote stat request, and stores the token in the local credential directory: + +```shell +ti fs import-file-system-token --from-file ./fs-token --region aws-us-east-1 +``` + +## Generate a token + +Generate another owner token by using TiDB Cloud API credentials. The CLI does not store the generated token locally by default, so you must capture its one-time plaintext response securely: + +```shell +umask 077 +ti fs generate-file-system-token \ + --file-system-id "" \ + --token-name ci \ + --ttl 24h > ./ci-token.json +``` + +To have the CLI store the generated token locally, add `--store-locally`. Use `--replace` if a different token is already stored for this Filesystem. + +For least-privilege access, generate a path-and-operation-limited token from an owner token: + +```shell +ti fs generate-file-system-scoped-token \ + --file-system-id "" \ + --ttl 24h \ + --allow /workspace:read,list > ./scoped-token.json +``` + +## Inspect and change token status + +List non-secret token metadata: + +```shell +ti fs list-file-system-tokens --file-system-id "" +``` + +Use [`disable-file-system-token`](/ai/ti/reference/ti-fs-disable-file-system-token.md) to suspend a token temporarily and [`enable-file-system-token`](/ai/ti/reference/ti-fs-enable-file-system-token.md) to restore it. + +## Rotate or revoke a token + +Use [`refresh-file-system-token`](/ai/ti/reference/ti-fs-refresh-file-system-token.md) to rotate a token. When you refresh the locally stored token, the CLI automatically updates the local credential file. When you refresh a token provided through `--fs-token` or `TI_FS_TOKEN`, the CLI returns the new token in the command output without storing it. + +> **Note:** +> +> Refresh is non-idempotent. If a request might have succeeded but its response was lost, do not retry with the old token. Instead, generate a new owner token using TiDB Cloud credentials. + +Use [`delete-file-system-token`](/ai/ti/reference/ti-fs-delete-file-system-token.md) to revoke a token permanently. If the deleted token matches the locally stored token, the CLI automatically removes the local credential. + +> **Note:** +> +> Before you rotate, disable, or delete a token used by an active local mount, run [`drain-file-system`](/ai/ti/guides/mount-filesystem.md#drain-or-unmount) and then [`unmount-file-system`](/ai/ti/guides/mount-filesystem.md#drain-or-unmount). The CLI checks for known active mounts and refuses the operation if the token is still in use. + +## What's next + +- [Share a TiDB Cloud Filesystem Across Machines](/ai/ti/guides/ti-share-filesystem-across-machines-example.md) +- [Use TiDB Cloud Filesystem in an Agent Sandbox](/ai/ti/guides/ti-agent-sandbox-example.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/guides/manage-filesystem-vault-secrets.md b/ai/ti/guides/manage-filesystem-vault-secrets.md new file mode 100644 index 0000000000000..4b222e12983b4 --- /dev/null +++ b/ai/ti/guides/manage-filesystem-vault-secrets.md @@ -0,0 +1,108 @@ +--- +title: Manage TiDB Cloud Filesystem Vault Secrets +summary: Learn how to store, read, delegate, inject, audit, revoke, and mount secrets securely with TiDB Cloud Filesystem Vault. +--- + +# Manage TiDB Cloud Filesystem Vault Secrets + +TiDB Cloud Filesystem Vault lets you store secrets, delegate narrowly scoped and time-limited access to users or agents, and inject credentials into processes without writing plaintext to disk. + +## Prerequisites + +- [Install and configure TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md). +- Select a Filesystem by passing `--file-system-id`, setting `TI_FS_FILE_SYSTEM_ID`, or supplying an FS token that identifies the Filesystem. +- For owner operations, provide an owner FS token through `--fs-token`, `TI_FS_TOKEN`, or the local credential stored for the selected Filesystem. + +> **Note:** +> +> To avoid security risks, never print, log, or commit owner or delegated tokens. + +## Create and read a secret + +```shell +ti fs-vault create-secret \ + --secret-name db-prod \ + --field DB_URL=mysql://example \ + --field PASSWORD=@./password.txt + +ti fs-vault read-secret --secret-name db-prod +``` + +> **Note:** +> +> All `read-secret` output formats, including the default JSON format, contain plaintext secret values. Direct the output only to the intended process. + +## Delegate limited access + +Create a short-lived read grant and capture its token: + +```shell +export TI_VAULT_TOKEN="$(ti fs-vault create-grant \ + --agent-id deploy-agent \ + --scope db-prod/DB_URL \ + --permission read \ + --ttl 10m \ + --token-only)" +``` + +Prefer `TI_VAULT_TOKEN` to a command-line token because command-line values can remain in process listings or shell history. + +## Inject a secret into a process + +The CLI can inject secret fields as environment variables into a child process without writing plaintext to disk. When you run the following command, the CLI reads the secret, sets each field as an environment variable (for example, `DB_URL`, `PASSWORD`), removes its own credential environment variables from the child, and then executes the specified command: + +```shell +ti fs-vault run-with-secret --secret-path /n/vault/db-prod -- +``` + +Prefer process injection to writing plaintext to disk. + +Field names injected by `run-with-secret` must match `[A-Z_][A-Z0-9_]*`. The command rejects the entire injection if any field name does not match this pattern or any field value contains an unsupported control character. Use uppercase environment-variable-style names when creating fields that you plan to inject. + +## Audit and revoke access + +```shell +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 but cannot erase a value that a process already read. + +## Mount a read-only Vault view + +On macOS or Linux with FUSE support, you can mount a read-only FUSE view of Vault secrets. The CLI creates the mount and serves secret fields as files under the mount path (for example, `/path/to/vault/db-prod/DB_URL`): + +Before mounting, set `TI_VAULT_TOKEN` to a delegated Vault token, such as the token created in [Delegate limited access](#delegate-limited-access). The mount command requires either `TI_VAULT_TOKEN` or `--vault-token`. + +```shell +mkdir -p /path/to/vault +ti fs-vault mount-vault \ + --mount-path /path/to/vault +``` + +Stop any processes that use the mount before you unmount it: + +```shell +ti fs-vault unmount-vault --mount-path /path/to/vault +``` + +Vault mounts are unavailable on Windows. Direct secret reads and process injection do not require a mount. + +## Security recommendations + +- Grant the narrowest field scope and shortest practical TTL. +- Do not store delegated tokens in CLI configuration or operation logs. +- Revoke grants after their tasks finish. + +## What's next + +- [Delegate TiDB Cloud Filesystem Vault Secrets to an Agent](/ai/ti/guides/ti-vault-agent-secrets-example.md) +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/guides/manage-git-workspaces.md b/ai/ti/guides/manage-git-workspaces.md new file mode 100644 index 0000000000000..ad2ba0ec29752 --- /dev/null +++ b/ai/ti/guides/manage-git-workspaces.md @@ -0,0 +1,66 @@ +--- +title: Manage Git Workspaces on TiDB Cloud Filesystem +summary: Learn how to clone, hydrate, create linked worktrees, and remove Git workspaces on a mounted TiDB Cloud Filesystem. +--- + +# Manage Git Workspaces on TiDB Cloud Filesystem + +Use `ti fs-git` to accelerate Git workspace setup on a mounted TiDB Cloud Filesystem while continuing to use ordinary Git commands for daily work. + +## Prerequisites + +- [Install and configure TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md). +- [Mount a TiDB Cloud Filesystem](/ai/ti/guides/mount-filesystem.md) through FUSE. +- Select the mounted Filesystem by passing `--file-system-id`, setting `TI_FS_FILE_SYSTEM_ID`, or supplying an FS token that identifies it. Provide an FS token with Git workspace permissions. +- Install Git and configure repository credentials independently. + +## Clone a workspace + +```shell +ti fs-git clone-git-workspace \ + --repo-url https://github.com/pingcap/tidb.git \ + --target-path /path/to/workspace/tidb +``` + +For a large repository, add `--blobless --hydrate background` to make the directory tree available immediately. The CLI starts a background process that downloads clean file content and Git objects after the clone command returns. Use `--hydrate sync` when your workflow requires hydration to finish before the command returns. + +## Hydrate an existing workspace + +If a workspace was cloned with `--blobless`, you can explicitly fetch the missing Git objects by running `hydrate-git-workspace`: + +```shell +ti fs-git hydrate-git-workspace \ + --target-path /path/to/workspace/tidb \ + --timeout 30m +``` + +Hydration fetches missing blob data from the remote repository without discarding your working-tree changes. + +## Add and use a linked worktree + +```shell +ti fs-git add-git-worktree \ + --base-path /path/to/workspace/tidb \ + --worktree-path /path/to/workspace/tidb-feature \ + --branch-name feature-x +``` + +After creation, use ordinary Git commands in the linked worktree. + +## Remove a worktree + +```shell +ti fs-git remove-git-worktree \ + --worktree-path /path/to/workspace/tidb-feature +``` + +The CLI checks for uncommitted changes and rejects the removal if the worktree is dirty. Use `--force` only after you decide that local changes in the worktree can be discarded. + +> **Note:** +> +> Before terminating an ephemeral machine, preserve required changes, remove unused worktrees, and gracefully unmount the Filesystem. + +## What's next + +- [Prepare a Git Workspace for Agents on TiDB Cloud Filesystem](/ai/ti/guides/ti-git-workspace-for-agents-example.md) +- [TiDB Cloud Filesystem Git CLI Command Reference](/ai/ti/reference/ti-filesystem-git.md) diff --git a/ai/ti/guides/manage-starter-instances.md b/ai/ti/guides/manage-starter-instances.md new file mode 100644 index 0000000000000..226c7927ec647 --- /dev/null +++ b/ai/ti/guides/manage-starter-instances.md @@ -0,0 +1,87 @@ +--- +title: Manage TiDB Cloud Starter Instances +summary: Learn how to use TiDB Cloud CLI to create and manage Starter instances, branches, SQL users, connections, and SQL statements. +--- + +# Manage TiDB Cloud Starter Instances + +This document describes how to use `ti db` commands in the TiDB Cloud CLI to manage TiDB Cloud Starter instances, branches, and SQL access from a terminal or automation workflow. + +## Prerequisites + +- [Install and configure TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md). +- Configure a profile with credentials that can access TiDB Cloud Starter. + +## Create a TiDB Cloud Starter instance + +Create a TiDB Cloud Starter instance and wait until it becomes active: + +```shell +ti db create-db-cluster --db-cluster-type starter --db-cluster-name app-db --wait +``` + +## List instances + +List TiDB Cloud Starter instances in the effective region: + +```shell +ti db list-db-clusters --db-cluster-type starter --output text +``` + +To get information about a TiDB Cloud Starter instance, pass its ID to [`describe-db-cluster`](/ai/ti/reference/ti-db-describe-db-cluster.md). + +## Manage branches + +Create a development branch from an instance: + +```shell +ti db create-db-cluster-branch \ + --db-cluster-id "" \ + --db-cluster-branch-name dev \ + --wait +``` + +Use the branch list, description, and deletion commands to manage its lifecycle. For their complete options, see the [`ti db` command reference](/ai/ti/reference/ti-starter-database.md). + +## Configure SQL access + +Create or repair the read-only, read-write, and admin SQL users for an instance: + +```shell +ti db create-db-sql-users --db-cluster-id "" +``` + +Format the stored credentials for an application: + +```shell +ti db format-db-connection-string \ + --db-cluster-id "" \ + --read-only \ + --format env +``` + +## Execute SQL + +Execute one statement with an explicit SQL role: + +```shell +ti db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --sql "SELECT 1" +``` + +For a workflow that separates read-only, read-write, and administrative operations, see [Query TiDB Cloud Starter with Explicit SQL Roles](/ai/ti/guides/ti-query-sql-with-roles-example.md). + +## Delete an instance + +When you no longer need the instance, delete it and wait until the deletion is observable: + +```shell +ti db delete-db-cluster --db-cluster-id "" --wait +``` + +## What's next + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) +- [Run a Daily TiDB Cloud CLI Workflow](/ai/ti/guides/ti-daily-workflow-example.md) diff --git a/ai/ti/guides/mount-filesystem.md b/ai/ti/guides/mount-filesystem.md new file mode 100644 index 0000000000000..52a73e39ba801 --- /dev/null +++ b/ai/ti/guides/mount-filesystem.md @@ -0,0 +1,130 @@ +--- +title: Mount a TiDB Cloud Filesystem +summary: Learn how to safely mount, use, drain, and unmount a TiDB Cloud Filesystem on macOS, Linux, or in a container. +--- + +# Mount a TiDB Cloud Filesystem + +In TiDB Cloud CLI, you can mount a TiDB Cloud Filesystem when an application needs to access remote data through a local filesystem path. + +## Prerequisites + +- [Install and configure TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md). +- Select a Filesystem by passing `--file-system-id`, setting `TI_FS_FILE_SYSTEM_ID`, or supplying an FS token that identifies the Filesystem. +- Provide an FS token through `--fs-token`, `TI_FS_TOKEN`, or the local credential stored for the selected Filesystem. +- On Linux, install FUSE3 and provide access to `/dev/fuse`. + +## Choose a mount driver + +| Platform | `--driver auto` | Notes | +|---|---|---| +| macOS | WebDAV | Install macFUSE and select `--driver fuse` for FUSE support. | +| Linux | FUSE | WebDAV mounting is not supported. | +| Windows | Not supported | Use `ti fs` data-plane commands without a mount. | + +## Mount the Filesystem + +On macOS or Linux, create a local path and mount the Filesystem in the background: + +```shell +mkdir -p /path/to/workspace +ti fs mount-file-system \ + --file-system-id "" \ + --mount-path /path/to/workspace +``` + +The CLI starts a background mount process and writes a local mount locator so that the drain and unmount commands can find the correct process. + +Use `--remote-path` to expose a subtree or `--read-only` to prevent writes. To mount a layer or checkpoint, select the FUSE driver and pass the appropriate layer options described in the [`mount-file-system` reference](/ai/ti/reference/ti-fs-mount-file-system.md). + +## Mount in a container + +Installing FUSE3 in an image is not sufficient. The host must expose `/dev/fuse`, and the container must be allowed to perform the mount. For Docker, provide settings equivalent to the following: + +```shell +docker run --rm -it \ + --device /dev/fuse \ + --cap-add SYS_ADMIN \ + --security-opt apparmor=unconfined \ + --env TI_FS_TOKEN \ + --env TI_REGION_CODE \ + --env TI_FS_FILE_SYSTEM_ID \ + +``` + +For Docker Compose, pass the same device, capability, security, and environment settings: + +```yaml +services: + agent: + image: + 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} +``` + +> **Warning:** +> +> `SYS_ADMIN` and an unconfined AppArmor profile weaken container isolation. Use them only for a dedicated, trusted container. When FUSE access is unavailable, use `ti fs` data commands without a mount. + +## Ubuntu 26.04 mount paths + +Ubuntu 26.04 applies an AppArmor profile to `/usr/bin/fusermount3`. By default, use a path under the current user's home directory, `/mnt`, `/media`, `/tmp`, or `/run/user/` instead of `/workspace`. + +For example: + +```shell +mkdir -p "$HOME/workspace" +ti fs mount-file-system \ + --file-system-id "" \ + --mount-path "$HOME/workspace" +``` + +If an application requires `/workspace`, add the following rules to `/etc/apparmor.d/local/fusermount3`: + +```text +mount fstype=@{fuse_types} options=(nosuid,nodev) options in (ro,rw,noatime,dirsync,nodiratime,noexec,sync) -> /workspace/{,**/}, +umount /workspace/{,**/}, +``` + +Then reload the profile: + +```shell +sudo apparmor_parser -r /etc/apparmor.d/fusermount3 +``` + +For related errors, see [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md). + +## Drain or unmount + +When you run `unmount-file-system`, the CLI automatically flushes open file handles and pending FUSE work before stopping the mount: + +```shell +ti fs unmount-file-system --mount-path /path/to/workspace +``` + +If you need a durability barrier while keeping a FUSE mount online (for example, before creating a layer checkpoint), run `drain-file-system` explicitly. This command flushes pending writes and waits for them to complete without unmounting: + +```shell +ti fs drain-file-system --mount-path /path/to/workspace --timeout 30s +``` + +> **Note:** +> +> Drain is supported only for FUSE mounts. WebDAV mounts flush writes through normal file close operations. + +> **Warning:** +> +> Do not terminate a machine while writes remain pending or after an unmount returns an error. In-memory writes and local-only overlay files can be lost. For a FUSE mount, run `drain-file-system` before shutdown to confirm that pending writes have reached the remote Filesystem. For a WebDAV mount, close files in the application and verify that `unmount-file-system` succeeds. + +## What's next + +- [Manage TiDB Cloud Filesystem Layers and Checkpoints](/ai/ti/guides/manage-filesystem-layers.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/guides/ti-agent-sandbox-example.md b/ai/ti/guides/ti-agent-sandbox-example.md new file mode 100644 index 0000000000000..98e01ecf5d5cb --- /dev/null +++ b/ai/ti/guides/ti-agent-sandbox-example.md @@ -0,0 +1,111 @@ +--- +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 workflow gives an ephemeral coding agent a durable, shared workspace without copying a user's complete TiDB Cloud CLI configuration into the sandbox. Use it when the sandbox's local disk is disposable but the agent needs artifacts, repository state, or files from previous sessions or other workers without rebuilding that state for every sandbox. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +> **Note:** +> +> For a hands-on version of this workflow, open the [TiDB Cloud Filesystem for Agent Sandbox Lab](https://labs.tidb.io/labs/demo_901). This interactive Lab Guide walks you through using a persistent Filesystem in an agent sandbox. + +## How it works + +A trusted machine provisions the Filesystem once. The sandbox receives only the Filesystem owner token and region code, so it can use ordinary file operations and data-plane, mount, Git, journal, and vault workflows without `ti configure`, a copied `~/.ti/` directory, or TiDB Cloud API keys. This also avoids the application-specific upload and download logic required by generic object-storage APIs. 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 by using the release installer. +- Install `jq` on the trusted machine. +- 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 region code used to create the Filesystem. 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= +``` + +The sandbox does not need `TIDB_CLOUD_PUBLIC_KEY`, `TIDB_CLOUD_PRIVATE_KEY`, `ti configure`, or files copied from `~/.ti/`. + +## Step 3. Verify direct access + +In the sandbox: + +```bash +printf 'sandbox ready\n' | 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" +``` + +On macOS, omit `--driver fuse` to use WebDAV, which requires no FUSE installation. Install macFUSE and select FUSE when you need FUSE-specific capabilities such as Git workspaces, layers, or online drain. For platform requirements and mount-path restrictions, see [Mount a TiDB Cloud Filesystem](/ai/ti/guides/mount-filesystem.md). + +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" +``` + +For a FUSE mount, use `ti fs drain-file-system --mount-path "$HOME/workspace"` separately when you need to verify remote durability while keeping the mount online. `drain-file-system` is not supported for WebDAV. For more information, see [Drain or unmount](/ai/ti/guides/mount-filesystem.md#drain-or-unmount). Back on the trusted machine: + +```bash +ti fs delete-file-system \ + --file-system-id "$FILE_SYSTEM_ID" +``` + +## Security and operational 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/guides/ti-ci-artifact-handoff-example.md b/ai/ti/guides/ti-ci-artifact-handoff-example.md new file mode 100644 index 0000000000000..a0a39282375a3 --- /dev/null +++ b/ai/ti/guides/ti-ci-artifact-handoff-example.md @@ -0,0 +1,76 @@ +--- +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 workflow uses a Filesystem as a durable handoff point between isolated CI jobs or runners. Use it when build output must survive the producer job and become available to a later consumer without adding a provider-specific artifact API, retention model, and download workflow. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## How it works + +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 such as `/ci/${RUN_ID}/`, and the consumer downloads or streams data from that exact path on another runner. Neither job needs TiDB Cloud API keys or a copied `~/.ti/` directory. + +## Prerequisites + +[Create a Filesystem](/ai/ti/guides/manage-filesystem-resources.md#create-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. + +## 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) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/ti/guides/ti-daily-workflow-example.md b/ai/ti/guides/ti-daily-workflow-example.md new file mode 100644 index 0000000000000..2ced8bd8863fa --- /dev/null +++ b/ai/ti/guides/ti-daily-workflow-example.md @@ -0,0 +1,125 @@ +--- +title: Run a Daily TiDB Cloud CLI Workflow +summary: Inspect resources, manage a TiDB Cloud Starter instance 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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Prerequisites + +- Install `ti` and run `ti configure`. +- Ensure your organization has capacity for one TiDB Cloud Starter instance 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 TiDB Cloud Starter instance + +```bash +ti db create-db-cluster \ + --db-cluster-type starter \ + --db-cluster-name daily-demo \ + --dry-run + +export DB_CLUSTER_ID="$(ti db create-db-cluster \ + --db-cluster-type starter \ + --db-cluster-name daily-demo \ + --wait \ + --query id \ + --output text)" +``` + +The command saves the returned cluster ID in `DB_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 "$DB_CLUSTER_ID" \ + --output text +``` + +## Step 3. Verify SQL access + +```bash +ti db create-db-sql-users --db-cluster-id "$DB_CLUSTER_ID" +ti db execute-sql-statement \ + --db-cluster-id "$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 \ + --wait \ + --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 + +Check whether a newer version is available without changing the installed version: + +```bash +ti update --check +``` + +Preview an update: + +```bash +ti update --dry-run +``` + +If another workflow has an active Filesystem or Vault mount, stop writers and unmount it before applying the update so that `ti` and the Filesystem runtime are updated together. For instructions, see [Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md#update-tidb-cloud-cli). + +Apply the update when appropriate: + +```bash +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 "$DB_CLUSTER_ID" +``` + +> **Note:** +> +> Deleting local TiDB Cloud CLI configuration does not delete 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/guides/ti-git-workspace-for-agents-example.md b/ai/ti/guides/ti-git-workspace-for-agents-example.md new file mode 100644 index 0000000000000..01dcff8a56c8e --- /dev/null +++ b/ai/ti/guides/ti-git-workspace-for-agents-example.md @@ -0,0 +1,96 @@ +--- +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 workflow removes a large repository clone from the critical path of starting an agent task. Use it when an ephemeral agent needs to inspect or change a large repository before a complete download would finish. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## How it works + +`ti fs-git clone-git-workspace --blobless --hydrate background` registers a Git workspace that can be shared across replacement agent runtimes 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. Unlike a normal clone, the initial object transfer does not block the complete workflow. Unlike a native blobless partial clone alone, background hydration reduces repeated on-demand fetches on the agent's critical path. Reads that arrive before hydration completes still 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`. Git workspaces rely on FUSE to combine the remote Git tree and workspace changes into the mounted path; WebDAV mounts do not provide this integration. +- 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 \ + --mount-profile coding-agent +``` + +## 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 operational notes + +- Repository credentials are managed by Git, not `ti`. +- The `coding-agent` mount profile keeps Git metadata, dependency directories, caches, build output, and other generated files on the local machine for performance. +- Files kept locally by the `coding-agent` profile disappear with an ephemeral machine. Commit or push required Git changes, and use [`pack-file-system`](/ai/ti/reference/ti-fs-pack-file-system.md) with explicit `--path` values to preserve other local files that 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/guides/ti-journal-agent-workflow-example.md b/ai/ti/guides/ti-journal-agent-workflow-example.md new file mode 100644 index 0000000000000..f1ef2b58efbf1 --- /dev/null +++ b/ai/ti/guides/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 workflow records planning, tool calls, tests, retries, and handoffs as a structured, ordered, and verifiable event history. Use it when operators need to reconstruct what happened across workers instead of relying on scattered console output or a mutable status file that shows only the latest state. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## How it works + +A Filesystem journal stores structured append-only entries with sequence information, searchable fields, optional idempotency keys, and hash-chain verification. Unlike a normal text file, journal entries cannot be edited or truncated after they are written, and producers do not need to implement their own parsing, concurrency, or retry-deduplication mechanism. Agents append semantic events such as `task.started` and `test.finished`; operators can query the workflow and verify the stored chain. + +## 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"}' +``` + +Specify an idempotency key when the workflow might retry the same append, and reuse that key for every retry of that logical operation. The service then avoids storing duplicate entries. When you omit the option, a new key is generated, which is appropriate for an append that you do not intend to retry. + +## 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 `read-journal-entries` result for `jrn-agent-demo` should include the start, test, and completion events. + +> **Note:** +> +> `search-journal-entries` searches all journals in the selected Filesystem because it does not accept a journal ID. Another journal with the same labels and event fields can also match the search in this example. + +The `--entry-type` and `--status` filters match the `type` and `status` fields in each `--entry-json` object. In this example, they select the entry whose payload contains `"type":"task.finished"` and `"status":"completed"`. + +## 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. For experiments that create disposable journals, use a dedicated test Filesystem and unique journal IDs such as `jrn-test-`. Delete the containing Filesystem only when none of its files or journals are still needed. + +## Security and operational 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/guides/ti-vault-agent-secrets-example.md) diff --git a/ai/ti/guides/ti-parallel-agent-dataset-example.md b/ai/ti/guides/ti-parallel-agent-dataset-example.md new file mode 100644 index 0000000000000..82759e9d767f0 --- /dev/null +++ b/ai/ti/guides/ti-parallel-agent-dataset-example.md @@ -0,0 +1,102 @@ +--- +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 workflow gives multiple short-lived workers one shared corpus without downloading a separate copy into every sandbox. Use it when parallel document-processing or evaluation agents need consistent access to the same PDFs, images, logs, or model artifacts. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## How it works + +An owner uploads the corpus once and creates a scoped, read-only Filesystem token for each worker. Every worker selects the same Filesystem and mounts the corpus read-only, so ordinary tools can traverse one common namespace without a storage SDK. This reduces startup time and avoids independent point-in-time copies. If workers produce results, they write them to separate paths in a different, writable output Filesystem, not to the dataset Filesystem. + +## Prerequisites + +- Install and configure the TiDB Cloud CLI on a trusted machine. +- Install the TiDB Cloud CLI and the required mount dependencies in each worker. +- Install `jq` on the trusted machine. +- Use a secure secret manager or encrypted worker input for token transfer. + +## 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 + +# Create one short-lived, read-only scoped token per worker. +ti fs generate-file-system-scoped-token \ + --file-system-id "$TI_FS_FILE_SYSTEM_ID" \ + --subject worker-1 \ + --ttl 24h \ + --allow /datasets/corpus:read,list > ./worker-1-token.json +``` + +Transfer the `fs_token` from `worker-1-token.json` and the Filesystem region code through a secret manager. Repeat the token-generation command with a unique subject for each worker. Keep the owner token only on the trusted machine, and delete the JSON files after storing the tokens securely. + +## Step 2. Mount in each worker + +> **Warning:** +> +> Give each worker a scoped token that permits only `read` and `list` under the corpus path. The `--read-only` mount option prevents accidental writes through the mount, but it does not change a token's permissions. + +Inject the worker's scoped token as `TI_FS_TOKEN` and set `TI_REGION_CODE` to the Filesystem region, 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 +``` + +## Cleanup + +Unmount the Filesystem in every worker before terminating it: + +```bash +ti fs unmount-file-system --mount-path "$HOME/corpus" +``` + +After all workers have unmounted the Filesystem, delete it from the trusted machine if you no longer need the dataset: + +```bash +rm -f ./filesystem.json ./worker-*-token.json +ti fs delete-file-system --file-system-id "$TI_FS_FILE_SYSTEM_ID" +``` + +## Security and operational notes + +- Do not distribute the owner token to workers. Generate a separate, short-lived scoped token for each worker so that read-only access is enforced by the credential. +- 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. + +## What's next + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [Use a Filesystem in an Agent Sandbox](/ai/ti/guides/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/guides/ti-persistent-agent-state-example.md b/ai/ti/guides/ti-persistent-agent-state-example.md new file mode 100644 index 0000000000000..983395793e16c --- /dev/null +++ b/ai/ti/guides/ti-persistent-agent-state-example.md @@ -0,0 +1,98 @@ +--- +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 workflow keeps plans, intermediate results, diagnostic files, and workflow history in TiDB Cloud Filesystem while the agent's compute environment remains disposable. A replacement sandbox can resume the task without keeping the previous sandbox alive only to preserve its local disk. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## How it works + +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. + +## Prerequisites + +- Install and configure the TiDB Cloud CLI on a trusted machine. +- Install the TiDB Cloud CLI in each sandbox. +- Install `jq` on the trusted machine. +- Use a secure secret manager or encrypted sandbox input for token transfer. + +## Step 1. Provision the state Filesystem + +On a 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 `TI_FS_TOKEN` in a secret manager, record `FILE_SYSTEM_ID` for cleanup, and record the configured region code. Delete `filesystem.json` after storing these values securely. + +## Step 2. Start the first sandbox + +Inject the following environment variables: + +```bash +export TI_FS_TOKEN="" +export TI_REGION_CODE="" +``` + +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"}' +``` + +The `agent` journal kind classifies this journal as an agent workflow and is the default when `--journal-kind` is omitted. The option accepts a custom string when you need a different workflow classification. + +## 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. + +## Cleanup + +After the sandboxes stop using the Filesystem, delete it from the trusted machine: + +```bash +rm -f ./filesystem.json +ti fs delete-file-system --file-system-id "$FILE_SYSTEM_ID" +``` + +Deleting the Filesystem also deletes its task files and journals. + +## Security and 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. + +## What's next + +- [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/guides/ti-query-sql-with-roles-example.md b/ai/ti/guides/ti-query-sql-with-roles-example.md new file mode 100644 index 0000000000000..f3d148c8821f0 --- /dev/null +++ b/ai/ti/guides/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 workflow prepares three SQL roles once and then explicitly selects the least-privileged role for each statement. Use it for interactive or automated schema, data, and verification work without handling database passwords in every command. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## How it works + +A conventional database connection uses one credential and retains that credential's privileges for the session. By contrast, `ti db create-db-sql-users` creates three stable identities and stores their credentials locally. Each `execute-sql-statement` invocation selects one identity and executes one statement, so an inspection step does not need to retain write or administrator privileges. + +| Role | Use it for | +| --- | --- | +| `admin` | Schema changes and privilege management | +| `read-write` | Application data changes | +| `read-only` | Queries and verification | + +## Prerequisites + +- Configure `ti`. +- Select an active TiDB Cloud Starter instance ID. + +## Step 1. Prepare SQL 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`. + +With `--format env`, the command writes separate `TIDB_` connection variables such as `TIDB_HOST`, `TIDB_USER`, and `TIDB_PASSWORD`. The `--env-include-database-url` option also adds a `DATABASE_URL` value for applications that accept a single MySQL connection URL. + +## 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 SQL execution transport. To open a direct TLS MySQL connection instead, specify `--transport mysql`; the CLI does not switch transports automatically. +- 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/guides/ti-share-filesystem-across-machines-example.md b/ai/ti/guides/ti-share-filesystem-across-machines-example.md new file mode 100644 index 0000000000000..5a0a56b1752ad --- /dev/null +++ b/ai/ti/guides/ti-share-filesystem-across-machines-example.md @@ -0,0 +1,118 @@ +--- +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 workflow gives users, automation, or agents on two machines one shared workspace. Use it when changes must remain visible from both machines without exchanging point-in-time copies through `scp` or archive uploads. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## How it works + +Machine A creates the Filesystem and generates a separate owner token for machine B. Both machines then access the same remote namespace through data-plane commands or a mounted directory, so writes become visible through either interface after they are flushed. This provides shared-directory behavior without manual snapshot synchronization or object-storage-specific transfer logic. + +| Participant | Credentials | Role in the workflow | +| --- | --- | --- | +| Machine A | Configured `ti` profile and its FS owner token | Creates and manages the Filesystem, writes initial data, and generates the token for machine B | +| Machine B | Its own FS owner token and the Filesystem region code | Accesses the Filesystem without TiDB Cloud API keys or a copied profile | +| TiDB Cloud Filesystem | Not applicable | Provides the shared remote namespace used by both machines | + +Using a separate token for each machine lets you revoke machine B without interrupting machine A. Because both tokens grant owner access, transfer and store them as secrets. + +## Prerequisites + +- Machine A has configured `ti`. +- Both machines have `ti` installed. +- Machine A has `jq` 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="" +``` + +Set `TI_REGION_CODE` to the region where the Filesystem was created. 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 + +# Graceful unmount flushes pending writes before the data-plane read. +ti fs unmount-file-system --mount-path /path/to/shared-workspace +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 + +### On machine B + +After the graceful unmount in Step 4, remove the credentials from the current shell: + +```bash +unset TI_FS_TOKEN TI_REGION_CODE +``` + +### On machine A + +```bash +rm -f ./filesystem.json ./machine-b-token.json + +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/guides/ti-agent-sandbox-example.md) diff --git a/ai/ti/guides/ti-vault-agent-secrets-example.md b/ai/ti/guides/ti-vault-agent-secrets-example.md new file mode 100644 index 0000000000000..d6bde80c570ac --- /dev/null +++ b/ai/ti/guides/ti-vault-agent-secrets-example.md @@ -0,0 +1,111 @@ +--- +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 workflow gives an agent temporary access to one secret field without sharing the Filesystem owner token or the complete secret. Use it when an agent needs a credential for one task but should not retain that value in a prompt, `.env` file, or sandbox image. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## How it works + +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. + +## Why use this approach + +Ordinary environment variables and files can deliver a secret, but they do not create a scoped, expiring delegation or an access audit trail. Sharing the Filesystem owner token also grants broader access than one secret field requires. A separate cloud secret manager can provide similar controls, but it requires another identity, policy, and integration path for every sandbox. + +## Prerequisites + +- Select a Filesystem with owner access. +- Install `jq`. +- 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 +umask 077 +set -o noclobber +ti fs-vault create-grant \ + --agent-id example-agent \ + --scope service-demo/ENDPOINT \ + --permission read \ + --ttl 10m \ + --label-hint example > ./vault-grant.json +set +o noclobber + +export TI_VAULT_TOKEN="$(jq -r '.token' ./vault-grant.json)" +export GRANT_ID="$(jq -r '.grant_id' ./vault-grant.json)" +``` + +The protected file captures both one-time values without printing the token. Store the token in a secret manager and retain `GRANT_ID` so that you can revoke the grant. + +## 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 `/n/vault/` prefix identifies the Vault namespace for commands that accept a full secret path; `service-demo` refers to the secret created in Step 1. `run-with-secret` reads the permitted fields, sets them as environment variables in the child process, and then runs the command after `--`. This test exits successfully when `ENDPOINT` is present without printing its value. 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 "$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 ./vault-grant.json +``` + +## Security and operational 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/guides/use-filesystem-journals.md b/ai/ti/guides/use-filesystem-journals.md new file mode 100644 index 0000000000000..e3ea5e7154873 --- /dev/null +++ b/ai/ti/guides/use-filesystem-journals.md @@ -0,0 +1,64 @@ +--- +title: Use TiDB Cloud Filesystem Journals +summary: Learn how to create, append, read, search, and verify append-only journals for agent and automation events in a Filesystem. +--- + +# Use TiDB Cloud Filesystem Journals + +Journals provide append-only, hash-chained event logs for agent workflows and automation pipelines running on a TiDB Cloud Filesystem. Use [`ti fs-journal` commands](/ai/ti/reference/ti-filesystem-journal.md) to create a journal, append ordered events, search or read them, and verify the hash chain. + +## Prerequisites + +- [Install and configure TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md). +- Select a Filesystem by passing `--file-system-id`, setting `TI_FS_FILE_SYSTEM_ID`, or supplying an FS token that identifies the Filesystem. +- Provide an FS token with journal permissions through `--fs-token`, `TI_FS_TOKEN`, or the local credential stored for the selected Filesystem. + +## Create a journal + +```shell +ti fs-journal create-journal \ + --journal-kind agent \ + --title "review task" \ + --actor agent:reviewer +``` + +Save the returned journal ID. + +## Append entries + +```shell +ti fs-journal append-journal-entries \ + --journal-id "" \ + --entry-json '{"type":"review_started"}' +``` + +For supported input forms and entry fields, see the [`append-journal-entries` reference](/ai/ti/reference/ti-fs-journal-append-journal-entries.md). + +## Read and search entries + +Read entries in sequence order: + +```shell +ti fs-journal read-journal-entries --journal-id "" +``` + +Search across journals and entries: + +```shell +ti fs-journal search-journal-entries \ + --entry-type review_started \ + --include-entries +``` + +## Verify a journal + +Verify that the journal's hash chain is intact: + +```shell +ti fs-journal verify-journal --journal-id "" +``` + +## What's next + +- [Record an Agent Workflow in a TiDB Cloud Filesystem Journal](/ai/ti/guides/ti-journal-agent-workflow-example.md) +- [TiDB Cloud Filesystem Journal CLI Command Reference](/ai/ti/reference/ti-filesystem-journal.md) diff --git a/ai/ti/guides/work-with-filesystem-data.md b/ai/ti/guides/work-with-filesystem-data.md new file mode 100644 index 0000000000000..8b75a0708ced6 --- /dev/null +++ b/ai/ti/guides/work-with-filesystem-data.md @@ -0,0 +1,75 @@ +--- +title: Work with TiDB Cloud Filesystem Data +summary: Learn how to copy, read, organize, search, and inspect files and directories in TiDB Cloud Filesystem by using the CLI. +--- + +# Work with TiDB Cloud Filesystem Data + +In TiDB Cloud CLI, you can use [`ti fs` commands](/ai/ti/reference/ti-filesystem.md) to transfer data between local storage and TiDB Cloud Filesystem and to manage its remote namespace. + +## Prerequisites + +- [Install and configure TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md). +- [Create a Filesystem](/ai/ti/guides/manage-filesystem-resources.md) or obtain access to an existing one. +- Select the Filesystem by passing `--file-system-id`, setting `TI_FS_FILE_SYSTEM_ID`, or supplying an FS token that identifies it. Provide an FS token with the permissions required for each operation. + +## Copy data + +Upload a local file to a remote path: + +```shell +ti fs copy-file --from-local ./report.md --to-remote /reports/report.md +``` + +[`copy-file`](/ai/ti/reference/ti-fs-copy-file.md) also supports downloads, streaming, appending, resuming, and recursive copies. + +## Read and inspect data + +Read a file or byte range to standard output: + +```shell +ti fs read-file --path /reports/report.md --offset 0 --length 1024 +``` + +List a directory and inspect one path: + +```shell +ti fs list-files --path /reports --output text +ti fs describe-file --path /reports/report.md +``` + +## Organize the namespace + +Create a directory, move a file, and remove data with the corresponding commands: + +```shell +ti fs create-directory --path /reports/archive +ti fs move-file --from-remote /draft.md --to-remote /reports/final.md +ti fs delete-file --path /scratch --recursive +``` + +You can also use `chmod-file`, `create-symlink`, and `create-hardlink` to manage POSIX-style metadata and links. + +> **Warning:** +> +> `delete-file --recursive` permanently deletes the target directory and its contents. Verify the remote path before you run the command. + +## Search for data + +Search file content below a path: + +```shell +ti fs search-file-content --path /reports --pattern "TODO" +``` + +Find paths by name, type, tags, size, or timestamps: + +```shell +ti fs find-files --path /reports --file-name-pattern "*.md" --tag stage=review +``` + +## What's next + +- [Manage TiDB Cloud Filesystem Layers and Checkpoints](/ai/ti/guides/manage-filesystem-layers.md) +- [Mount a TiDB Cloud Filesystem](/ai/ti/guides/mount-filesystem.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.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..50465b2cf2256 --- /dev/null +++ b/ai/ti/reference/ti-cli-reference.md @@ -0,0 +1,167 @@ +--- +title: TiDB Cloud CLI (`ti`) Command Reference +summary: Reference TiDB Cloud CLI command groups, syntax, global options, output, dry-run behavior, help forms, and errors. +--- + +# TiDB Cloud CLI (`ti`) Command Reference + +This page describes the command structure and behavior shared by [TiDB Cloud CLI (`ti`)](/ai/ti/ti-overview.md) commands. For the syntax and options of an individual command, select its command group or use the documentation navigation. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti [options] [global options] +ti [options] [global options] +``` + +For example: + +```bash +ti configure --profile staging +ti db list-db-clusters --db-cluster-type starter +``` + +The `ti` executable accepts long options only. A one-letter option such as `-p` is rejected. + +In generated usage, specify required options before optional options, and use square brackets to enclose optional options: + +```text +ti db describe-db-cluster + --db-cluster-id + [--output ] + [--view ] +``` + +Value types are enclosed in angle brackets. In command help, `(required)` follows the name and type of each required option: + +```text +--db-cluster-name (required) Starter DB cluster display name +--wait Wait until the created cluster is active +``` + +## Commands and command groups + +Use the following table to find the reference for a top-level command or command group. Each command page includes its syntax, options, and examples. + +| Command or command group | Purpose | Reference | +| --- | --- | --- | +| `configure` | Configure local profiles, API keys, and the default region. | [`ti configure`](/ai/ti/reference/ti-configure.md) | +| `update` | Check for and install TiDB Cloud CLI updates. | [`ti update`](/ai/ti/reference/ti-update.md) | +| `db` | Manage TiDB Cloud Starter instances, branches, SQL users, connections, and SQL statements. | [`ti db` commands](/ai/ti/reference/ti-starter-database.md) | +| `fs` | Manage Filesystem resources, AI providers, tokens, data, layers, and mounts. | [`ti fs` commands](/ai/ti/reference/ti-filesystem.md) | +| `fs-git` | Manage Git workspaces on mounted Filesystems. | [`ti fs-git` commands](/ai/ti/reference/ti-filesystem-git.md) | +| `fs-journal` | Manage verifiable Filesystem journals. | [`ti fs-journal` commands](/ai/ti/reference/ti-filesystem-journal.md) | +| `fs-vault` | Manage Filesystem Vault secrets and delegated access. | [`ti fs-vault` commands](/ai/ti/reference/ti-filesystem-vault.md) | + +To list available commands in the terminal, run `ti help` or `ti help`. + +## 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 default region code for the current command, for example, `aws-us-east-1`. + +Command pages document `--help`, `--version`, and all command-specific options separately. + +## Output + +Commands that return structured data use JSON by default: + +```bash +ti db list-db-clusters --db-cluster-type starter +``` + +Use text output for a human-readable representation: + +```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 that support `--dry-run` validate local options, the profile, credentials, the region, and the request shape, and then report a plan without making the remote mutation. + +```bash +ti db delete-db-cluster \ + --db-cluster-id "" \ + --dry-run +``` + +Read-only commands reject `--dry-run`. The option is not a global simulation option 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 options: + +```bash +ti help +ti db help +ti db create-db-cluster help +ti --help +ti --version +``` + +`help` is a command for navigating the command hierarchy. `--help` is available on each command; both forms intentionally coexist. The `--version` option is also available at each command level and reports the version of the same `ti` executable. + +## 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. + +## Related documentation + +For configuration, security, compatibility, and troubleshooting details, see the following documents: + +| Document | Purpose | +| --- | --- | +| [Install, Configure, and Update TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md) | Install releases, configure profiles, update, and uninstall `ti` | +| [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) | Understand profiles, precedence rules, credentials, and local state | +| [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) | Review supported regions, credential boundaries, platform support, and limitations | +| [Migrate from `tdc` to TiDB Cloud CLI](/ai/ti/reference/ti-migrate-from-tdc.md) | Migrate local state and environment variables from `tdc` v0.1.x | +| [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) | Diagnose configuration, authentication, routing, and command failures | + +## Release notes + +For the latest changes to TiDB Cloud CLI (`ti`), see the [TiDB Cloud CLI (`ti`) Release Notes](https://github.com/tidbcloud/ti-cli/releases). 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..320d960a212cb --- /dev/null +++ b/ai/ti/reference/ti-configuration-and-credentials.md @@ -0,0 +1,247 @@ +--- +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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Main files + +```toml +# ~/.ti/config +[default] +region_code = "aws-us-east-1" +``` + +```toml +# ~/.ti/credentials +[default] +tidb_cloud_public_key = "..." +tidb_cloud_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. `TIDB_CLOUD_PUBLIC_KEY` and `TIDB_CLOUD_PRIVATE_KEY`, when either is set; +2. the selected section of `~/.ti/credentials`. + +Both environment values are required together. `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. TiDB Cloud Starter instance 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. The region-scoped 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. + +Owner FS tokens authorize Filesystem data access and token inventory or lifecycle operations. They do not authorize TiDB Cloud Filesystem resource creation, listing, description, or deletion, and they cannot generate another owner token. Those operations require TiDB Cloud API credentials. `ti fs delete-file-system` additionally requires an explicit `--file-system-id`; the ID embedded in `TI_FS_TOKEN` is never used to select a Filesystem for deletion. + +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 Filesystem inventory, description, provisioning, and deletion require TiDB Cloud API credentials. An FS token is neither required nor accepted as authorization for Filesystem deletion. + +## 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. + +The three access modes map to TiDB Cloud built-in database roles: + +| `ti` access mode | TiDB Cloud built-in role | Intended use | +| --- | --- | --- | +| `read_only` | `role_readonly` | Query and verify data without modifying it | +| `read_write` | `role_readwrite` | Query and modify application data | +| `admin` | `role_admin` | Make schema changes and manage privileges | + +For the complete TiDB Cloud role model, see [Manage Database Users and Roles](/tidb-cloud/configure-sql-users.md). + +## Companion state and mount locators + +The installer includes `ti-drive9`, the companion runtime that executes `ti fs`, `ti fs-git`, `ti fs-journal`, and `ti fs-vault` operations. You do not invoke it directly. 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-configure.md b/ai/ti/reference/ti-configure.md new file mode 100644 index 0000000000000..79434acbff40c --- /dev/null +++ b/ai/ti/reference/ti-configure.md @@ -0,0 +1,71 @@ +--- +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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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`: Avoid prompts. Provide the region code, public key, and private key through the corresponding command options or environment variables. 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). + +## Configuration value sources + +The following command options and environment variables provide the same configuration values: + +| Configuration value | Command option | Environment variable | +| --- | --- | --- | +| Default region code | `--region-code` | `TI_REGION_CODE` | +| TiDB Cloud API public key | `--tidb-cloud-public-key` | `TIDB_CLOUD_PUBLIC_KEY` | +| TiDB Cloud API private key | `--tidb-cloud-private-key` | `TIDB_CLOUD_PRIVATE_KEY` | + +For each value, an explicitly provided command option takes precedence over its environment variable. With `--non-interactive`, all three values must resolve from these sources. + +## 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) +- [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) diff --git a/ai/ti/reference/ti-db-create-db-cluster-branch.md b/ai/ti/reference/ti-db-create-db-cluster-branch.md new file mode 100644 index 0000000000000..d1a9ca7467083 --- /dev/null +++ b/ai/ti/reference/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 TiDB Cloud Starter instance. `--wait` waits for the branch to become `ACTIVE`. The command verifies that the parent cluster is Starter before creating the branch. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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/ti-db-create-db-cluster.md b/ai/ti/reference/ti-db-create-db-cluster.md new file mode 100644 index 0000000000000..e6174a766b02b --- /dev/null +++ b/ai/ti/reference/ti-db-create-db-cluster.md @@ -0,0 +1,85 @@ +--- +title: ti db create-db-cluster +summary: Create a TiDB Cloud Starter cluster. +--- + +# ti db create-db-cluster + +Creates a TiDB Cloud Starter instance. The required `--db-cluster-type` must be `starter`; there is no implicit type. `--wait` waits for the cluster to become `ACTIVE`. + +The request does not select a project. TiDB Cloud assigns the instance according to its server-side project rules, and `ti` preserves any project metadata in the response. You cannot select or configure a project through `ti`. + +The TiDB Cloud CLI validates the returned service plan. If verification fails after creation is accepted, `ti` reports the cluster ID and retains the instance for inspection. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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. If omitted, `ti` does not send a spending limit, and TiDB Cloud applies its default rules. For details, see [Manage Spending Limit for TiDB Cloud Starter Instances](/tidb-cloud/manage-serverless-spend-limit.md). +- `--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 TiDB Cloud Starter instance 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 TiDB Cloud Starter instance 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 + ``` + +## If post-creation verification fails + +If TiDB Cloud accepts the creation request but `ti` cannot verify the returned resource as a Starter instance, note the cluster ID in the error. Inspect the retained resource with: + +```bash +ti db describe-db-cluster --db-cluster-id "" +``` + +If `ti` still cannot verify the service plan, inspect or delete the resource in the TiDB Cloud console. Do not repeat the create command until you determine whether the first request created an instance. + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/ti-db-create-db-sql-users.md b/ai/ti/reference/ti-db-create-db-sql-users.md new file mode 100644 index 0000000000000..4044d59fdaacb --- /dev/null +++ b/ai/ti/reference/ti-db-create-db-sql-users.md @@ -0,0 +1,63 @@ +--- +title: ti db create-db-sql-users +summary: Create TiDB Cloud CLI-managed SQL users for a TiDB Cloud Starter instance. +--- + +# ti db create-db-sql-users + +Creates or repairs three `ti`-managed SQL users for a TiDB Cloud Starter instance: read-only, read-write, and admin. It stores their credentials locally so that later commands can select the appropriate user with `--read-only`, `--read-write`, or `--admin`. + +These users have the following predefined access levels and built-in TiDB Cloud roles: + +| `ti` access mode | TiDB Cloud built-in role | Intended use | +| --- | --- | --- | +| `read_only` | `role_readonly` | Query and verify data without modifying it | +| `read_write` | `role_readwrite` | Query and modify application data | +| `admin` | `role_admin` | Make schema changes and manage privileges | + +For the TiDB Cloud role model, see [Manage Database Users and Roles](/tidb-cloud/configure-sql-users.md). + +`ti` stores the generated usernames and passwords in `~/.ti/db_users//credentials`, with separate TOML sections for the three access modes. On systems that support POSIX permissions, the credentials file is readable and writable only by its owner. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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/ti-db-delete-db-cluster-branch.md b/ai/ti/reference/ti-db-delete-db-cluster-branch.md new file mode 100644 index 0000000000000..bfbce68abfa44 --- /dev/null +++ b/ai/ti/reference/ti-db-delete-db-cluster-branch.md @@ -0,0 +1,48 @@ +--- +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 TiDB Cloud Starter instance. The command verifies that the parent cluster is Starter before reading or deleting the branch. It returns the delete response without polling; this command does not provide a `--wait` option. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 TiDB Cloud Starter instance. + ti db delete-db-cluster-branch --db-cluster-id "" --db-cluster-branch-id "" + ``` + +To verify that the branch no longer appears, run `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/ti-db-delete-db-cluster.md b/ai/ti/reference/ti-db-delete-db-cluster.md new file mode 100644 index 0000000000000..659ea7ac2981f --- /dev/null +++ b/ai/ti/reference/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 a TiDB Cloud Starter instance. Use `--wait` to wait until deletion completes. This command only accepts TiDB Cloud Starter instances and rejects other cluster types. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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`: After TiDB Cloud accepts the deletion request, poll until the instance reaches `DELETED`. A subsequent `not found` or `permission denied` response is also treated as completed deletion because the instance is no longer readable. + +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/ti-db-describe-db-cluster-branch.md b/ai/ti/reference/ti-db-describe-db-cluster-branch.md new file mode 100644 index 0000000000000..edd8a6c74f532 --- /dev/null +++ b/ai/ti/reference/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 default `FULL` view returns the complete branch details available from the TiDB Cloud API; use `--view BASIC` to request only basic information. The command verifies that the parent cluster is Starter before reading the branch. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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`. If omitted, the TiDB Cloud API uses `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/ti-db-describe-db-cluster.md b/ai/ti/reference/ti-db-describe-db-cluster.md new file mode 100644 index 0000000000000..e6e2c3c4a59d6 --- /dev/null +++ b/ai/ti/reference/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 + +Gets information about a TiDB Cloud Starter instance. The default `BASIC` view returns basic instance information. Use `--view FULL` to request the complete details available from the TiDB Cloud API. The command rejects the cluster if its API metadata does not verify it as Starter. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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`. If omitted, the TiDB Cloud API uses `BASIC`. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Get information about a TiDB Cloud Starter instance: + + ```bash + # Return the instance 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/ti-db-execute-sql-statement.md b/ai/ti/reference/ti-db-execute-sql-statement.md new file mode 100644 index 0000000000000..84237197ae238 --- /dev/null +++ b/ai/ti/reference/ti-db-execute-sql-statement.md @@ -0,0 +1,87 @@ +--- +title: ti db execute-sql-statement +summary: Execute one SQL statement against a TiDB Cloud Starter cluster. +--- + +# ti db execute-sql-statement + +Executes one SQL statement against a TiDB Cloud Starter instance. The default access role is read-write; specifying a role explicitly is recommended. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 direct TLS MySQL connection when the workflow requires the MySQL protocol. + ti db execute-sql-statement --db-cluster-id "" --transport mysql --sql "SELECT CURRENT_TIMESTAMP" + ``` + +## Choose a transport + +The default `https` transport sends the statement to the TiDB Cloud HTTPS SQL API. The `mysql` transport opens a direct TLS MySQL connection to the instance, executes the statement once, and closes the connection. Use `mysql` only when your network or workflow specifically requires the MySQL protocol. + +The CLI does not automatically fall back from `https` to `mysql` or retry a statement through the other transport. This prevents a write statement from being executed twice after an ambiguous failure. + +## Output + +JSON output contains `fields`, `rows`, `row_count`, `rows_affected` when applicable, `last_insert_id` when applicable, `transport`, `access_mode`, and `cluster_id`. Each item in `rows` is an object keyed by column name. + +With `--output text`, query results are rendered as a table with column headings and a row count. Statements that do not return rows produce a `Query OK` message with the affected-row count and, when available, the last insert ID. + +## Related documentation + +- [TiDB Cloud Starter CLI Command Reference](/ai/ti/reference/ti-starter-database.md) diff --git a/ai/ti/reference/ti-db-format-db-connection-string.md b/ai/ti/reference/ti-db-format-db-connection-string.md new file mode 100644 index 0000000000000..186e165a5abf9 --- /dev/null +++ b/ai/ti/reference/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. If you do not specify a role option, the command uses `read_write`. The command verifies that the cluster is Starter before loading its local SQL credentials. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 "" --read-write --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/ti-db-list-db-cluster-branches.md b/ai/ti/reference/ti-db-list-db-cluster-branches.md new file mode 100644 index 0000000000000..9e4d998225883 --- /dev/null +++ b/ai/ti/reference/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 TiDB Cloud Starter instance, with optional pagination. The command verifies that the parent cluster is Starter before listing branches. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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. If omitted or set to `0`, the API returns at most `10`. The API maximum is `100`; values greater than `100` are set to `100`. +- `--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 TiDB Cloud Starter instance. + 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/ti-db-list-db-clusters.md b/ai/ti/reference/ti-db-list-db-clusters.md new file mode 100644 index 0000000000000..66bed8122382b --- /dev/null +++ b/ai/ti/reference/ti-db-list-db-clusters.md @@ -0,0 +1,87 @@ +--- +title: ti db list-db-clusters +summary: List TiDB Cloud Starter clusters. +--- + +# ti db list-db-clusters + +Lists TiDB Cloud Starter instances in the selected region, with optional pagination, filtering, ordering, and JMESPath projection. The required `--db-cluster-type` must be `starter`. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 `: TiDB Cloud Starter API filter expression. The API supports Google AIP-style `=` and `AND` expressions for `region.provider`, `region.name`, `state`, `projectId`, `clusterId`, `displayName`, and `labels.`. +- `--help`: Display help information. +- `--order-by `: TiDB Cloud Starter API `orderBy` expression. `ti` passes this value to the API without interpreting it. +- `--page-size `: Number of verified clusters to return. If omitted or set to `0`, the default is `10`. 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 TiDB Cloud Starter instances 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}' + ``` + +- Filter active clusters: + + ```bash + # Combine this filter with the mandatory effective-region filter. + ti db list-db-clusters --db-cluster-type starter --filter 'state="ACTIVE"' + ``` + +## Region resolution + +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. + +Cross-region and non-Starter instances are omitted. An instance is also omitted if missing or conflicting service-plan or region information prevents `ti` from verifying that it is a Starter instance in the selected region. + +## Filter and ordering behavior + +`ti` passes the user-supplied filter and ordering expressions to the TiDB Cloud Starter API. Invalid or unsupported expressions are rejected by the API. For the API contract, see [TiDB Cloud API v1beta1 Overview](/api/tidb-cloud-api-v1beta1.md). + +## Page token reuse + +The command can retrieve multiple TiDB Cloud API pages to fill one result page and returns a `ti` `next_page_token`. It omits the API `total_size`, which can include resources outside the verified result. + +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/ti-db-update-db-cluster.md b/ai/ti/reference/ti-db-update-db-cluster.md new file mode 100644 index 0000000000000..a19fa9959899f --- /dev/null +++ b/ai/ti/reference/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 a TiDB Cloud Starter instance. At least one of `--db-cluster-name` or `--monthly-spending-limit-usd-cents` is required. This command only accepts Starter instances. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 TiDB Cloud Starter instance 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/ti-filesystem-git.md b/ai/ti/reference/ti-filesystem-git.md new file mode 100644 index 0000000000000..d5567ac92c7cb --- /dev/null +++ b/ai/ti/reference/ti-filesystem-git.md @@ -0,0 +1,22 @@ +--- +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. Continue to use ordinary `git` commands for status, edit, add, commit, fetch, and push. + +## Commands + +| Command | Description | +|---|---| +| [`clone-git-workspace`](/ai/ti/reference/ti-fs-git-clone-git-workspace.md) | Clones a repository into a mounted Filesystem path. | +| [`hydrate-git-workspace`](/ai/ti/reference/ti-fs-git-hydrate-git-workspace.md) | Materializes clean Git data for an existing fast or blobless workspace. | +| [`add-git-worktree`](/ai/ti/reference/ti-fs-git-add-git-worktree.md) | Creates a linked worktree from a base workspace. | +| [`remove-git-worktree`](/ai/ti/reference/ti-fs-git-remove-git-worktree.md) | Removes a linked worktree. | + +## See also + +- [Manage Git Workspaces on TiDB Cloud Filesystem](/ai/ti/guides/manage-git-workspaces.md) +- [Prepare a Git Workspace for Agents on TiDB Cloud Filesystem](/ai/ti/guides/ti-git-workspace-for-agents-example.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..9e721d7129301 --- /dev/null +++ b/ai/ti/reference/ti-filesystem-journal.md @@ -0,0 +1,23 @@ +--- +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. + +## Commands + +| Command | Description | +|---|---| +| [`create-journal`](/ai/ti/reference/ti-fs-journal-create-journal.md) | Creates a journal. | +| [`append-journal-entries`](/ai/ti/reference/ti-fs-journal-append-journal-entries.md) | Appends events to a journal. | +| [`read-journal-entries`](/ai/ti/reference/ti-fs-journal-read-journal-entries.md) | Reads journal entries in sequence order. | +| [`search-journal-entries`](/ai/ti/reference/ti-fs-journal-search-journal-entries.md) | Searches journals and entries. | +| [`verify-journal`](/ai/ti/reference/ti-fs-journal-verify-journal.md) | Verifies the journal hash chain. | + +## See also + +- [Use TiDB Cloud Filesystem Journals](/ai/ti/guides/use-filesystem-journals.md) +- [Record an Agent Workflow in a TiDB Cloud Filesystem Journal](/ai/ti/guides/ti-journal-agent-workflow-example.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..cece96304ca50 --- /dev/null +++ b/ai/ti/reference/ti-filesystem-vault.md @@ -0,0 +1,31 @@ +--- +title: TiDB Cloud Filesystem Vault CLI Command Reference +summary: Reference every `ti fs-vault` command for secrets, delegated access, audit events, process injection, and mounts. +--- + +# TiDB Cloud Filesystem Vault CLI Command Reference + +Use `ti fs-vault` to manage secrets and delegated access in TiDB Cloud Filesystem. + +Most secret-management commands identify a secret by its name, such as `db-prod`. `replace-secret` and `run-with-secret` instead require its canonical Vault path, `/n/vault/`. `/n/vault/` is the root of the Vault namespace, so `/n/vault/db-prod` and the secret name `db-prod` identify the same secret. + +## Commands + +| Command | Description | +|---|---| +| [`create-secret`](/ai/ti/reference/ti-fs-vault-create-secret.md) | Creates a secret. | +| [`replace-secret`](/ai/ti/reference/ti-fs-vault-replace-secret.md) | Replaces a secret. | +| [`read-secret`](/ai/ti/reference/ti-fs-vault-read-secret.md) | Reads a secret. | +| [`list-secrets`](/ai/ti/reference/ti-fs-vault-list-secrets.md) | Lists secrets. | +| [`delete-secret`](/ai/ti/reference/ti-fs-vault-delete-secret.md) | Deletes a secret. | +| [`create-grant`](/ai/ti/reference/ti-fs-vault-create-grant.md) | Delegates limited access to a secret. | +| [`delete-grant`](/ai/ti/reference/ti-fs-vault-delete-grant.md) | Revokes delegated access. | +| [`list-audit-events`](/ai/ti/reference/ti-fs-vault-list-audit-events.md) | Lists Vault audit events. | +| [`run-with-secret`](/ai/ti/reference/ti-fs-vault-run-with-secret.md) | Injects a secret into a process. | +| [`mount-vault`](/ai/ti/reference/ti-fs-vault-mount-vault.md) | Mounts a read-only Vault view. | +| [`unmount-vault`](/ai/ti/reference/ti-fs-vault-unmount-vault.md) | Unmounts a Vault view. | + +## See also + +- [Manage TiDB Cloud Filesystem Vault Secrets](/ai/ti/guides/manage-filesystem-vault-secrets.md) +- [Delegate TiDB Cloud Filesystem Vault Secrets to an Agent](/ai/ti/guides/ti-vault-agent-secrets-example.md) diff --git a/ai/ti/reference/ti-filesystem.md b/ai/ti/reference/ti-filesystem.md new file mode 100644 index 0000000000000..efa09ce87b292 --- /dev/null +++ b/ai/ti/reference/ti-filesystem.md @@ -0,0 +1,135 @@ +--- +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. + +In command syntax, square brackets (`[]`) enclose optional items. Parentheses group required choices, and a vertical bar (`|`) separates alternatives. For example, `(--ttl | --no-expiration)` means that you must specify exactly one of the two options. + +## Resource and token commands + +| Command | Description | +| --- | --- | +| [`create-file-system`](/ai/ti/reference/ti-fs-create-file-system.md) | Creates a Filesystem and its initial owner token. | +| [`list-file-systems`](/ai/ti/reference/ti-fs-list-file-systems.md) | Lists Filesystems in the effective region. | +| [`describe-file-system`](/ai/ti/reference/ti-fs-describe-file-system.md) | Describes one Filesystem by ID. | +| [`check-file-system`](/ai/ti/reference/ti-fs-check-file-system.md) | Checks Filesystem selection, routing, credentials, and data-plane access. | +| [`delete-file-system`](/ai/ti/reference/ti-fs-delete-file-system.md) | Permanently deletes a Filesystem. | +| [`import-file-system-token`](/ai/ti/reference/ti-fs-import-file-system-token.md) | Imports and selects an existing Filesystem token locally. | +| [`generate-file-system-token`](/ai/ti/reference/ti-fs-generate-file-system-token.md) | Generates an additional owner token. | +| [`generate-file-system-scoped-token`](/ai/ti/reference/ti-fs-generate-file-system-scoped-token.md) | Generates a token limited by path, operation, and lifetime. | +| [`list-file-system-tokens`](/ai/ti/reference/ti-fs-list-file-system-tokens.md) | Lists non-secret token metadata. | +| [`enable-file-system-token`](/ai/ti/reference/ti-fs-enable-file-system-token.md) | Re-enables a disabled token. | +| [`disable-file-system-token`](/ai/ti/reference/ti-fs-disable-file-system-token.md) | Temporarily disables a token. | +| [`delete-file-system-token`](/ai/ti/reference/ti-fs-delete-file-system-token.md) | Permanently revokes a token. | +| [`refresh-file-system-token`](/ai/ti/reference/ti-fs-refresh-file-system-token.md) | Rotates a token and returns its replacement once. | + +### Token-management authorization + +When an owner token authorizes token management, it can list tokens, create scoped tokens, and revoke either owner or scoped tokens. It can enable or disable scoped tokens only. TiDB Cloud API credentials can enable, disable, or revoke either token kind. + +## AI provider configuration commands + +These commands configure optional providers for extracting content from media files and generating embeddings. Ordinary Filesystem resource and file operations do not require AI provider configuration. + +| Command | Description | +| --- | --- | +| [`describe-file-system-extract-configuration`](/ai/ti/reference/ti-fs-describe-file-system-extract-configuration.md) | Describes the media extraction provider configuration. | +| [`update-file-system-extract-configuration`](/ai/ti/reference/ti-fs-update-file-system-extract-configuration.md) | Updates the provider used to extract media content. | +| [`describe-file-system-embedding-configuration`](/ai/ti/reference/ti-fs-describe-file-system-embedding-configuration.md) | Describes the embedding provider configuration. | +| [`update-file-system-embedding-configuration`](/ai/ti/reference/ti-fs-update-file-system-embedding-configuration.md) | Updates the provider used to generate embeddings. | + +## Data and namespace commands + +| Command | Description | +| --- | --- | +| [`copy-file`](/ai/ti/reference/ti-fs-copy-file.md) | Copies files between local storage and a Filesystem, or within a Filesystem. | +| [`read-file`](/ai/ti/reference/ti-fs-read-file.md) | Reads a remote file or byte range. | +| [`list-files`](/ai/ti/reference/ti-fs-list-files.md) | Lists entries under a remote path. | +| [`describe-file`](/ai/ti/reference/ti-fs-describe-file.md) | Describes a remote file or directory. | +| [`move-file`](/ai/ti/reference/ti-fs-move-file.md) | Moves or renames a remote path. | +| [`delete-file`](/ai/ti/reference/ti-fs-delete-file.md) | Deletes a remote file or directory. | +| [`create-directory`](/ai/ti/reference/ti-fs-create-directory.md) | Creates a remote directory. | +| [`chmod-file`](/ai/ti/reference/ti-fs-chmod-file.md) | Changes POSIX-style mode metadata. | +| [`create-symlink`](/ai/ti/reference/ti-fs-create-symlink.md) | Creates a symbolic link. | +| [`create-hardlink`](/ai/ti/reference/ti-fs-create-hardlink.md) | Creates a hard link. | +| [`search-file-content`](/ai/ti/reference/ti-fs-search-file-content.md) | Searches extracted file content and descriptions. | +| [`find-files`](/ai/ti/reference/ti-fs-find-files.md) | Finds files by name, tag, date, size, or type. | + +## Layer and portability commands + +| Command | Description | +| --- | --- | +| [`create-layer`](/ai/ti/reference/ti-fs-create-layer.md) | Creates an isolated writable layer. | +| [`list-layers`](/ai/ti/reference/ti-fs-list-layers.md) | Lists layers in a Filesystem. | +| [`fork-layer`](/ai/ti/reference/ti-fs-fork-layer.md) | Forks a child layer from a parent tip or checkpoint. | +| [`list-layer-chain`](/ai/ti/reference/ti-fs-list-layer-chain.md) | Lists the pinned ancestry of a layer. | +| [`describe-layer`](/ai/ti/reference/ti-fs-describe-layer.md) | Describes a layer by ID. | +| [`diff-layer`](/ai/ti/reference/ti-fs-diff-layer.md) | Lists changes recorded in a layer. | +| [`create-layer-checkpoint`](/ai/ti/reference/ti-fs-create-layer-checkpoint.md) | Creates a durable checkpoint in a layer. | +| [`delete-layer`](/ai/ti/reference/ti-fs-delete-layer.md) | Logically abandons a layer. | +| [`rollback-layer`](/ai/ti/reference/ti-fs-rollback-layer.md) | Rolls a layer back without committing its changes. | +| [`commit-layer`](/ai/ti/reference/ti-fs-commit-layer.md) | Applies a layer's changes to the base Filesystem. | +| [`pack-file-system`](/ai/ti/reference/ti-fs-pack-file-system.md) | Archives selected local overlay state to the Filesystem. | +| [`unpack-file-system`](/ai/ti/reference/ti-fs-unpack-file-system.md) | Restores local overlay state from an archive. | + +### Layer references + +A layer reference can be a layer ID, a unique layer name, or a tag reference in the form `tag:=`, for example `tag:run=123`. Because names and tag references can be ambiguous, use layer IDs in automation. + +### Mount profiles and local overlays + +A local overlay stores files that a mount profile keeps on the local machine instead of in the remote namespace. Mount profiles define which paths use that overlay: + +| Mount profile | Behavior | +| --- | --- | +| `coding-agent` | Keeps version-control metadata, dependency directories, caches, build output, and common temporary paths in the local overlay. It does not select automatic pack paths. | +| `portable` | Uses the same local-path rules as `coding-agent` and packs or unpacks the complete overlay by default, so you can move it between machines or sandbox sessions. | +| `none` | Disables local-overlay path routing and automatic pack or unpack behavior. | + +## Mount commands + +| Command | Description | +| --- | --- | +| [`mount-file-system`](/ai/ti/reference/ti-fs-mount-file-system.md) | Mounts a Filesystem at a local path. | +| [`drain-file-system`](/ai/ti/reference/ti-fs-drain-file-system.md) | Flushes pending writes from a live FUSE mount. | +| [`unmount-file-system`](/ai/ti/reference/ti-fs-unmount-file-system.md) | Flushes and unmounts a Filesystem. | + +## Command aliases + +The following `ti fs` commands have Unix-style aliases. For example, `ti fs cp` is equivalent to `ti fs copy-file`. Commands not listed in the table, including `pack-file-system` and `unpack-file-system`, do not have aliases. + +| 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 options, authentication, output, query, and error behavior as canonical commands. + +## See also + +- [Manage TiDB Cloud Filesystem Resources](/ai/ti/guides/manage-filesystem-resources.md) +- [Configure TiDB Cloud Filesystem AI Providers](/ai/ti/guides/configure-filesystem-ai-providers.md) +- [Manage TiDB Cloud Filesystem Tokens](/ai/ti/guides/manage-filesystem-tokens.md) +- [Work with TiDB Cloud Filesystem Data](/ai/ti/guides/work-with-filesystem-data.md) +- [Manage Filesystem Layers and Checkpoints](/ai/ti/guides/manage-filesystem-layers.md) +- [Mount a TiDB Cloud Filesystem](/ai/ti/guides/mount-filesystem.md) +- [Manage Git Workspaces on TiDB Cloud Filesystem](/ai/ti/guides/manage-git-workspaces.md) +- [Use TiDB Cloud Filesystem Journals](/ai/ti/guides/use-filesystem-journals.md) +- [Manage TiDB Cloud Filesystem Vault Secrets](/ai/ti/guides/manage-filesystem-vault-secrets.md) diff --git a/ai/ti/reference/ti-fs-check-file-system.md b/ai/ti/reference/ti-fs-check-file-system.md new file mode 100644 index 0000000000000..d89707de83239 --- /dev/null +++ b/ai/ti/reference/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 + +Verifies that the selected Filesystem is correctly configured and accessible, including its region, credentials, and file access. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-chmod-file.md b/ai/ti/reference/ti-fs-chmod-file.md new file mode 100644 index 0000000000000..6aad6c955dca2 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-commit-layer.md b/ai/ti/reference/ti-fs-commit-layer.md new file mode 100644 index 0000000000000..19b9e8b43f62e --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-copy-file.md b/ai/ti/reference/ti-fs-copy-file.md new file mode 100644 index 0000000000000..2f7a125a92ac2 --- /dev/null +++ b/ai/ti/reference/ti-fs-copy-file.md @@ -0,0 +1,121 @@ +--- +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`. + +Specify exactly one of the following source and destination pairs: + +| Source | Destination | +| --- | --- | +| `--from-local` | `--to-remote` | +| `--from-stdin` | `--to-remote` | +| `--from-remote` | `--to-local` | +| `--from-remote` | `--to-stdout` | +| `--from-remote` | `--to-remote` | + +`--append` supports only `--from-local` with `--to-remote`. It does not support standard input or remote sources. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--help`: Display help information. +- `--layer-id `: Write one copied file into a file system layer instead of the base file system. Cannot be combined with `--recursive`. +- `--overwrite`: Replace an existing destination file. +- `--recursive`: Copy directory structure recursively. Cannot be combined with `--layer-id`; seed a layer directory through a writable FUSE mount instead. +- `--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/ti-fs-create-directory.md b/ai/ti/reference/ti-fs-create-directory.md new file mode 100644 index 0000000000000..5dd081c41c516 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-create-file-system.md b/ai/ti/reference/ti-fs-create-file-system.md new file mode 100644 index 0000000000000..cfe03b6cdfac6 --- /dev/null +++ b/ai/ti/reference/ti-fs-create-file-system.md @@ -0,0 +1,72 @@ +--- +title: ti fs create-file-system +summary: Create a TiDB Cloud Filesystem. +--- + +# ti fs create-file-system + +Creates a Filesystem and returns its ID and owner token. The CLI stores and selects the token in the current profile. Use `--wait` to wait until the Filesystem is ready for use. + +You can optionally set a display name and labels. These values appear in `list-file-systems` and `describe-file-system` output but do not select the Filesystem in later commands. + +> **Important:** +> +> The service does not reveal the initial owner token again. If the CLI warns that it could not store the token, save the returned value before closing the terminal. If the local credential is later lost, use TiDB Cloud API credentials with [`ti fs generate-file-system-token`](/ai/ti/reference/ti-fs-generate-file-system-token.md) to create a replacement owner token. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs create-file-system + [--display-name ] + [--dry-run] + [--help] + [--label ] + [--version] + [--wait] +``` + +## Options + +- `--display-name `: Set a display name between 4 and 64 characters shown by Filesystem inventory commands. The value does not select the Filesystem in later commands. +- `--dry-run`: Validate the request without applying changes. +- `--help`: Display help information. +- `--label `: Add an organization-visible `key=value` label. Repeat this option to add up to 30 labels. Do not put secrets or personal data in labels. +- `--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 \ + --display-name agent-workspace \ + --label environment=development \ + --label team=ai \ + --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/ti-fs-create-hardlink.md b/ai/ti/reference/ti-fs-create-hardlink.md new file mode 100644 index 0000000000000..de7e3dc4a6115 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-create-layer-checkpoint.md b/ai/ti/reference/ti-fs-create-layer-checkpoint.md new file mode 100644 index 0000000000000..3a22c806fbf68 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-create-layer.md b/ai/ti/reference/ti-fs-create-layer.md new file mode 100644 index 0000000000000..6f9175ddc1439 --- /dev/null +++ b/ai/ti/reference/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 a layer for recording isolated changes over a Filesystem base path. If `--layer-id` is omitted, the service generates one. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 `: Set the layer durability mode. The only explicitly supported value is `restore-safe`, which preserves changes in the remote layer so the layer can be restored after the local environment ends. If omitted, the service uses `restore-safe`. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-create-symlink.md b/ai/ti/reference/ti-fs-create-symlink.md new file mode 100644 index 0000000000000..d9c3538baaa2e --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-delete-file-system-token.md b/ai/ti/reference/ti-fs-delete-file-system-token.md new file mode 100644 index 0000000000000..2eba42e4a74cc --- /dev/null +++ b/ai/ti/reference/ti-fs-delete-file-system-token.md @@ -0,0 +1,60 @@ +--- +title: ti fs delete-file-system-token +summary: Permanently revoke a TiDB Cloud Filesystem token. +--- + +# ti fs delete-file-system-token + +Permanently revokes a Filesystem token. The token stops authenticating after the change propagates and no longer appears in list results. An owner token can revoke either token kind in the same Filesystem; a scoped token cannot use this command. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs delete-file-system-token + --token-id + [--file-system-id ] + [--fs-token ] + [--dry-run] + [--help] + [--version] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. Required when using TiDB Cloud API credentials; optional when an owner token supplies the ID. +- `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--fs-token `: Authorize the request with an owner Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. If no Filesystem token is available, the command uses the configured TiDB Cloud API keys. +- `--dry-run`: Validate credentials, identifiers, and known local mount conflicts without revoking the 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 + +- 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 "" + ``` + +- Revoke a token by using an owner token: + + ```bash + # The owner token identifies the Filesystem; use the immutable ID of the token being revoked. + TI_FS_TOKEN="" ti fs delete-file-system-token \ + --token-id "" + ``` + +## Related documentation + +- [Token-management authorization](/ai/ti/reference/ti-filesystem.md#token-management-authorization) +- [`ti fs generate-file-system-token`](/ai/ti/reference/ti-fs-generate-file-system-token.md) +- [`ti fs disable-file-system-token`](/ai/ti/reference/ti-fs-disable-file-system-token.md) diff --git a/ai/ti/reference/ti-fs-delete-file-system.md b/ai/ti/reference/ti-fs-delete-file-system.md new file mode 100644 index 0000000000000..744df92789464 --- /dev/null +++ b/ai/ti/reference/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 + +Starts deleting a Filesystem. Deletion runs asynchronously after the command returns. You must specify `--file-system-id`; display names, labels, and Filesystem tokens cannot identify a Filesystem for deletion. This command requires TiDB Cloud API credentials. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs delete-file-system + --file-system-id + [--dry-run] + [--help] + [--version] +``` + +## Options + +- `--file-system-id `: Set the immutable Filesystem ID. FS tokens cannot replace this option or authorize Filesystem deletion. \[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/ti-fs-delete-file.md b/ai/ti/reference/ti-fs-delete-file.md new file mode 100644 index 0000000000000..812c77eee7fbb --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-delete-layer.md b/ai/ti/reference/ti-fs-delete-layer.md new file mode 100644 index 0000000000000..f241384d7e5db --- /dev/null +++ b/ai/ti/reference/ti-fs-delete-layer.md @@ -0,0 +1,58 @@ +--- +title: ti fs delete-layer +summary: Abandon a TiDB Cloud Filesystem layer. +--- + +# ti fs delete-layer + +Abandons a layer without erasing its history. If the layer has live descendants, the command fails unless you specify `--cascade`, which abandons the descendants first. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs delete-layer + --layer-ref + [--cascade] + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--layer-ref `: Layer ID, unique name, or [tag reference](/ai/ti/reference/ti-filesystem.md#layer-references). \[required] +- `--cascade`: Abandon live descendants before abandoning the selected layer. +- `--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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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 + +- Abandon a rejected leaf timeline: + + ```bash + # Deletion fails when the selected layer still has live descendants. + ti fs delete-layer --file-system-id --layer-ref experiment-a + ``` + +- Abandon a test-owned subtree: + + ```bash + # Cascade is explicit and abandons descendants before the selected layer. + ti fs delete-layer --file-system-id --layer-ref experiment-root --cascade + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [`ti fs list-layer-chain`](/ai/ti/reference/ti-fs-list-layer-chain.md) diff --git a/ai/ti/reference/ti-fs-describe-file-system-embedding-configuration.md b/ai/ti/reference/ti-fs-describe-file-system-embedding-configuration.md new file mode 100644 index 0000000000000..5b0d7e28285a4 --- /dev/null +++ b/ai/ti/reference/ti-fs-describe-file-system-embedding-configuration.md @@ -0,0 +1,45 @@ +--- +title: ti fs describe-file-system-embedding-configuration +summary: Describe embedding configuration for a TiDB Cloud Filesystem. +--- + +# ti fs describe-file-system-embedding-configuration + +Shows the embedding configuration for a Filesystem. This configuration is optional and does not affect normal Filesystem operations when it is not customized. This command requires TiDB Cloud API credentials and does not use a Filesystem token. + +The `source` field reports whether the configuration is `custom`, `default`, `none`, or `database_auto`. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs describe-file-system-embedding-configuration + --file-system-id + [--help] + [--version] +``` + +## Options + +- `--file-system-id `: Set the immutable Filesystem 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 + +- Inspect effective embedding configuration: + + ```bash + # Show provider metadata, masked credentials, source, and generation. + ti fs describe-file-system-embedding-configuration \ + --file-system-id + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/ti-fs-describe-file-system-extract-configuration.md b/ai/ti/reference/ti-fs-describe-file-system-extract-configuration.md new file mode 100644 index 0000000000000..9da109fa37ecd --- /dev/null +++ b/ai/ti/reference/ti-fs-describe-file-system-extract-configuration.md @@ -0,0 +1,57 @@ +--- +title: ti fs describe-file-system-extract-configuration +summary: Describe media extraction configuration for a TiDB Cloud Filesystem. +--- + +# ti fs describe-file-system-extract-configuration + +Shows the image, audio, or video extraction configuration for a Filesystem. This configuration is optional and does not affect normal Filesystem operations when it is not customized. This command requires TiDB Cloud API credentials and does not use a Filesystem token. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs describe-file-system-extract-configuration + --file-system-id + --media-type + [--help] + [--version] +``` + +## Options + +- `--file-system-id `: Set the immutable Filesystem ID. \[required] +- `--media-type `: Select `image`, `audio`, or `video`. \[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 + +- Inspect image extraction: + + ```bash + # Show whether image extraction uses a custom, default, or absent provider configuration. + ti fs describe-file-system-extract-configuration \ + --file-system-id \ + --media-type image + ``` + +- Print only the effective provider source: + + ```bash + # Return custom, default, or none for use in a script. + ti fs describe-file-system-extract-configuration \ + --file-system-id \ + --media-type audio \ + --query source \ + --output text + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/ti-fs-describe-file-system.md b/ai/ti/reference/ti-fs-describe-file-system.md new file mode 100644 index 0000000000000..c178e68b9e8a8 --- /dev/null +++ b/ai/ti/reference/ti-fs-describe-file-system.md @@ -0,0 +1,44 @@ +--- +title: ti fs describe-file-system +summary: Describe a remote TiDB Cloud Filesystem. +--- + +# ti fs describe-file-system + +Shows detailed information about a Filesystem, including its display name, labels, placement, status, quota, and usage. This command requires TiDB Cloud API credentials and does not use a Filesystem token. + +The output includes `has_local_token`, which indicates whether this machine has a matching local token. When available, quota data includes media and video extraction limits and usage. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs describe-file-system + --file-system-id + [--help] + [--version] +``` + +## Options + +- `--file-system-id `: Set the immutable Filesystem 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/ti-fs-describe-file.md b/ai/ti/reference/ti-fs-describe-file.md new file mode 100644 index 0000000000000..8452410fdeeef --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-describe-layer.md b/ai/ti/reference/ti-fs-describe-layer.md new file mode 100644 index 0000000000000..0fd65950fd200 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-diff-layer.md b/ai/ti/reference/ti-fs-diff-layer.md new file mode 100644 index 0000000000000..7b425403ba16b --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--help`: Display help information. +- `--max-seq `: The highest layer sequence to include; 0 includes all sequences. +- `--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/ti-fs-disable-file-system-token.md b/ai/ti/reference/ti-fs-disable-file-system-token.md new file mode 100644 index 0000000000000..60f3fc5fc44f7 --- /dev/null +++ b/ai/ti/reference/ti-fs-disable-file-system-token.md @@ -0,0 +1,63 @@ +--- +title: ti fs disable-file-system-token +summary: Temporarily disable a TiDB Cloud Filesystem token. +--- + +# ti fs disable-file-system-token + +Temporarily disables a Filesystem token without revoking it. You can re-enable the token later with [`ti fs enable-file-system-token`](/ai/ti/reference/ti-fs-enable-file-system-token.md). A token used by a known local mount must be drained and unmounted first. With owner token authentication, only scoped tokens can be disabled; TiDB Cloud API keys can disable either token kind. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs disable-file-system-token + --token-id + [--file-system-id ] + [--fs-token ] + [--dry-run] + [--help] + [--version] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. Required when using TiDB Cloud API credentials; optional when an owner token supplies the ID. +- `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--fs-token `: Authorize the request with an owner Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. If no Filesystem token is available, the command uses the configured TiDB Cloud API keys. +- `--dry-run`: Validate credentials, identifiers, and known local mount conflicts without disabling the 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 + +- 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 "" + ``` + +- Disable a scoped token by using an owner token: + + ```bash + # Inject TI_FS_TOKEN from a secret manager. The owner token identifies the Filesystem. + # Drain any local mount that uses the target token first. + ti fs disable-file-system-token \ + --token-id "" + ``` + +## Related documentation + +- [Token-management authorization](/ai/ti/reference/ti-filesystem.md#token-management-authorization) +- [`ti fs enable-file-system-token`](/ai/ti/reference/ti-fs-enable-file-system-token.md) +- [`ti fs delete-file-system-token`](/ai/ti/reference/ti-fs-delete-file-system-token.md) diff --git a/ai/ti/reference/ti-fs-drain-file-system.md b/ai/ti/reference/ti-fs-drain-file-system.md new file mode 100644 index 0000000000000..25216e1080a86 --- /dev/null +++ b/ai/ti/reference/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 pending writes from a FUSE mount to the remote Filesystem while keeping the mount online. The command alias is `ti fs drain`. For a WebDAV mount, stop writers and use `ti fs unmount-file-system`; running `drain-file-system` for it returns an error. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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/ti-fs-enable-file-system-token.md b/ai/ti/reference/ti-fs-enable-file-system-token.md new file mode 100644 index 0000000000000..b643e55e0b25b --- /dev/null +++ b/ai/ti/reference/ti-fs-enable-file-system-token.md @@ -0,0 +1,60 @@ +--- +title: ti fs enable-file-system-token +summary: Enable a disabled TiDB Cloud Filesystem token. +--- + +# ti fs enable-file-system-token + +Re-enables a disabled Filesystem token. The token can take approximately 10 seconds to become usable. With owner token authentication, only scoped tokens can be enabled; TiDB Cloud API keys can enable either token kind. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs enable-file-system-token + --token-id + [--file-system-id ] + [--fs-token ] + [--dry-run] + [--help] + [--version] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. Required when using TiDB Cloud API credentials; optional when an owner token supplies the ID. +- `--token-id `: Specify the immutable token ID returned by the list command. This option is required. +- `--fs-token `: Authorize the request with an owner Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. If no Filesystem token is available, the command uses the configured TiDB Cloud API keys. +- `--dry-run`: Validate the request without changing remote token state. +- `--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 + +- 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 "" + ``` + +- Enable a scoped token by using an owner token: + + ```bash + # The owner token identifies and authorizes token management for its Filesystem. + TI_FS_TOKEN="" ti fs enable-file-system-token \ + --token-id "" + ``` + +## Related documentation + +- [Token-management authorization](/ai/ti/reference/ti-filesystem.md#token-management-authorization) +- [`ti fs list-file-system-tokens`](/ai/ti/reference/ti-fs-list-file-system-tokens.md) +- [`ti fs disable-file-system-token`](/ai/ti/reference/ti-fs-disable-file-system-token.md) diff --git a/ai/ti/reference/ti-fs-find-files.md b/ai/ti/reference/ti-fs-find-files.md new file mode 100644 index 0000000000000..3a1dff9b22799 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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 `: Return files newer than the specified date in `YYYY-MM-DD` format. +- `--older `: Return files older than the specified date in `YYYY-MM-DD` format. +- `--path `: File path prefix. \[default: /] +- `--resource-type `: Resource type filter: `file` or `directory`. +- `--tag `: Match an exact tag by `key=value`, or match any value for a tag key by specifying only `key`. +- `--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/ti-fs-fork-layer.md b/ai/ti/reference/ti-fs-fork-layer.md new file mode 100644 index 0000000000000..e4fde279f5f14 --- /dev/null +++ b/ai/ti/reference/ti-fs-fork-layer.md @@ -0,0 +1,68 @@ +--- +title: ti fs fork-layer +summary: Fork a copy-on-write child layer in a TiDB Cloud Filesystem. +--- + +# ti fs fork-layer + +Creates a writable child layer from the current state of a parent layer or from one of its checkpoints. Changes to the child layer do not modify the parent layer. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs fork-layer + --parent-layer-ref + [--actor-id ] + [--checkpoint-id ] + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--layer-id ] + [--layer-name ] + [--version] +``` + +## Options + +- `--parent-layer-ref `: Parent layer ID, unique name, or [tag reference](/ai/ti/reference/ti-filesystem.md#layer-references). \[required] +- `--actor-id `: Actor ID identifying the child owner. +- `--checkpoint-id `: Pin the child to this checkpoint of the parent. If omitted, pins the serialized parent tip. +- `--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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--help`: Display help information. +- `--layer-id `: Stable child layer ID. If omitted, the service generates one. +- `--layer-name `: Human-readable child layer name. +- `--version`: Display version information. + +For options shared by all commands, see [Global options](/ai/ti/reference/ti-cli-reference.md#global-options). + +## Examples + +- Fork from the parent tip: + + ```bash + # Start an independent writable timeline at the parent's current serialized tip. + ti fs fork-layer --file-system-id --parent-layer-ref research-base --layer-name experiment-a --actor-id agent-a + ``` + +- Fork from a stable checkpoint: + + ```bash + # Continue from an earlier review boundary without changing the original timeline. + ti fs fork-layer --file-system-id --parent-layer-ref research-base --checkpoint-id seed --layer-name experiment-b --actor-id agent-b + ``` + +> **Note:** +> +> Layer names remain visible after logical deletion and can become ambiguous. Automation should capture and use the returned layer ID. + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [`ti fs mount-file-system`](/ai/ti/reference/ti-fs-mount-file-system.md) diff --git a/ai/ti/reference/ti-fs-generate-file-system-scoped-token.md b/ai/ti/reference/ti-fs-generate-file-system-scoped-token.md new file mode 100644 index 0000000000000..4c8f9b4a7bd40 --- /dev/null +++ b/ai/ti/reference/ti-fs-generate-file-system-scoped-token.md @@ -0,0 +1,99 @@ +--- +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 + +Generates a scoped token with limited path and operation access from an owner token. The token value appears only in the command output and cannot be retrieved later. 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. + +The operations have the following meanings. A command can require more than one operation, such as `read` on a copy source and `write` on its destination. + +| Operation | Allows | +| --- | --- | +| `read` | Reading file content and metadata. | +| `list` | Listing entries under a directory. | +| `search` | Searching or finding files under the prefix. Requires `read`. | +| `write` | Creating or changing files, directories, links, and copy destinations. | +| `delete` | Deleting a path or removing a source path during a move. | + +> **Important:** +> +> Include both `search` and `read` in the same `--allow` value when permitting searches. The CLI rejects a scope that includes `search` without `read`. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs generate-file-system-scoped-token + --ttl + --allow + [--file-system-id ] + [--fs-token ] + [--subject ] + [--store-locally] + [--replace] + [--dry-run] + [--help] + [--version] +``` + +## 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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. +- `--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 + +- Give a sandbox read and write access to one workspace: + + ```bash + # Inject the owner TI_FS_TOKEN from a secret manager, then create a token limited to /workspace. + 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 + # Inject the owner TI_FS_TOKEN from a secret manager. Repeat --allow to assign different operations to independent prefixes. + ti fs generate-file-system-scoped-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/ti-fs-generate-file-system-token.md) +- [`ti fs refresh-file-system-token`](/ai/ti/reference/ti-fs-refresh-file-system-token.md) diff --git a/ai/ti/reference/ti-fs-generate-file-system-token.md b/ai/ti/reference/ti-fs-generate-file-system-token.md new file mode 100644 index 0000000000000..020cc35b7c58e --- /dev/null +++ b/ai/ti/reference/ti-fs-generate-file-system-token.md @@ -0,0 +1,80 @@ +--- +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 a Filesystem using TiDB Cloud API credentials. The token value appears only in the command output and cannot be retrieved later. Use `--store-locally` to save the token in the local credential store. An existing Filesystem token cannot be used to generate owner tokens. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs generate-file-system-token + --file-system-id + --token-name + (--ttl | --no-expiration) + [--dry-run] + [--help] + [--replace] + [--store-locally] + [--version] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem that owns the token. FS tokens cannot replace this option or authorize owner-token generation. 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. +- `--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 + +- 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/ti-fs-list-file-system-tokens.md) diff --git a/ai/ti/reference/ti-fs-git-add-git-worktree.md b/ai/ti/reference/ti-fs-git-add-git-worktree.md new file mode 100644 index 0000000000000..55beebbe0790c --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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`: Verify that the base workspace uses blobless Git storage. This option does not convert a non-blobless workspace. +- `--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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--help`: Display help information. +- `--hydrate `: Clean-data hydration mode: `auto`, `background`, `sync`, or `off`. With `auto`, a worktree linked to a blobless base hydrates in the background, while a worktree linked to a non-blobless base does not run a separate hydration step. `background` and `sync` require a blobless base; `off` skips hydration. \[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/ti-fs-git-clone-git-workspace.md b/ai/ti/reference/ti-fs-git-clone-git-workspace.md new file mode 100644 index 0000000000000..cc00eaa6bc97b --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--help`: Display help information. +- `--hydrate `: Clean-data hydration mode: `auto`, `background`, `sync`, or `off`. With `auto`, a blobless clone hydrates in the background, while a non-blobless clone does not run a separate hydration step. `background` and `sync` require `--blobless`; `off` skips hydration. \[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/ti-fs-git-hydrate-git-workspace.md b/ai/ti/reference/ti-fs-git-hydrate-git-workspace.md new file mode 100644 index 0000000000000..6694a4069f59d --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-git-remove-git-worktree.md b/ai/ti/reference/ti-fs-git-remove-git-worktree.md new file mode 100644 index 0000000000000..5786605fcde94 --- /dev/null +++ b/ai/ti/reference/ti-fs-git-remove-git-worktree.md @@ -0,0 +1,57 @@ +--- +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 Git worktree while preserving the shared Git data used by other worktrees. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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 + # Remove a clean linked worktree. + ti fs-git remove-git-worktree --file-system-id --worktree-path /path/to/workspace/tidb-feature + ``` + +- Force removal of a Git worktree: + + ```bash + # Discard local changes only after deciding that they are no longer needed. + 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/ti-fs-import-file-system-token.md b/ai/ti/reference/ti-fs-import-file-system-token.md new file mode 100644 index 0000000000000..c909daf626c27 --- /dev/null +++ b/ai/ti/reference/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 Filesystem token and stores it in the selected local profile. The Filesystem ID is derived from the token; use the optional `--file-system-id` to verify that the token belongs to the expected Filesystem. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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/ti-fs-journal-append-journal-entries.md b/ai/ti/reference/ti-fs-journal-append-journal-entries.md new file mode 100644 index 0000000000000..ddcfa32232117 --- /dev/null +++ b/ai/ti/reference/ti-fs-journal-append-journal-entries.md @@ -0,0 +1,99 @@ +--- +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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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. For the supported fields, see [Entry JSON format](#entry-json-format). +- `--entry-type `: Entry type to use when an input object omits `type`. An explicit `type` in an input object takes precedence. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--help`: Display help information. +- `--idempotency-key `: Key used to deduplicate retries of the same append request. If omitted, each invocation receives a new key. +- `--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). + +## Entry JSON format + +Each input object supports the following fields: + +| Field | Type | Description | +| --- | --- | --- | +| `type` | string | Event type. Required unless `--entry-type` supplies a default. It must start with a lowercase letter and can contain lowercase letters, digits, underscores (`_`), periods (`.`), or hyphens (`-`). | +| `schema_version` | integer | Schema version for the event payload. Values less than `1` use `1`. | +| `status` | string | Optional user-defined status. The CLI converts it to lowercase. | +| `occurred_at` | RFC3339 timestamp | Time when the event occurred. If omitted, the service supplies the time. | +| `actor` | object | Optional actor with `type` and `id` string fields. | +| `source` | string | Event source. Supported values are `self_reported`, `gateway_observed`, `server_observed`, and `imported`. \[default: `self_reported`] | +| `parent_entry_id` | string | Optional parent event ID. | +| `correlation_id` | string | Optional ID that groups related events. | +| `subjects` | array of strings | Subjects in `type:id` form. Values supplied with `--subject` are added to this array. | +| `summary` | JSON value | Optional inline event payload. | + +Artifact references are not currently supported. Do not include `artifacts` or `artifact_refs` in an entry. + +If you specify `--source`, it replaces the `source` value in every input object. `--entry-type` applies only to objects that omit `type`. + +> **Important:** +> +> To make an append safe to retry, choose an idempotency key for the logical request and reuse that key for every retry. If you omit `--idempotency-key`, a retry receives a new key and can append duplicate entries. + +## Examples + +- Append one JSON entry: + + ```bash + # Record an event object and let the CLI or service apply default metadata. + 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/ti-fs-journal-create-journal.md b/ai/ti/reference/ti-fs-journal-create-journal.md new file mode 100644 index 0000000000000..4daa18ca44fe8 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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`. Both parts are user-defined non-empty strings; the CLI converts `type` to lowercase. +- `--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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--help`: Display help information. +- `--journal-id `: Journal ID; generated when omitted. +- `--journal-kind `: User-defined journal category. It must contain 1 to 64 characters, start with a lowercase letter, and use only lowercase letters, digits, underscores (`_`), periods (`.`), or hyphens (`-`). \[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/ti-fs-journal-read-journal-entries.md b/ai/ti/reference/ti-fs-journal-read-journal-entries.md new file mode 100644 index 0000000000000..eeae32ecd1518 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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. If omitted or set to `0`, reading starts with the earliest entry. +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-journal-search-journal-entries.md b/ai/ti/reference/ti-fs-journal-search-journal-entries.md new file mode 100644 index 0000000000000..f2c2b82bfd018 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 `: Cursor returned by a previous page. When continuing, repeat the filters from the original request. +- `--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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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 `: Lower time bound as a relative duration, such as `24h`, or an RFC3339 timestamp. +- `--status `: Entry status filter. +- `--subject `: Subject filter; repeatable. +- `--until `: Upper time bound as an RFC3339 timestamp. Relative durations are not accepted. +- `--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/ti-fs-journal-verify-journal.md b/ai/ti/reference/ti-fs-journal-verify-journal.md new file mode 100644 index 0000000000000..62c35adc735ed --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-list-file-system-tokens.md b/ai/ti/reference/ti-fs-list-file-system-tokens.md new file mode 100644 index 0000000000000..2b34915c7d6e0 --- /dev/null +++ b/ai/ti/reference/ti-fs-list-file-system-tokens.md @@ -0,0 +1,72 @@ +--- +title: ti fs list-file-system-tokens +summary: List token metadata for one TiDB Cloud Filesystem. +--- + +# ti fs list-file-system-tokens + +Lists tokens for a Filesystem. Token values are never included in the output. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs list-file-system-tokens + [--file-system-id ] + [--fs-token ] + [--include-expired] + [--help] + [--limit ] + [--offset ] + [--version] +``` + +## Options + +- `--file-system-id `: Specify the Filesystem whose tokens are listed. Required when using TiDB Cloud API credentials; optional when `--fs-token` or `TI_FS_TOKEN` supplies an owner token, because `ti` derives the ID from that token. +- `--fs-token `: Authorize the request with an owner Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. If no Filesystem token is available, the command uses the 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. +- `--help`: Display help information. +- `--offset `: Set the zero-based token offset [default: 0]. +- `--limit `: Set the maximum number of tokens to return, from 1 through 200 [default: 50]. +- `--version`: Display version information. + +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 + ``` + +- List token metadata with an owner token: + + ```bash + # The owner token identifies the Filesystem, so --file-system-id is not needed. + TI_FS_TOKEN="" ti fs list-file-system-tokens --output text + ``` + +## Related documentation + +- [`ti fs generate-file-system-token`](/ai/ti/reference/ti-fs-generate-file-system-token.md) +- [`ti fs generate-file-system-scoped-token`](/ai/ti/reference/ti-fs-generate-file-system-scoped-token.md) +- [TiDB Cloud CLI Regions, Security, and Limitations](/ai/ti/reference/ti-regions-security-and-limitations.md) diff --git a/ai/ti/reference/ti-fs-list-file-systems.md b/ai/ti/reference/ti-fs-list-file-systems.md new file mode 100644 index 0000000000000..5da760e15a220 --- /dev/null +++ b/ai/ti/reference/ti-fs-list-file-systems.md @@ -0,0 +1,57 @@ +--- +title: ti fs list-file-systems +summary: List remote TiDB Cloud Filesystems in a region. +--- + +# ti fs list-file-systems + +Lists all Filesystems accessible with the selected TiDB Cloud credentials in the selected region. Results include display names, labels, status, quota and usage, and `has_local_token`, which indicates whether this machine has a matching local token. Token values are never included. + +When available, quota data includes media and video extraction limits and usage. + +The CLI retrieves every service page automatically and returns one complete, sorted result, so this command has no pagination options. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs list-file-systems + [--display-name ] + [--help] + [--label ] + [--version] +``` + +## Options + +- `--display-name `: Filter by a case-sensitive display-name substring. This is not an exact resource lookup. +- `--help`: Display help information. +- `--label `: Filter by one exact `key=value` label. +- `--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 + ``` + +- Filter Filesystems by display metadata: + + ```bash + # Match a display-name substring and one exact organization-visible label. + ti fs list-file-systems \ + --display-name workspace \ + --label environment=production + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/ti-fs-list-files.md b/ai/ti/reference/ti-fs-list-files.md new file mode 100644 index 0000000000000..96202bd1d664f --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-list-layer-chain.md b/ai/ti/reference/ti-fs-list-layer-chain.md new file mode 100644 index 0000000000000..abc9f8d626355 --- /dev/null +++ b/ai/ti/reference/ti-fs-list-layer-chain.md @@ -0,0 +1,47 @@ +--- +title: ti fs list-layer-chain +summary: List the ancestry chain for a TiDB Cloud Filesystem layer. +--- + +# ti fs list-layer-chain + +Lists the parent-child layer chain from the root layer to a selected child layer, including each layer's sequence boundary. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs list-layer-chain + --layer-ref + [--file-system-id ] + [--fs-token ] + [--help] + [--version] +``` + +## Options + +- `--layer-ref `: Layer ID, unique name, or [tag reference](/ai/ti/reference/ti-filesystem.md#layer-references). \[required] +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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 + +- Inspect a child timeline: + + ```bash + # Render the root-to-tip ancestry as stable text columns. + ti fs list-layer-chain --file-system-id --layer-ref experiment-a --output text + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) +- [`ti fs fork-layer`](/ai/ti/reference/ti-fs-fork-layer.md) diff --git a/ai/ti/reference/ti-fs-list-layers.md b/ai/ti/reference/ti-fs-list-layers.md new file mode 100644 index 0000000000000..0c9b0409b01b6 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-mount-file-system.md b/ai/ti/reference/ti-fs-mount-file-system.md new file mode 100644 index 0000000000000..2e29052340bf8 --- /dev/null +++ b/ai/ti/reference/ti-fs-mount-file-system.md @@ -0,0 +1,121 @@ +--- +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`. + +The command starts the mount process in the background, waits for the mount to become ready, and then prints the result. If startup fails, the error includes a log path for diagnosis. Use `ti fs unmount-file-system` to end the mount. + +> **Important:** +> +> Layer and checkpoint mounts require FUSE. On macOS, where automatic selection normally uses WebDAV, install macFUSE and specify `--driver fuse`. Checkpoint mounts are always read-only. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs mount-file-system + --mount-path + [--cache-dir ] + [--checkpoint-id ] + [--driver ] + [--dry-run] + [--file-system-id ] + [--fs-token ] + [--help] + [--layer-ref ] + [--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/`. +- `--checkpoint-id `: Mount this checkpoint of `--layer-ref` read-only. Requires FUSE. +- `--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`. +- `--fs-token `: Set the Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--help`: Display help information. +- `--layer-ref `: Mount through a writable layer ID, unique name, or [tag reference](/ai/ti/reference/ti-filesystem.md#layer-references). Requires FUSE. +- `--local-root `: Local overlay root. If omitted, uses `~/.ti/local/fs/`. +- `--mount-profile `: Select a [mount profile](/ai/ti/reference/ti-filesystem.md#mount-profiles-and-local-overlays): `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. This behavior is enabled by default; specify `--write-back-cache=false` to disable it. Unavailable for checkpoint mounts, which are always read-only. \[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 + ``` + +- Mount a writable child layer: + + ```bash + # Expose only the selected copy-on-write timeline at the local path. + ti fs mount-file-system --file-system-id --mount-path /path/to/experiment --remote-path /workspace --driver fuse --layer-ref experiment + ``` + +- Compare an immutable historical checkpoint: + + ```bash + # A checkpoint mount is always read-only. + ti fs mount-file-system --file-system-id --mount-path /path/to/checkpoint --remote-path /workspace --driver fuse --layer-ref experiment --checkpoint-id v5 + ``` + +## Related documentation + +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/ti-fs-move-file.md b/ai/ti/reference/ti-fs-move-file.md new file mode 100644 index 0000000000000..5b02ab488cddf --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-pack-file-system.md b/ai/ti/reference/ti-fs-pack-file-system.md new file mode 100644 index 0000000000000..c7609c86ff082 --- /dev/null +++ b/ai/ti/reference/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](/ai/ti/reference/ti-filesystem.md#mount-profiles-and-local-overlays) into a remote archive. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--help`: Display help information. +- `--local-root `: Local overlay root containing the overlay directory. +- `--mount-path `: The local mounted path. +- `--mount-profile `: Select a [mount profile](/ai/ti/reference/ti-filesystem.md#mount-profiles-and-local-overlays): `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 /path/to/local-root --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/ti-fs-read-file.md b/ai/ti/reference/ti-fs-read-file.md new file mode 100644 index 0000000000000..fe4c9ce4faa1c --- /dev/null +++ b/ai/ti/reference/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 + +Reads a remote file or byte range and outputs it to stdout. The command alias is `ti fs cat`. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-refresh-file-system-token.md b/ai/ti/reference/ti-fs-refresh-file-system-token.md new file mode 100644 index 0000000000000..bf9196a2371c4 --- /dev/null +++ b/ai/ti/reference/ti-fs-refresh-file-system-token.md @@ -0,0 +1,83 @@ +--- +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 Filesystem token and returns its replacement value once. The previous value stops working after authentication changes propagate, which can take approximately 10 seconds. + +> **Warning:** +> +> Refresh is not idempotent. If the request succeeds but you do not receive the response, do not retry with the old token. Generate and distribute a replacement token instead. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs refresh-file-system-token + [--file-system-id ] + [--fs-token ] + [--ttl ] + [--dry-run] + [--help] + [--version] +``` + +## 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. +- `--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 + +- 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 + # Read the current token without echoing it or storing it in shell history. + printf 'Current FS token: ' >&2 + read -r -s TI_FS_TOKEN + printf '\n' >&2 + export TI_FS_TOKEN + + # Capture the one-time replacement and update the external secret manager yourself. + TI_REGION_CODE="aws-us-east-1" \ + ti fs refresh-file-system-token > ./refreshed-token.json + unset TI_FS_TOKEN + ``` + +- Change the token lifetime during refresh: + + ```bash + # Read the current token without echoing it or storing it in shell history. + printf 'Current FS token: ' >&2 + read -r -s TI_FS_TOKEN + printf '\n' >&2 + export TI_FS_TOKEN + + # Rotate the token and set its new lifetime to 30 days. + TI_REGION_CODE="aws-us-east-1" \ + ti fs refresh-file-system-token --ttl 720h + unset TI_FS_TOKEN + ``` + +## Related documentation + +- [`ti fs generate-file-system-token`](/ai/ti/reference/ti-fs-generate-file-system-token.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.md) diff --git a/ai/ti/reference/ti-fs-rollback-layer.md b/ai/ti/reference/ti-fs-rollback-layer.md new file mode 100644 index 0000000000000..57db08b2e88a7 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-search-file-content.md b/ai/ti/reference/ti-fs-search-file-content.md new file mode 100644 index 0000000000000..710b4793b88ad --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs search-file-content + --pattern + [--file-system-id ] + [--fs-token ] + [--help] + [--layer-id ] + [--limit ] + [--path ] + [--version] +``` + +## Options + +- `--pattern `: Text query used for full-text and, when configured, semantic search over extracted file content and descriptions. The value is not a regular expression or glob. \[required] +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-unmount-file-system.md b/ai/ti/reference/ti-fs-unmount-file-system.md new file mode 100644 index 0000000000000..b7aca5d460763 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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. This can lose uncommitted in-memory or write-back state. +- `--help`: Display help information. +- `--ignore-absent`: Return success when no file system mount state exists for the specified path. +- `--no-auto-pack`: Skip the default auto-pack action configured by the mount. The built-in `portable` profile enables this action by selecting `/` as its pack path. +- `--pack-archive-path `: After unmounting, pack the mount's local overlay to this remote archive path. Specifying this option requests a pack even when the mount profile has no default pack paths. +- `--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/ti-fs-unpack-file-system.md b/ai/ti/reference/ti-fs-unpack-file-system.md new file mode 100644 index 0000000000000..b3b56936085c0 --- /dev/null +++ b/ai/ti/reference/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](/ai/ti/reference/ti-filesystem.md#mount-profiles-and-local-overlays) from a remote archive. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--help`: Display help information. +- `--local-root `: The local overlay root to restore into. +- `--mount-path `: The local mounted path. +- `--mount-profile `: Select a [mount profile](/ai/ti/reference/ti-filesystem.md#mount-profiles-and-local-overlays): `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 /path/to/local-root --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/ti-fs-update-file-system-embedding-configuration.md b/ai/ti/reference/ti-fs-update-file-system-embedding-configuration.md new file mode 100644 index 0000000000000..e2639e2c7619d --- /dev/null +++ b/ai/ti/reference/ti-fs-update-file-system-embedding-configuration.md @@ -0,0 +1,94 @@ +--- +title: ti fs update-file-system-embedding-configuration +summary: Replace embedding configuration for a TiDB Cloud Filesystem. +--- + +# ti fs update-file-system-embedding-configuration + +Enables or disables optional app-managed embedding for one Filesystem. Enabling performs a real provider validation request that can incur a small provider charge. After enablement, text or extracted descriptions are sent to the selected embedding provider. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs update-file-system-embedding-configuration + --enabled + --file-system-id + [--dry-run] + [--help] + [--provider-api-base ] + [--provider-model ] + [--version] +``` + +## Options + +- `--enabled `: Enter `true` with a complete provider configuration, or `false` without provider options. \[required] +- `--file-system-id `: Set the immutable Filesystem ID. \[required] +- `--dry-run`: Validate the request without contacting the Filesystem backend or embedding provider. +- `--provider-api-base `: Set a valid HTTPS OpenAI-compatible provider base URL. +- `--provider-model `: Set an embedding model that returns exactly 1024 dimensions. +- `--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). + +The provider API key is accepted only from `TI_FS_AI_PROVIDER_API_KEY`. It is sent to the Filesystem backend for validation and encrypted storage, is never stored locally by `ti`, and is returned only in masked form. Embedding requires an exact OpenAI-compatible `/v1/embeddings` contract. Native provider interfaces are not supported. + +A Filesystem whose `source` is `database_auto` uses database-managed embedding and cannot be changed with this command. Do not retry an update blindly after a timeout or lost response. Run the describe command first to determine whether the update succeeded. + +## Examples + +- Enable app-managed embedding: + + ```bash + # Read the provider key without echoing it or storing it in shell history. + printf 'Provider API key: ' >&2 + read -r -s TI_FS_AI_PROVIDER_API_KEY + printf '\n' >&2 + export TI_FS_AI_PROVIDER_API_KEY + + # Configure a model that returns exactly 1024 dimensions. + ti fs update-file-system-embedding-configuration \ + --file-system-id \ + --enabled true \ + --provider-api-base https://api.openai.com/v1 \ + --provider-model text-embedding-3-small + unset TI_FS_AI_PROVIDER_API_KEY + ``` + +- Preview enablement without validating or saving the provider: + + ```bash + # Read the provider key without echoing it or storing it in shell history. + printf 'Provider API key: ' >&2 + read -r -s TI_FS_AI_PROVIDER_API_KEY + printf '\n' >&2 + export TI_FS_AI_PROVIDER_API_KEY + + # Validate local inputs and show a redacted request plan. + ti fs update-file-system-embedding-configuration \ + --file-system-id \ + --enabled true \ + --provider-api-base https://api.openai.com/v1 \ + --provider-model text-embedding-3-small \ + --dry-run + unset TI_FS_AI_PROVIDER_API_KEY + ``` + +- Disable app-managed embedding: + + ```bash + # Remove custom embedding configuration without changing normal file access. + ti fs update-file-system-embedding-configuration \ + --file-system-id \ + --enabled false + ``` + +## Related documentation + +- [`ti fs describe-file-system-embedding-configuration`](/ai/ti/reference/ti-fs-describe-file-system-embedding-configuration.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/ti-fs-update-file-system-extract-configuration.md b/ai/ti/reference/ti-fs-update-file-system-extract-configuration.md new file mode 100644 index 0000000000000..4845377d20b21 --- /dev/null +++ b/ai/ti/reference/ti-fs-update-file-system-extract-configuration.md @@ -0,0 +1,110 @@ +--- +title: ti fs update-file-system-extract-configuration +summary: Update media extraction configuration for a TiDB Cloud Filesystem. +--- + +# ti fs update-file-system-extract-configuration + +Updates optional image, audio, or video extraction configuration for one Filesystem. Enabling or replacing a provider performs a real provider validation request that can incur a small provider charge. After enablement, Filesystem media is sent to the selected provider for extraction. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs update-file-system-extract-configuration + --file-system-id + --media-type + [--dry-run] + [--enabled ] + [--help] + [--prompt ] + [--provider-api-base ] + [--provider-model ] + [--provider-protocol ] + [--version] +``` + +## Options + +- `--file-system-id `: Set the immutable Filesystem ID. \[required] +- `--media-type `: Select `image`, `audio`, or `video`. \[required] +- `--dry-run`: Validate the request without contacting the Filesystem backend or AI provider. +- `--enabled `: Explicitly enable or disable extraction. Enter `true` or `false`. +- `--prompt `: Set a prompt of at most 8 KiB. Pass an empty string to restore backend default prompt behavior. +- `--provider-api-base `: Set a valid HTTPS provider base URL. +- `--provider-model `: Set the provider model name. +- `--provider-protocol `: Set `openai`, or `qwen-asr` for audio only. The default is `openai`. +- `--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). + +The provider API key is accepted only from `TI_FS_AI_PROVIDER_API_KEY`. It is sent to the Filesystem backend for validation and encrypted storage, is never stored locally by `ti`, and is returned only in masked form. `openai` supports image, audio, and video. Alibaba Cloud Model Studio Qwen ASR is supported for audio through `qwen-asr`. Other services work only when they implement the exact required OpenAI-compatible contract. Native Anthropic, Gemini, Vertex AI, Bedrock, and Azure OpenAI interfaces are not supported. + +Do not retry an update blindly after a timeout or lost response. The provider might already have charged for validation and the backend might have saved the configuration. Run the matching describe command first. + +Before enabling a provider in an interactive shell, read and export its API key without placing it in shell history: + +```bash +printf 'Provider API key: ' >&2 +read -r -s TI_FS_AI_PROVIDER_API_KEY +printf '\n' >&2 +export TI_FS_AI_PROVIDER_API_KEY +``` + +In CI, inject `TI_FS_AI_PROVIDER_API_KEY` from a masked secret. Unset the variable after the command finishes. + +## Examples + +- Enable image extraction with an OpenAI-compatible provider: + + ```bash + # Configure extraction using the provider key from TI_FS_AI_PROVIDER_API_KEY. + ti fs update-file-system-extract-configuration \ + --file-system-id \ + --media-type image \ + --enabled true \ + --provider-api-base https://api.openai.com/v1 \ + --provider-model + ``` + +- Enable Alibaba Cloud Model Studio Qwen ASR for audio: + + ```bash + # Use the DashScope OpenAI-compatible endpoint with the qwen-asr protocol. + ti fs update-file-system-extract-configuration \ + --file-system-id \ + --media-type audio \ + --enabled true \ + --provider-api-base https://dashscope.aliyuncs.com/compatible-mode/v1 \ + --provider-model qwen3-asr-flash \ + --provider-protocol qwen-asr + ``` + +- Change only the prompt of an enabled image configuration: + + ```bash + # Keep the existing provider credentials and update only extraction instructions. + ti fs update-file-system-extract-configuration \ + --file-system-id \ + --media-type image \ + --prompt "Describe the image and return searchable attributes." + ``` + +- Disable image extraction: + + ```bash + # Remove the custom image provider configuration without changing normal file access. + ti fs update-file-system-extract-configuration \ + --file-system-id \ + --media-type image \ + --enabled false + ``` + +## Related documentation + +- [`ti fs describe-file-system-extract-configuration`](/ai/ti/reference/ti-fs-describe-file-system-extract-configuration.md) +- [TiDB Cloud Filesystem CLI Command Reference](/ai/ti/reference/ti-filesystem.md) diff --git a/ai/ti/reference/ti-fs-vault-create-grant.md b/ai/ti/reference/ti-fs-vault-create-grant.md new file mode 100644 index 0000000000000..898c183202762 --- /dev/null +++ b/ai/ti/reference/ti-fs-vault-create-grant.md @@ -0,0 +1,72 @@ +--- +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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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`. For the current permission behavior, see [Grant permissions](#grant-permissions). \[required] +- `--scope `: Secret scope in the form `` for all fields or `/` for one field; repeatable. The equivalent canonical Vault paths `/n/vault/` and `/n/vault//` are also accepted. \[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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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). + +## Grant permissions + +| Permission | Current `ti` behavior | +| --- | --- | +| `read` | Allows delegated `list-secrets`, `read-secret`, `run-with-secret`, and `mount-vault` operations within the grant scopes. | +| `write` | The service accepts this permission, but it does not include read authority. The current `ti` command surface does not expose an operation that writes a secret with a delegated token. | + +## 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/ti-fs-vault-create-secret.md b/ai/ti/reference/ti-fs-vault-create-secret.md new file mode 100644 index 0000000000000..5dd122807ec08 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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. `key=-` reads standard input. If more than one field uses `-`, each receives the same standard input value. \[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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-vault-delete-grant.md b/ai/ti/reference/ti-fs-vault-delete-grant.md new file mode 100644 index 0000000000000..cd022d792bd20 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-vault-delete-secret.md b/ai/ti/reference/ti-fs-vault-delete-secret.md new file mode 100644 index 0000000000000..44c8a7499804a --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-vault-list-audit-events.md b/ai/ti/reference/ti-fs-vault-list-audit-events.md new file mode 100644 index 0000000000000..7c5c08cdb6551 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-vault-list-secrets.md b/ai/ti/reference/ti-fs-vault-list-secrets.md new file mode 100644 index 0000000000000..d7e3a03696ee2 --- /dev/null +++ b/ai/ti/reference/ti-fs-vault-list-secrets.md @@ -0,0 +1,62 @@ +--- +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. + +The command returns the complete visible list. It does not paginate the result. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 owner Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. For delegated authentication, use `--vault-token` or `TI_VAULT_TOKEN` instead. +- `--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 + # Read the delegated token without echoing it or storing it in shell history. + printf 'Delegated Vault token: ' >&2 + read -r -s TI_VAULT_TOKEN + printf '\n' >&2 + export TI_VAULT_TOKEN + + # Restrict results to the token's granted scope. + ti fs-vault list-secrets --file-system-id + unset 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/ti-fs-vault-mount-vault.md b/ai/ti/reference/ti-fs-vault-mount-vault.md new file mode 100644 index 0000000000000..5986069e33bb0 --- /dev/null +++ b/ai/ti/reference/ti-fs-vault-mount-vault.md @@ -0,0 +1,72 @@ +--- +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. + +On Linux, install FUSE3 and make `/dev/fuse` available. On macOS, install macFUSE and approve its system extension. Vault mounts are not supported on Windows; use `read-secret`, `list-secrets`, or `run-with-secret` instead. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs-vault mount-vault + --mount-path + [--dry-run] + [--file-system-id ] + [--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`. +- `--fs-token `: Set the owner Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. For delegated authentication, use `--vault-token` or `TI_VAULT_TOKEN` instead. +- `--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 + +Before running either example, inject a delegated Vault token. In an interactive shell, read and export it without placing it in shell history: + +```bash +printf 'Delegated Vault token: ' >&2 +read -r -s TI_VAULT_TOKEN +printf '\n' >&2 +export TI_VAULT_TOKEN +``` + +When the mount is no longer needed, unmount it and run `unset TI_VAULT_TOKEN`. + +- Mount a delegated Vault view: + + ```bash + # Expose only the paths allowed by TI_VAULT_TOKEN. + ti fs-vault mount-vault --file-system-id --mount-path ./vault + ``` + +- Allow more time for the Vault mount to become ready: + + ```bash + # Increase the readiness timeout on a slower host or network. + ti fs-vault mount-vault --file-system-id --mount-path ./vault --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/ti-fs-vault-read-secret.md b/ai/ti/reference/ti-fs-vault-read-secret.md new file mode 100644 index 0000000000000..2a4b6a17d49af --- /dev/null +++ b/ai/ti/reference/ti-fs-vault-read-secret.md @@ -0,0 +1,73 @@ +--- +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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 owner Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. For delegated authentication, use `--vault-token` or `TI_VAULT_TOKEN` instead. +- `--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 + # Read the delegated token without echoing it or storing it in shell history. + printf 'Delegated Vault token: ' >&2 + read -r -s TI_VAULT_TOKEN + printf '\n' >&2 + export TI_VAULT_TOKEN + + # Access only the field allowed by the delegated token. + ti fs-vault read-secret --file-system-id --secret-name db-prod --field DB_URL --format raw + unset 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/ti-fs-vault-replace-secret.md b/ai/ti/reference/ti-fs-vault-replace-secret.md new file mode 100644 index 0000000000000..08339646095f7 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 `: Canonical Vault path in the form `/n/vault/`. For example, the secret created as `db-prod` has the path `/n/vault/db-prod`. \[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 Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. +- `--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/ti-fs-vault-run-with-secret.md b/ai/ti/reference/ti-fs-vault-run-with-secret.md new file mode 100644 index 0000000000000..f30215f3b6365 --- /dev/null +++ b/ai/ti/reference/ti-fs-vault-run-with-secret.md @@ -0,0 +1,58 @@ +--- +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. + +Each secret field name becomes an environment variable with the same name in the child process. Field names must match `[A-Z_][A-Z0-9_]*`, so create fields that you intend to inject with uppercase names. The command rejects the entire injection if any field name, including a name that contains lowercase letters, does not match this pattern or if a value contains an unsupported control character. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Syntax + +```text +ti fs-vault run-with-secret + --secret-path + [--file-system-id ] + [--fs-token ] + [--help] + [--vault-token ] + [--version] + -- [args...] +``` + +## Options + +- `--secret-path `: Canonical Vault path in the form `/n/vault/`. For example, the secret created as `db-prod` has the path `/n/vault/db-prod`. \[required] +- `--file-system-id `: Select the file system. You can also set `TI_FS_FILE_SYSTEM_ID`. +- `--fs-token `: Set the owner Filesystem token. If omitted, the command uses the `TI_FS_TOKEN` environment variable. If neither is provided, the command uses the local token stored for the selected Filesystem. For delegated authentication, use `--vault-token` or `TI_VAULT_TOKEN` instead. +- `--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 + # Verify that the child process receives DB_URL without printing its value. + ti fs-vault run-with-secret --file-system-id --secret-path /n/vault/db-prod -- sh -c 'test -n "$DB_URL" && printf "DB_URL is set\n"' + ``` + +- Run an application with injected fields: + + ```bash + # Make all fields available only to the child process and its descendants. + ti fs-vault run-with-secret --file-system-id --secret-path /n/vault/db-prod -- ./deploy.sh + ``` + +## Related documentation + +- [TiDB Cloud Filesystem Vault CLI Command Reference](/ai/ti/reference/ti-filesystem-vault.md) diff --git a/ai/ti/reference/ti-fs-vault-unmount-vault.md b/ai/ti/reference/ti-fs-vault-unmount-vault.md new file mode 100644 index 0000000000000..13f4bbe53da71 --- /dev/null +++ b/ai/ti/reference/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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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/ti-install-configure-update.md b/ai/ti/reference/ti-install-configure-update.md new file mode 100644 index 0000000000000..1c5335c6e482a --- /dev/null +++ b/ai/ti/reference/ti-install-configure-update.md @@ -0,0 +1,283 @@ +--- +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 + +Use this guide to install and configure TiDB Cloud CLI (`ti`), check for and apply updates, and uninstall the CLI when needed. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Prerequisites + +To configure TiDB Cloud CLI, obtain a TiDB Cloud API public key and private key from the [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys) page in the TiDB Cloud console first. + +> **Note:** +> +> If you previously used TiDB Cloud CLI `tdc` v0.1.x, unmount any Filesystem or Vault mounts started by `tdc`, and read [Migrate from tdc to TiDB Cloud CLI](/ai/ti/reference/ti-migrate-from-tdc.md) before installing `ti`. + +## Install TiDB Cloud CLI + +Depending on your operating system, follow the steps below to install the TiDB Cloud CLI. + + + +
+ +1. On macOS or Linux, run the following command to install the TiDB Cloud CLI: + + ```bash + curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh -s -- --yes + ``` + +2. Add `ti` to the current shell and verify it: + + ```bash + export PATH="$HOME/.ti/bin:$PATH" + ti --version + ``` + +3. To keep `ti` available in new terminal sessions, add it to your shell profile. For example, if you use `zsh`, run the following commands: + + ```bash + echo 'export PATH="$HOME/.ti/bin:$PATH"' >> ~/.zshrc + source ~/.zshrc + ``` + + If you use Bash, add the same `export` command to the startup file used by your terminal, commonly `~/.bashrc` on Linux or `~/.bash_profile` on macOS. + +
+ +
+ +1. On Windows PowerShell, run the following command to install the TiDB Cloud CLI: + + ```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 + ``` + +2. Add `ti` to the current PowerShell session and verify it: + + ```powershell + $env:Path = "$HOME\.ti\bin;$env:Path" + ti --version + ``` + +3. Add `$HOME\.ti\bin` to your user `PATH` to keep `ti` available in new PowerShell sessions: + + ```powershell + $tiBin = "$HOME\.ti\bin" + [Environment]::SetEnvironmentVariable("Path", "$tiBin;$([Environment]::GetEnvironmentVariable('Path', 'User'))", "User") + ``` + +
+ + +The installer writes to your home directory and does not require elevated privileges. + +The installer also displays a notice about anonymous usage telemetry and how to opt out. Installation does not require you to make a telemetry choice. For details, see [Anonymous telemetry](/ai/ti/reference/ti-configuration-and-credentials.md#anonymous-telemetry). + +## Configure a profile + +A profile is a named set of TiDB Cloud API public key, private key, and region code. + +This section describes how to configure a profile for the TiDB Cloud CLI. + +### Configure interactively + +By default, `ti configure` prompts you for the information required to configure a profile: + +```bash +ti configure +``` + +`ti configure` prompts you for your TiDB Cloud API public key and private key, and a default region code. The CLI uses this region for commands unless you override it for an individual command. For available regions, see [Supported regions](/ai/ti/reference/ti-regions-security-and-limitations.md#supported-regions). + +The command validates the input format locally and saves the profile without making a request to TiDB Cloud. Your credentials are verified when you run a command that accesses TiDB Cloud. To change the default profile, run `ti configure` again. To change a named profile, include its name, for example, `ti configure --profile staging`. + +### Configure a named profile + +Pass `--profile` to configure a named profile: + +```bash +ti configure --profile staging +``` + +### Configure for automation + +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. + +## Select a profile and override its region + +To use a named profile and override its default region for one command, use the global `--profile` and `--region` options: + +```bash +ti --profile staging --region aws-us-west-2 db list-db-clusters --db-cluster-type starter +``` + +For detailed profile, credential, and region precedence rules, see [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md). + +## Get help and check the version + +Use `help` or `--help` to inspect commands and `--version` to check the installed version: + +```bash +ti help +ti fs help +ti --version +``` + +For command groups and CLI conventions, see [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md). + +## Update TiDB Cloud CLI + +Check without changing files: + +```bash +ti update --check +``` + +In automation, return exit code `1` when a newer version is available: + +```bash +ti update --check --fail-if-update-available +``` + +Preview an update: + +```bash +ti update --dry-run +``` + +> **Note:** +> +> If you have an active Filesystem or Vault mount, stop writers and unmount it before updating so that `ti` and the Filesystem runtime are updated together. For example: +> +> ```bash +> ti fs unmount-file-system --mount-path +> ``` +> +> For a Vault mount, use `ti fs-vault unmount-vault --mount-path `. For details, see [Mount a TiDB Cloud Filesystem](/ai/ti/guides/mount-filesystem.md) and [Manage Filesystem Vault Secrets](/ai/ti/guides/manage-filesystem-vault-secrets.md). + +Apply the latest update: + +```bash +ti update +``` + +Install a specific release: + +```bash +ti update --target-version +``` + +The update command replaces both `ti` and `ti-drive9` in a user-owned installation. It does not modify installations in protected or package-manager-owned locations. To migrate an older `/usr/local/bin` installation to `~/.ti/bin`, run the installer once. + +## Migrate from tdc v0.1.x + +If you have never used `tdc` v0.1.x, skip this section. + +If you previously used `tdc` v0.1.x, `ti` can migrate supported local profiles, credentials, preferences, and Filesystem state from `~/.tdc/` to `~/.ti/`. Before installing `ti`, unmount any Filesystem or Vault mounts started by `tdc`. + +For the complete migration procedure, including migrated and excluded state, directory conflict resolution, and legacy environment variable compatibility, see [Migrate from tdc to TiDB Cloud CLI](/ai/ti/reference/ti-migrate-from-tdc.md). + +## Uninstall TiDB Cloud CLI + +Before uninstalling, stop writers and unmount any active Filesystem or Vault mounts. + +For example, run the command that corresponds to the type of mount: + +```bash +# Filesystem mount +ti fs unmount-file-system --mount-path + +# Vault mount +ti fs-vault unmount-vault --mount-path +``` + +For details, see [Mount a TiDB Cloud Filesystem](/ai/ti/guides/mount-filesystem.md) and [Manage Filesystem Vault Secrets](/ai/ti/guides/manage-filesystem-vault-secrets.md). + + + +
+ +1. Remove the binaries: + + ```bash + rm -f "$HOME/.ti/bin/ti" "$HOME/.ti/bin/ti-drive9" + ``` + +2. Remove the `~/.ti/bin` entry that you added to your shell profile during installation. + +
+ +
+ +1. Remove the binaries: + + ```powershell + Remove-Item "$HOME\.ti\bin\ti.exe", "$HOME\.ti\bin\ti-drive9.exe" + ``` + +2. Remove `$HOME\.ti\bin` from your user `PATH`: + + ```powershell + $tiBin = "$HOME\.ti\bin" + $userPath = [Environment]::GetEnvironmentVariable("Path", "User") + $newPath = (($userPath -split ";") | Where-Object { $_ -and $_ -ne $tiBin }) -join ";" + [Environment]::SetEnvironmentVariable("Path", $newPath, "User") + ``` + +
+ + +### Remove local state + +Removing binaries preserves profiles, credentials, Filesystem registrations, DB SQL credentials, logs, and mount locators. + +> **Note:** +> +> Remove `~/.ti/` only when you intend to permanently delete all local TiDB Cloud CLI state. Deleting local state does not delete remote TiDB Cloud Starter instances or Filesystem resources. + + + +
+ +On macOS or Linux: + +```bash +rm -rf "$HOME/.ti" +``` + +
+ +
+ +On Windows PowerShell: + +```powershell +Remove-Item "$HOME\.ti" -Recurse -Force +``` + +
+ + +## See also + +- [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-migrate-from-tdc.md b/ai/ti/reference/ti-migrate-from-tdc.md new file mode 100644 index 0000000000000..7a87e1e49a59b --- /dev/null +++ b/ai/ti/reference/ti-migrate-from-tdc.md @@ -0,0 +1,96 @@ +--- +title: Migrate from tdc to TiDB Cloud CLI +summary: Migrate supported local state and automation from tdc v0.1.x to TiDB Cloud CLI. +--- + +# Migrate from tdc to TiDB Cloud CLI + +This migration applies only if you previously used `tdc` v0.1.x. New TiDB Cloud CLI installations do not require it. + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Before you begin + +- Stop writers and unmount every Filesystem and Vault mount started by `tdc`. Migration stops if an old mount is still active because it cannot transfer a running FUSE or WebDAV process. + + Run the commands that match each active mount. For a FUSE Filesystem mount, run `drain-file-system` to flush pending writes, and then run `unmount-file-system` to detach the mount. For a WebDAV Filesystem mount, stop writers and run only `unmount-file-system`. A Vault mount only requires `unmount-vault`. + + ```bash + # FUSE Filesystem mount + tdc fs drain-file-system --mount-path + tdc fs unmount-file-system --mount-path + + # WebDAV Filesystem mount + tdc fs unmount-file-system --mount-path + + # Vault mount + tdc fs-vault unmount-vault --mount-path + ``` + +- Back up `~/.tdc/` and any existing `~/.ti/` directory before resolving a directory conflict. + +## Install ti and migrate local state + +The old `tdc update` command cannot install the renamed `ti` executable, and `ti` does not provide a `tdc` command alias. Install `ti` directly by following [Install TiDB Cloud CLI](/ai/ti/reference/ti-install-configure-update.md#install-tidb-cloud-cli). + +The installer and the first non-update `ti` command automatically migrate supported local state when `~/.tdc/` exists and `~/.ti/` does not. The migration preserves `~/.tdc/` as a rollback copy and creates an owner-only marker under `~/.ti/` to record the completed migration. + +The following table summarizes which state is migrated: + +| Migrated | Not migrated | +| --- | --- | +| Profiles and TiDB Cloud API credentials | Binaries | +| Global preferences and the telemetry installation identity | Logs and caches | +| Database SQL credentials | Local overlays | +| Filesystem registrations and credentials | Mount locators and companion runtime state | + +After installation, verify the new executable and run a read-only command for the resources you use. For example: + +```bash +ti --version + +# For TiDB Cloud Starter +ti db list-db-clusters --db-cluster-type starter --output text + +# For TiDB Cloud Filesystem +ti fs list-file-systems --output text +``` + +After you verify the migration, you can remove the old `tdc` binaries and local state when you no longer need the rollback copy. + +## Resolve a local state conflict + +If `~/.tdc/` and `~/.ti/` were created independently, or the migration marker is missing, invalid, or references a different source, `ti` stops without merging or overwriting either directory. + +Determine which directory is the intended source of truth, and move the other directory to a backup location. Then run the installer or `ti` command again. Do not combine credential or Filesystem registry directories manually. + +## Update environment variables + +Update automation to use the following environment variable names: + +| `tdc` v0.1.x variable | `ti` variable | +| --- | --- | +| `TDC_PROFILE` | `TI_PROFILE` | +| `TDC_REGION_CODE` | `TI_REGION_CODE` | +| `TDC_PUBLIC_KEY` | `TIDB_CLOUD_PUBLIC_KEY` | +| `TDC_PRIVATE_KEY` | `TIDB_CLOUD_PRIVATE_KEY` | +| `TDC_FS_TOKEN` | `TI_FS_TOKEN` | +| `TDC_FS_FILE_SYSTEM_ID` | `TI_FS_FILE_SYSTEM_ID` | +| `TDC_LOGGING` | `TI_LOGGING` | +| `TDC_TELEMETRY` | `TI_TELEMETRY` | +| `TDC_TELEMETRY_TAG` | `TI_TELEMETRY_TAG` | +| `TDC_TELEMETRY_EXTRA` | `TI_TELEMETRY_EXTRA` | +| `TDC_VAULT_TOKEN` | `TI_VAULT_TOKEN` | +| `TDC_INSTALL_DIR` | `TI_INSTALL_DIR` | + +During the v0.2.x transition, `ti` accepts a legacy `TDC_*` environment variable only when the corresponding new variable is not set. If both forms are set to different values, the command fails before changing local or remote state. Support for legacy `TDC_*` variables is removed in v0.3.0. + +## What's next + +- [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) +- [Manage TiDB Cloud Starter Instances](/ai/ti/guides/manage-starter-instances.md) +- [Manage Filesystem Resources](/ai/ti/guides/manage-filesystem-resources.md) +- [Troubleshoot TiDB Cloud CLI](/ai/ti/reference/ti-troubleshooting.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..0be90892f8d60 --- /dev/null +++ b/ai/ti/reference/ti-regions-security-and-limitations.md @@ -0,0 +1,106 @@ +--- +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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Supported regions + +When using TiDB Cloud CLI, you need to configure a default region for CLI operations. + +The following table lists the supported regions for TiDB Cloud CLI and shows which TiDB Cloud CLI services are available in each region. + +| Provider | Location | Canonical region code | TiDB Cloud Starter | TiDB Cloud Filesystem | +| --- | --- | --- | --- | --- | +| AWS | N. Virginia | `aws-us-east-1` | Supported | Supported | +| AWS | Oregon | `aws-us-west-2` | Supported | Supported | +| AWS | Singapore | `aws-ap-southeast-1` | Supported | Supported | +| AWS | Frankfurt | `aws-eu-central-1` | Supported | Not supported | +| AWS | Tokyo | `aws-ap-northeast-1` | Supported | Not supported | +| Alibaba Cloud | Singapore | `alicloud-ap-southeast-1` | Supported | Supported | + +If your configured region supports TiDB Cloud Starter but not TiDB Cloud Filesystem, you can manage Starter instances in that region. Filesystem commands fail with an `unsupported endpoint` error. + +Supported Filesystem regions are built into each `ti` release. To use Filesystem in a region added after your installed version was released, upgrade `ti`. You cannot enable an unsupported region by specifying a service URL. + +## 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 | +| Describe or update Filesystem extraction and embedding configuration | TiDB Cloud API key and explicit 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. +- Pass an AI provider key only through `TI_FS_AI_PROVIDER_API_KEY`. The TiDB Cloud CLI does not persist this value locally, and the Filesystem service returns it only in masked form. Do not retry an AI configuration update after an ambiguous failure until you describe the effective configuration. +- Enabling extraction shares Filesystem media with the configured extraction provider. Enabling app-managed embedding shares text or extracted descriptions with the configured embedding provider. Review that provider's data retention and security terms before enabling either feature. +- 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 | Filesystem mount | Vault mount | Requirements and alternatives | +| --- | --- | --- | --- | +| macOS | WebDAV by default; FUSE with explicit `--driver fuse` | FUSE | The built-in WebDAV helper supports Filesystem mounts. Install macFUSE and approve its system extension for FUSE or Vault mounts. | +| Linux | FUSE | FUSE | Install FUSE3 and provide access to `/dev/fuse`. WebDAV mounting is not supported. | +| Windows | Not supported | Not supported | Use `ti fs` data-plane commands and non-mount Vault commands instead. | + +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. +- Filesystem extraction and embedding provider configuration is optional. Leaving it unconfigured does not block resource administration, file access, search, layers, Git, journal, vault, or mount workflows. +- OpenAI provider interfaces are supported for embedding and image, audio, and video extraction. Alibaba Cloud Model Studio Qwen ASR is supported only for audio extraction. Other vendors are conditionally compatible only through the exact OpenAI-compatible contract; native Anthropic, Gemini, Vertex AI, Bedrock, and Azure OpenAI interfaces are not supported. +- App-managed embedding requires a provider model that returns exactly 1024 dimensions. Filesystems that report `source=database_auto` use database-managed embedding and reject app-managed configuration. +- 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, including direct file operations, layers, mounts, Git workspaces, journals, and Vault operations. + +## 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-starter-database.md b/ai/ti/reference/ti-starter-database.md new file mode 100644 index 0000000000000..acc0b780a96f8 --- /dev/null +++ b/ai/ti/reference/ti-starter-database.md @@ -0,0 +1,32 @@ +--- +title: TiDB Cloud Starter CLI Command Reference +summary: Reference every `ti db` command for Starter instances, branches, SQL users, connection strings, and SQL execution. +--- + +# TiDB Cloud Starter CLI Command Reference + +Use `ti db` to manage TiDB Cloud Starter instances, branches, and SQL access. The CLI rejects instance-scoped operations when the target is not a TiDB Cloud Starter instance or its service plan cannot be verified. + +A branch is a separate TiDB Cloud Starter instance that contains a diverged copy of data from its parent instance. Use branches to test changes in isolation without affecting the parent. For more information, see [TiDB Cloud Branching](/tidb-cloud/branch-overview.md). + +## Commands + +| Command | Description | +|---|---| +| [`create-db-cluster`](/ai/ti/reference/ti-db-create-db-cluster.md) | Creates a TiDB Cloud Starter instance. | +| [`list-db-clusters`](/ai/ti/reference/ti-db-list-db-clusters.md) | Lists Starter instances in the effective region. | +| [`describe-db-cluster`](/ai/ti/reference/ti-db-describe-db-cluster.md) | Describes a TiDB Cloud Starter instance. | +| [`update-db-cluster`](/ai/ti/reference/ti-db-update-db-cluster.md) | Updates a TiDB Cloud Starter instance. | +| [`delete-db-cluster`](/ai/ti/reference/ti-db-delete-db-cluster.md) | Deletes a TiDB Cloud Starter instance. | +| [`create-db-cluster-branch`](/ai/ti/reference/ti-db-create-db-cluster-branch.md) | Creates a branch for a TiDB Cloud Starter instance. | +| [`list-db-cluster-branches`](/ai/ti/reference/ti-db-list-db-cluster-branches.md) | Lists branches for a TiDB Cloud Starter instance. | +| [`describe-db-cluster-branch`](/ai/ti/reference/ti-db-describe-db-cluster-branch.md) | Describes a branch for a TiDB Cloud Starter instance. | +| [`delete-db-cluster-branch`](/ai/ti/reference/ti-db-delete-db-cluster-branch.md) | Deletes a branch from a TiDB Cloud Starter instance. | +| [`create-db-sql-users`](/ai/ti/reference/ti-db-create-db-sql-users.md) | Creates or repairs role-based SQL users. | +| [`format-db-connection-string`](/ai/ti/reference/ti-db-format-db-connection-string.md) | Formats stored SQL credentials as a connection string. | +| [`execute-sql-statement`](/ai/ti/reference/ti-db-execute-sql-statement.md) | Executes one SQL statement. | + +## See also + +- [Manage TiDB Cloud Starter Instances](/ai/ti/guides/manage-starter-instances.md) +- [Query TiDB Cloud Starter with Explicit SQL Roles](/ai/ti/guides/ti-query-sql-with-roles-example.md) diff --git a/ai/ti/reference/ti-troubleshooting.md b/ai/ti/reference/ti-troubleshooting.md new file mode 100644 index 0000000000000..b8f35127d3be8 --- /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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 "$TIDB_CLOUD_PUBLIC_KEY" +test -n "$TIDB_CLOUD_PRIVATE_KEY" +``` + +If you intend to use saved credentials, unset both variables and verify the profile: + +```bash +unset TIDB_CLOUD_PUBLIC_KEY TIDB_CLOUD_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="" +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 +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. The outcome is unknown: the old token might still work if the refresh did not commit, or it might already be invalid. The replacement token from a committed refresh cannot be recovered because its response was lost. Do not retry the refresh with the old token. Instead, use TiDB Cloud credentials to generate an independent owner token. + +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 be one of the Filesystem endpoints built into the installed TiDB Cloud CLI release. Compare it with [current Filesystem regions](/ai/ti/reference/ti-regions-security-and-limitations.md#supported-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`, the companion runtime for Filesystem commands, next to `ti`. You do not invoke `ti-drive9` directly. Re-run the current installer when the TiDB Cloud CLI reports a missing companion: + +```bash +curl -fsSL https://github.com/tidbcloud/ti-cli/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 + +Background mount success prints the TiDB Cloud CLI result without Drive9 startup messages. If startup fails or times out, inspect the companion log path in the 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`. Filesystem and Vault mounts are not supported on Windows; use `ti fs` data-plane commands or non-mount Vault commands instead. + +## 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 [Mount a TiDB Cloud Filesystem](/ai/ti/guides/mount-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-cli/issues](https://github.com/tidbcloud/ti-cli/issues). diff --git a/ai/ti/reference/ti-update.md b/ai/ti/reference/ti-update.md new file mode 100644 index 0000000000000..7f7d2b6b791a5 --- /dev/null +++ b/ai/ti/reference/ti-update.md @@ -0,0 +1,69 @@ +--- +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:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without 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 + ``` + +- Fail a CI job when an update is available: + + ```bash + # Exit with code 1 when a newer release is available, without changing files. + ti update --check --fail-if-update-available + ``` + +- 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/ti-overview.md b/ai/ti/ti-overview.md new file mode 100644 index 0000000000000..f38a3c11a5ec9 --- /dev/null +++ b/ai/ti/ti-overview.md @@ -0,0 +1,87 @@ +--- +title: TiDB Cloud CLI (`ti`) Overview +summary: Learn when to use the TiDB Cloud CLI (`ti`) to manage TiDB Cloud Starter instances and TiDB Cloud Filesystems. +--- + +# TiDB Cloud CLI (`ti`) Overview + +[TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a CLI for managing [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter) instances and [TiDB Cloud Filesystems](/tidb-cloud/tidb-cloud-glossary.md#tidb-cloud-filesystem). It is designed for both interactive use and automation, with structured JSON output by default. + +> **Note:** +> +> - TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface might change without prior notice. +> - TiDB Cloud currently provides two CLIs with different scopes: [`ti`](https://github.com/tidbcloud/ti-cli) and [`ticloud`](https://github.com/tidbcloud/tidbcloud-cli). To learn when to use `ti` or `ticloud`, see [Differences between `ti` and `ticloud`](#differences-between-ti-and-ticloud) and [When to use TiDB Cloud CLI (`ti`)](#when-to-use-tidb-cloud-cli-ti). + +## When to use TiDB Cloud CLI (`ti`) + +Use the TiDB Cloud CLI (`ti`) when you want to manage TiDB Cloud from a terminal, script, CI job, or AI agent environment. + +| Typical use case | What you can do | +| --- | --- | +| Automate TiDB Cloud Starter lifecycle operations | Create and manage TiDB Cloud Starter instances and branches, wait until they are ready, inspect results as JSON, run SQL statements, and delete resources by ID. | +| Separate SQL privileges by task | Use CLI-managed read-only, read-write, or admin identities for each task without handling database passwords in every command. | +| Persist and share files across environments | Keep files available across local machines, CI jobs, sandboxes, and other ephemeral environments, and access the same remote namespace through direct file commands or supported FUSE and WebDAV mounts. | +| Use Filesystems in ephemeral environments | Provision a Filesystem on a trusted machine, then give a sandbox its Filesystem token and region code without copying a CLI profile or providing TiDB Cloud API keys. | +| 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, hash-chained workflow events in journals and grant temporary, scoped access to selected vault fields. | + +For visual, guided workflows, use the [TiDB Cloud console](https://tidbcloud.com/). For TiDB Cloud Essential or operations that `ti` does not support, use [`ticloud`](#differences-between-ti-and-ticloud). + +## What TiDB Cloud CLI manages + +The TiDB Cloud CLI covers the following functional areas: + +- **TiDB Cloud Starter** + - Instance and branch lifecycle operations + - SQL users and connection information + - SQL statement execution +- **TiDB Cloud Filesystem** + - Filesystem lifecycle and file operations + - FUSE and WebDAV mounts + - Layers, packs, and Git workspaces + - Journals and vaults +- **CLI configuration** + - Profiles, regions, and local credentials + - CLI updates + - Output formatting and JMESPath queries + +Most resource commands follow a two-level command model: + +```text +ti +``` + +For example, `ti db list-db-clusters --db-cluster-type starter`, `ti fs copy-file`, and `ti fs-journal verify-journal`. + +You can also use the top-level `ti configure` and `ti update` commands to configure and maintain the CLI. + +## Differences between `ti` and `ticloud` + +TiDB Cloud currently provides two CLIs with different scopes: `ti` and [`ticloud`](/tidb-cloud/cli-reference.md). + +`ti` is designed for automation with TiDB Cloud Starter and for managing TiDB Cloud Filesystems, while `ticloud` continues to support TiDB Cloud Essential and additional TiDB Cloud operations that are not available in `ti`. + +| CLI | Best for | Key characteristics | +| --- | --- | --- | +| `ti` | Supported TiDB Cloud Starter automation workflows and TiDB Cloud Filesystems | Designed for automation; outputs JSON by default; commands support non-interactive workflows, while `ti configure` can also prompt interactively | +| `ticloud` | TiDB Cloud Essential, existing TiDB Cloud Starter workflows, and operations not available in `ti` (such as data import, data export, and audit log operations) | Supports additional TiDB Cloud operations that are not available in `ti`, and both interactive and non-interactive modes | + +`ti` does not replace `ticloud`. Choose the CLI based on the resource and operation you need: + +- For new automation workflows with TiDB Cloud Starter, use `ti` when it supports the operations you need. +- For managing TiDB Cloud Filesystems, use `ti`. +- If you have existing `ticloud` workflows for TiDB Cloud Starter or TiDB Cloud Essential, you can continue to use them. +- For TiDB Cloud Essential or operations not available in `ti` (such as data import, data export, and audit log operations), use [`ticloud`](/tidb-cloud/cli-reference.md). + +## Next steps + +If you are new to the TiDB Cloud CLI, start with the [Quick Start](/ai/ti/ti-quick-start.md) to install `ti`, configure a profile, and complete a basic TiDB Cloud Starter or Filesystem workflow. + +Then continue based on what you want to do: + +- [Manage TiDB Cloud Starter Instances](/ai/ti/guides/manage-starter-instances.md) +- [Manage TiDB Cloud Filesystems](/ai/ti/guides/manage-filesystem-resources.md) +- **Follow end-to-end workflows**: Start with [Run a Daily TiDB Cloud CLI Workflow](/ai/ti/guides/ti-daily-workflow-example.md) or [Use TiDB Cloud Filesystem in an Agent Sandbox](/ai/ti/guides/ti-agent-sandbox-example.md) +- **Look up a specific command**: Check the [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) +- **See what’s new in TiDB Cloud CLI**: Check the [TiDB Cloud CLI (`ti`) Release Notes](https://github.com/tidbcloud/ti-cli/releases) +- **Report a problem**: 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..e9caa20c5fc7e --- /dev/null +++ b/ai/ti/ti-quick-start.md @@ -0,0 +1,197 @@ +--- +title: Get Started with TiDB Cloud CLI +summary: Install and configure TiDB Cloud CLI, then create and use a TiDB Cloud Filesystem or query a TiDB Cloud Starter database. +--- + +# Get Started with TiDB Cloud CLI + +[TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is a command-line tool for managing [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter) instances and [TiDB Cloud Filesystems](/tidb-cloud/tidb-cloud-glossary.md#tidb-cloud-filesystem). It supports both interactive use and automation, with JSON as the default output format for commands. + +This guide walks you through installing and configuring TiDB Cloud CLI (`ti`), and then completing a basic workflow with TiDB Cloud Starter or TiDB Cloud Filesystem. For an overview of the CLI, its capabilities, and supported workflows, see [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md). + +> **Note:** +> +> TiDB Cloud CLI (`ti`) is currently in public preview. Its features and command-line interface are subject to change without notice. + +## Prerequisites + +Before you begin, obtain a TiDB Cloud API public key and private key from the [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys) page in the [TiDB Cloud console](https://tidbcloud.com/). + +## Step 1. Install TiDB Cloud CLI + +Depending on your operating system, take the following steps to install TiDB Cloud CLI. + + + +
+ +1. On macOS or Linux, run the following command to install TiDB Cloud CLI: + + ```bash + curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh -s -- --yes + ``` + +2. Add `ti` to the current shell and verify it: + + ```bash + export PATH="$HOME/.ti/bin:$PATH" + ti --version + ``` + +3. Add `export PATH="$HOME/.ti/bin:$PATH"` to your shell profile to keep `ti` available in new terminals. + + For example, if you use `zsh`, run the following command: + + ```bash + echo 'export PATH="$HOME/.ti/bin:$PATH"' >> ~/.zshrc + source ~/.zshrc + ``` + +
+ +
+ +1. On Windows PowerShell, run the following command to install TiDB Cloud CLI: + + ```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 + ``` + +2. Add `ti` to the current PowerShell session and verify it: + + ```powershell + $env:Path = "$HOME\.ti\bin;$env:Path" + ti --version + ``` + +3. Add `$HOME\.ti\bin` to your user `PATH` to keep `ti` available in new PowerShell sessions: + + ```powershell + $tiBin = "$HOME\.ti\bin" + [Environment]::SetEnvironmentVariable("Path", "$tiBin;$([Environment]::GetEnvironmentVariable('Path', 'User'))", "User") + ``` + +
+ + +## Step 2. Configure TiDB Cloud CLI + +1. Run the interactive configuration: + + ```bash + ti configure + ``` + +2. Provide the following information: + + - A default region for CLI operations, specified as a region code (such as `aws-us-east-1`). For a list of regions that are supported by TiDB Cloud CLI, see [Supported regions](/ai/ti/reference/ti-regions-security-and-limitations.md#supported-regions). + - Your TiDB Cloud API public key and private key. + +3. Run a read-only command to verify that the CLI can access TiDB Cloud using the saved credentials: + + ```bash + ti db list-db-clusters --db-cluster-type starter --output text + ``` + + Example output: + + ```bash + { + "profile": "default", + "region_code": "aws-us-east-1", + "credentials_stored": true + } + ``` + +## Step 3. Choose a workflow + +Complete either of the following workflows. + +- [Option A: Create and use a Filesystem](/ai/ti/ti-quick-start.md#option-a-create-and-use-a-filesystem) +- [Option B: Create a TiDB Cloud Starter instance and query the database](/ai/ti/ti-quick-start.md#option-b-create-a-tidb-cloud-starter-instance-and-query-the-database) + +### Option A: Create and use a Filesystem + +A TiDB Cloud Filesystem is a persistent, shareable cloud file system that you can use across local machines, CI jobs, sandboxes, and other ephemeral environments. + +1. 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, so you do not need to provide it for subsequent file operations. + +2. Write a file to the Filesystem, and then read the file: + + ```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 + ``` + +3. Delete the Filesystem: + + ```bash + ti fs delete-file-system \ + --file-system-id "$TI_FS_FILE_SYSTEM_ID" + unset TI_FS_FILE_SYSTEM_ID + ``` + +### Option B: Create a TiDB Cloud Starter instance and query the database + +1. Create a TiDB Cloud Starter instance 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)" + ``` + +2. Create the SQL users and run a read-only query to verify the connection: + + ```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 `ti db execute-sql-statement` command executes the query through the HTTPS SQL API. The output includes `ready = 1`. + +3. Delete the TiDB Cloud Starter instance: + + ```bash + ti db delete-db-cluster \ + --db-cluster-id "$TI_DB_CLUSTER_ID" \ + --wait + unset TI_DB_CLUSTER_ID + ``` + +## What's next + +- Read the [TiDB Cloud Command Line Interface Overview](/ai/ti/ti-overview.md) to understand what `ti` manages and when to use it. +- Follow the task guides to manage [TiDB Cloud Starter instances](/ai/ti/guides/manage-starter-instances.md) or [Filesystem resources](/ai/ti/guides/manage-filesystem-resources.md). +- Explore the [TiDB Cloud CLI Command Reference](/ai/ti/reference/ti-cli-reference.md) for command groups, global options, and shared CLI behavior. +- Learn about [TiDB Cloud CLI Configuration and Credentials](/ai/ti/reference/ti-configuration-and-credentials.md) to set up multiple profiles or non-interactive authentication. diff --git a/ai/vector-search-get-started-using-python.md b/ai/vector-search-get-started-using-python.md index 7c235b84954b5..d1ec0026521e2 100644 --- a/ai/vector-search-get-started-using-python.md +++ b/ai/vector-search-get-started-using-python.md @@ -8,7 +8,7 @@ aliases: ['/tidb/stable/vector-search-get-started-using-python/','/tidb/dev/vect This tutorial demonstrates how to develop a simple AI application that provides **semantic search** features. Unlike traditional keyword search, semantic search intelligently understands the meaning behind your query and returns the most relevant result. For example, if you have documents titled "dog", "fish", and "tree", and you search for "a swimming animal", the application would identify "fish" as the most relevant result. -Throughout this tutorial, you will develop this AI application using [TiDB Vector Search](/ai/concepts/vector-search-overview.md), Python, [TiDB Vector SDK for Python](https://github.com/pingcap/tidb-vector-python), and AI models. +Throughout this tutorial, you will develop this AI application using [TiDB Vector Search](/ai/guides/vector-search-overview.md), Python, [TiDB Vector SDK for Python](https://github.com/pingcap/tidb-vector-python), and AI models. > **Note:** > @@ -51,7 +51,7 @@ pip install sqlalchemy pymysql sentence-transformers tidb-vector python-dotenv ``` - `tidb-vector`: the Python client for interacting with TiDB vector search. -- [`sentence-transformers`](https://sbert.net): a Python library that provides pre-trained models for generating [vector embeddings](/ai/concepts/vector-search-overview.md#vector-embedding) from text. +- [`sentence-transformers`](https://sbert.net): a Python library that provides pre-trained models for generating [vector embeddings](/ai/guides/vector-search-overview.md#vector-embedding) from text. ### Step 3. Configure the TiDB connection string @@ -117,7 +117,7 @@ The following are descriptions for each parameter: ### Step 4. Initialize the embedding model -An [embedding model](/ai/concepts/vector-search-overview.md#embedding-model) transforms data into [vector embeddings](/ai/concepts/vector-search-overview.md#vector-embedding). This example uses the pre-trained model [**msmarco-MiniLM-L12-cos-v5**](https://huggingface.co/sentence-transformers/msmarco-MiniLM-L12-cos-v5) for text embedding. This lightweight model, provided by the `sentence-transformers` library, transforms text data into 384-dimensional vector embeddings. +An [embedding model](/ai/guides/vector-search-overview.md#embedding-model) transforms data into [vector embeddings](/ai/guides/vector-search-overview.md#vector-embedding). This example uses the pre-trained model [**msmarco-MiniLM-L12-cos-v5**](https://huggingface.co/sentence-transformers/msmarco-MiniLM-L12-cos-v5) for text embedding. This lightweight model, provided by the `sentence-transformers` library, transforms text data into 384-dimensional vector embeddings. To set up the model, copy the following code into the `example.py` file. This code initializes a `SentenceTransformer` instance and defines a `text_to_embedding()` function for later use. diff --git a/basic-features.md b/basic-features.md index 2060844f0451f..76111ee92449f 100644 --- a/basic-features.md +++ b/basic-features.md @@ -111,7 +111,7 @@ You can try out TiDB features on [TiDB Playground](https://play.tidbcloud.com/?u | Advanced SQL features | 8.5 | 8.1 | 7.5 | 7.1 | 6.5 | 6.1 | 5.4 | |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| -| [Vector search](/ai/concepts/vector-search-overview.md) | E | N | N | N | N | N | N | +| [Vector search](/ai/guides/vector-search-overview.md) | E | N | N | N | N | N | N | | [Prepared statement cache](/sql-prepared-plan-cache.md) | Y | Y | Y | Y | Y | Y | Y | | [Non-prepared statement cache](/sql-non-prepared-plan-cache.md) | Y | Y | Y | E | N | N | N | | [Instance-level execution plan cache](/system-variables.md#tidb_enable_instance_plan_cache-new-in-v840) | E | N | N | N | N | N | N | diff --git a/develop/dev-guide-vector-search.md b/develop/dev-guide-vector-search.md index 573d750efb47e..0cd1df5555b6b 100644 --- a/develop/dev-guide-vector-search.md +++ b/develop/dev-guide-vector-search.md @@ -5,7 +5,7 @@ summary: Introduce the vector search feature in TiDB for developers, including c # Vector Search -[Vector search](/ai/concepts/vector-search-overview.md) enables semantic similarity searches across diverse data types such as documents, images, audio, and video. By leveraging your MySQL expertise, you can build scalable AI applications with advanced search functionality. +[Vector search](/ai/guides/vector-search-overview.md) enables semantic similarity searches across diverse data types such as documents, images, audio, and video. By leveraging your MySQL expertise, you can build scalable AI applications with advanced search functionality. ## Get started diff --git a/glossary.md b/glossary.md index b97cad05ff555..588365792a542 100644 --- a/glossary.md +++ b/glossary.md @@ -413,4 +413,4 @@ Universally Unique Identifier (UUID) is a 128-bit (16-byte) generated ID used to ### Vector search -[Vector search](/ai/concepts/vector-search-overview.md) is a search method that prioritizes the meaning of your data to deliver relevant results. Unlike traditional full-text search, which relies on exact keyword matching and word frequency, vector search converts various data types (such as text, images, or audio) into high-dimensional vectors and queries based on the similarity between these vectors. This search method captures the semantic meaning and contextual information of the data, leading to a more precise understanding of user intent. Even when the search terms do not exactly match the content in the database, vector search can still provide results that align with the user's intent by analyzing the semantics of the data. +[Vector search](/ai/guides/vector-search-overview.md) is a search method that prioritizes the meaning of your data to deliver relevant results. Unlike traditional full-text search, which relies on exact keyword matching and word frequency, vector search converts various data types (such as text, images, or audio) into high-dimensional vectors and queries based on the similarity between these vectors. This search method captures the semantic meaning and contextual information of the data, leading to a more precise understanding of user intent. Even when the search terms do not exactly match the content in the database, vector search can still provide results that align with the user's intent by analyzing the semantics of the data. diff --git a/releases/release-8.4.0.md b/releases/release-8.4.0.md index e6d6cd86e5239..9c022f5aa13ba 100644 --- a/releases/release-8.4.0.md +++ b/releases/release-8.4.0.md @@ -207,7 +207,7 @@ Quick access: [Quick start](https://docs-archive.pingcap.com/tidb/v8.4/quick-sta To enhance the performance of vector search, you can create and use [vector search indexes](/ai/reference/vector-search-index.md). Note that TiDB vector search indexes rely on TiFlash. Before using vector search indexes, make sure that TiFlash nodes are deployed in your TiDB cluster. - For more information, see [documentation](/ai/concepts/vector-search-overview.md). + For more information, see [documentation](/ai/guides/vector-search-overview.md). ### DB operations diff --git a/tidb-cloud/ai-feature-concepts.md b/tidb-cloud/ai-feature-concepts.md index 972e48cf148f1..6ac96102b6286 100644 --- a/tidb-cloud/ai-feature-concepts.md +++ b/tidb-cloud/ai-feature-concepts.md @@ -23,7 +23,7 @@ Unlike traditional full-text search, which relies on exact keyword matching and Even when the search terms do not exactly match the content in the database, vector search can still provide results that align with the user's intent by analyzing the semantics of the data. For example, a full-text search for "a swimming animal" only returns results containing these exact keywords. In contrast, vector search can return results for other swimming animals, such as fish or ducks, even if these results do not contain the exact keywords. -For more information, see [Vector Search (PREVIEW) Overview](/ai/concepts/vector-search-overview.md). +For more information, see [Vector Search (PREVIEW) Overview](/ai/guides/vector-search-overview.md). ## AI integrations @@ -37,7 +37,7 @@ For a list of supported AI frameworks, see [AI Integrations for TiDB](/ai/integr A vector embedding, also known as an embedding, is a sequence of numbers that represents real-world objects in a high-dimensional space. It captures the meaning and context of unstructured data, such as documents, images, audio, and videos. -Embedding models are algorithms that transform data into [vector embeddings](/ai/concepts/vector-search-overview.md#vector-embedding). The choice of an appropriate embedding model is crucial for ensuring the accuracy and relevance of semantic search results. +Embedding models are algorithms that transform data into [vector embeddings](/ai/guides/vector-search-overview.md#vector-embedding). The choice of an appropriate embedding model is crucial for ensuring the accuracy and relevance of semantic search results. TiDB Vector Search supports storing vectors of up to 16383 dimensions, which accommodates most embedding models. For unstructured text data, you can find top-performing text embedding models on the [Massive Text Embedding Benchmark (MTEB) Leaderboard](https://huggingface.co/spaces/mteb/leaderboard). diff --git a/tidb-cloud/cli-reference.md b/tidb-cloud/cli-reference.md index 742ddb62356e7..43f3a3ea600ad 100644 --- a/tidb-cloud/cli-reference.md +++ b/tidb-cloud/cli-reference.md @@ -1,15 +1,24 @@ --- -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 currently provides two CLIs with different scopes: [`ti`](https://github.com/tidbcloud/ti-cli) and [`ticloud`](https://github.com/tidbcloud/tidbcloud-cli). +> +> - `ti` is recommended for new automation workflows with TiDB Cloud Starter when it supports the operations you need. You can also use `ti` to manage TiDB Cloud Filesystems. To get started, see [TiDB Cloud CLI (`ti`) Quick Start](/ai/ti/ti-quick-start.md). +> - `ticloud` remains the CLI for TiDB Cloud Essential and for operations that [`ti`](/ai/ti/ti-overview.md) does not yet support, such as data import, data export, and audit log operations. +> +> For more information about when to use `ti` or `ticloud`, see [Differences between `ti` and `ticloud`](/ai/ti/ti-overview.md#differences-between-ti-and-ticloud). + +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. -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:** +> +> The `ticloud` CLI is currently in public preview and does not support TiDB Cloud Dedicated clusters. ## Before you begin diff --git a/tidb-cloud/connected-ai-chat-in-im.md b/tidb-cloud/connected-ai-chat-in-im.md index 210a0c44f0c1d..ae21139142014 100644 --- a/tidb-cloud/connected-ai-chat-in-im.md +++ b/tidb-cloud/connected-ai-chat-in-im.md @@ -5,7 +5,7 @@ summary: Introduces detailed information about the AI chat in Instant Message (I # Connected: AI chat in IM -The AI chat in Instant Message (IM) powered by PingCAP, is an offering to invite TiDB AI assistant chatbot to specific IM channels for preliminary technical support and consultation. This service is based on Graph RAG (Retrieval-Augmented Generation) built on top of [TiDB Vector Search](/ai/concepts/vector-search-overview.md). +The AI chat in Instant Message (IM) powered by PingCAP, is an offering to invite TiDB AI assistant chatbot to specific IM channels for preliminary technical support and consultation. This service is based on Graph RAG (Retrieval-Augmented Generation) built on top of [TiDB Vector Search](/ai/guides/vector-search-overview.md). ## Limitation diff --git a/tidb-cloud/get-started-with-cli.md b/tidb-cloud/get-started-with-cli.md index 425c141e73763..870621b66b251 100644 --- a/tidb-cloud/get-started-with-cli.md +++ b/tidb-cloud/get-started-with-cli.md @@ -1,11 +1,20 @@ --- -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:** +> +> TiDB Cloud currently provides two CLIs with different scopes: [`ti`](https://github.com/tidbcloud/ti-cli) and [`ticloud`](https://github.com/tidbcloud/tidbcloud-cli). +> +> - `ti` is recommended for new automation workflows with TiDB Cloud Starter when it supports the operations you need. You can also use `ti` to manage TiDB Cloud Filesystems. To get started, see [TiDB Cloud CLI (`ti`) Quick Start](/ai/ti/ti-quick-start.md). +> - `ticloud` remains the CLI for TiDB Cloud Essential and for operations that [`ti`](/ai/ti/ti-overview.md) does not yet support, such as data import, data export, and audit log operations. +> +> For more information about when to use `ti` or `ticloud`, see [Differences between `ti` and `ticloud`](/ai/ti/ti-overview.md#differences-between-ti-and-ticloud). + +TiDB Cloud provides the command-line interface (CLI) [`ticloud`](https://github.com/tidbcloud/tidbcloud-cli) for you to interact with TiDB Cloud Starter and Essential from your terminal with a few lines of commands. For example, you can perform the following operations using `ticloud`: - Create, delete, and list your {{{ .starter }}} or Essential instances. - Import data to your {{{ .starter }}} or Essential instances. @@ -13,7 +22,7 @@ TiDB Cloud provides a command-line interface (CLI) [`ticloud`](https://github.co > **Note:** > -> TiDB Cloud CLI is in public preview. +> The `ticloud` CLI is currently in public preview. ## Before you begin diff --git a/tidb-cloud/releases/release-notes-2024.md b/tidb-cloud/releases/release-notes-2024.md index 5d5fce67213c8..9944339ea421c 100644 --- a/tidb-cloud/releases/release-notes-2024.md +++ b/tidb-cloud/releases/release-notes-2024.md @@ -247,7 +247,7 @@ This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-c - Programming language support for Python: [SQLAlchemy](/ai/integrations/vector-search-integrate-with-sqlalchemy.md), [Peewee](/ai/integrations/vector-search-integrate-with-peewee.md), and [Django ORM](/ai/integrations/vector-search-integrate-with-django-orm.md). - Sample applications and tutorials: perform semantic searches for documents using [Python](/ai/quickstart-via-python.md) or [SQL](/ai/quickstart-via-sql.md). - For more information, see [Vector search (beta) overview](/ai/concepts/vector-search-overview.md). + For more information, see [Vector search (beta) overview](/ai/guides/vector-search-overview.md). - [TiDB Cloud Serverless](/tidb-cloud/select-cluster-tier.md#starter) now offers weekly email reports for organization owners. diff --git a/tidb-cloud/releases/tidb-cloud-release-notes.md b/tidb-cloud/releases/tidb-cloud-release-notes.md index 96dfa60baf3bb..e19b83ea1d28e 100644 --- a/tidb-cloud/releases/tidb-cloud-release-notes.md +++ b/tidb-cloud/releases/tidb-cloud-release-notes.md @@ -8,6 +8,18 @@ aliases: ['/tidbcloud/supported-tidb-versions','/tidbcloud/release-notes','/ai/v This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-cloud/) in 2026. +## September 15, 2026 + +**General changes** + +* **TiDB Cloud CLI** + + [TiDB Cloud CLI (`ti`)](https://github.com/tidbcloud/ti-cli) is now available in public preview for managing [TiDB Cloud Starter](/tidb-cloud/select-cluster-tier.md#starter) instances and TiDB Cloud Filesystems. A TiDB Cloud Filesystem is a serverless distributed file system designed for AI agents and automation workloads. + + You can use `ti` directly or let your scripts, CI jobs, and AI agents run it to automate TiDB Cloud workflows. With `ti`, you can create and manage TiDB Cloud Starter instances, execute SQL statements, and create and access persistent Filesystem workspaces through file commands or supported mounts. JSON output by default, JMESPath output queries, and support for `--wait` and `--dry-run` on applicable commands simplify automation. + + For more information, see [Get Started with TiDB Cloud CLI](/ai/ti/ti-quick-start.md) and [TiDB Cloud CLI (`ti`) Overview](/ai/ti/ti-overview.md). + ## September 8, 2026 **Console changes** diff --git a/tidb-cloud/tidb-cloud-glossary.md b/tidb-cloud/tidb-cloud-glossary.md index a89d9b2ad7fda..38e4070f1e5f1 100644 --- a/tidb-cloud/tidb-cloud-glossary.md +++ b/tidb-cloud/tidb-cloud-glossary.md @@ -69,7 +69,7 @@ For more information, see [Manage an endpoint](/tidb-cloud/data-service-manage-e ### Full-text search -Unlike [Vector Search](/ai/concepts/vector-search-overview.md), which focuses on semantic similarity, full-text search lets you retrieve documents for exact keywords. In Retrieval-Augmented Generation (RAG) scenarios, you can use full-text search together with vector search to improve the retrieval quality. +Unlike [Vector Search](/ai/guides/vector-search-overview.md), which focuses on semantic similarity, full-text search lets you retrieve documents for exact keywords. In Retrieval-Augmented Generation (RAG) scenarios, you can use full-text search together with vector search to improve the retrieval quality. For more information, see [Full-Text Search with SQL](/ai/guides/vector-search-full-text-search-sql.md) and [Full-Text Search with Python](/ai/guides/vector-search-full-text-search-python.md). @@ -193,6 +193,10 @@ For TiDB Cloud Dedicated and TiDB Self-Managed, a Request Unit (RU) is a resourc In TiDB Cloud, a cluster is a dedicated cloud deployment of TiDB that includes explicit infrastructure details such as node topology (where you can specify the number of [TiDB](/tidb-computing.md) nodes, [TiKV](/tidb-storage.md) nodes, and [TiFlash](/tiflash/tiflash-overview.md) nodes), storage configuration, and scaling model. +### TiDB Cloud Filesystem + +A TiDB Cloud Filesystem is a serverless distributed file system designed for AI agents and automation workloads. It provides a persistent, shareable file namespace that stays available independently of the local machine, sandbox, or CI runner that accesses it, making it useful for persistent storage, shared workspaces, and AI agent workflows. + ### TiDB node The computing node that aggregates data from queries returned from transactional or analytical stores. Increasing the number of TiDB nodes will increase the number of concurrent queries that the {{{ .dedicated }}} cluster can handle. @@ -232,7 +236,7 @@ A list of IP addresses and Classless Inter-Domain Routing (CIDR) addresses that ### Vector search -[Vector search](/ai/concepts/vector-search-overview.md) is a search method that prioritizes the meaning of your data to deliver relevant results. Unlike traditional full-text search, which relies on exact keyword matching and word frequency, vector search converts various data types (such as text, images, or audio) into high-dimensional vectors and queries based on the similarity between these vectors. This search method captures the semantic meaning and contextual information of the data, leading to a more precise understanding of user intent. Even when the search terms do not exactly match the content in the database, vector search can still provide results that align with the user's intent by analyzing the semantics of the data. +[Vector search](/ai/guides/vector-search-overview.md) is a search method that prioritizes the meaning of your data to deliver relevant results. Unlike traditional full-text search, which relies on exact keyword matching and word frequency, vector search converts various data types (such as text, images, or audio) into high-dimensional vectors and queries based on the similarity between these vectors. This search method captures the semantic meaning and contextual information of the data, leading to a more precise understanding of user intent. Even when the search terms do not exactly match the content in the database, vector search can still provide results that align with the user's intent by analyzing the semantics of the data. ### Virtual Private Cloud diff --git a/tiflash-upgrade-guide.md b/tiflash-upgrade-guide.md index 18ae00dac61c7..e52d4620094bb 100644 --- a/tiflash-upgrade-guide.md +++ b/tiflash-upgrade-guide.md @@ -136,7 +136,7 @@ Starting from v7.4, to reduce the read and write amplification generated during ## From v7.x to v8.4 or a later version -Starting from v8.4, the underlying storage format of TiFlash is updated to support [vector search](/ai/concepts/vector-search-overview.md). Therefore, after TiFlash is upgraded to v8.4 or a later version, in-place downgrading to the original version is not supported. +Starting from v8.4, the underlying storage format of TiFlash is updated to support [vector search](/ai/guides/vector-search-overview.md). Therefore, after TiFlash is upgraded to v8.4 or a later version, in-place downgrading to the original version is not supported. **Workaround for downgrading TiFlash in testing or other special scenarios**