+
+
+
+1. In the left navigation pane of the [TiDB Cloud console](https://tidbcloud.com), select your organization and click **File Systems**.
+2. In the upper-right corner, click **Create File System**.
+3. On the **Create File System** page, enter a file system name, and select a **Cloud Provider** and **Region**.
+4. (Optional) Review and edit the usage limits in the summary.
+
+ To edit the usage limits, add a credit card to your organization. Without a credit card, the free limits cannot be edited during creation. For more information, see [Manage Usage Limit](/tidb-cloud-filesystem/manage-filesystem-limits.md).
+
+5. Click **Create**. The **Your File System is Ready!** dialog offers optional steps to install TiDB Cloud CLI and mount the file system on macOS or Linux. The default owner token in the mount command is shown only once; save it securely before closing the dialog.
+
+
+
+
+
Create a file system and wait until it is ready:
```shell
@@ -43,8 +61,27 @@ Setting `TI_FS_FILE_SYSTEM_ID` lets subsequent commands identify the target file
>
> Do not put credentials, connection strings, private paths, or personal data in file system labels.
+
+
+
+
## List and inspect file systems
+
+
+
+
+1. In the left navigation pane of the [TiDB Cloud console](https://tidbcloud.com), select your organization and click **File Systems**.
+2. On the [**File Systems**](https://tidbcloud.com/filesystems) page, select a cloud provider and region to list file systems in that location. Use **Search Name** or **Status** to narrow the list.
+
+To view details of a file system, click the file system's name to go to its overview page.
+
+To change its display name, click **...** in the upper-right corner of the overview page and select **Rename**.
+
+
+
+
+
List the file systems available in the current region:
```shell
@@ -66,6 +103,10 @@ The CLI does not automatically select a file system based on the number of file
The current CLI does not provide a command to change a file system's display name or labels after creation. Choose these values when you create the file system.
+
+
+
+
## Check access
Check whether the CLI can access a file system:
@@ -87,6 +128,20 @@ For common access and connectivity issues, see [Troubleshoot TiDB Cloud Filesyst
>
> Deleting a file system permanently removes its remote data. Before deletion, stop applications that are using the file system and successfully unmount any active local mounts. For information about finishing pending writes safely, see [Finish safely](/tidb-cloud-filesystem/filesystem-mount.md#finish-safely).
+
+
+
+
+1. In the TiDB Cloud console, open your organization's [**File Systems**](https://tidbcloud.com/filesystems) page, then select the **Cloud Provider** and **Region** for the target file system.
+2. In the row of the target file system, click **...**, and then select **Delete**.
+3. In the confirmation dialog, enter the requested region and file system name in the form `region/name`, then click **I understand, delete it.**
+
+Deletion is asynchronous. After the request is submitted, the file system might remain visible with the status `deleting` until deletion finishes.
+
+
+
+
+
Delete a file system by its ID:
```shell
@@ -95,6 +150,10 @@ ti fs delete-file-system --file-system-id ""
File system deletion is asynchronous. After the service accepts the request, the CLI reports the file system status as `deleting` and removes the matching locally stored credential. This status means that deletion has started, not that the remote file system and its data have already been removed.
+
+
+
+
## What's next
- [Manage File System Tokens](/tidb-cloud-filesystem/manage-filesystem-tokens.md) to generate, delegate, rotate, or revoke file system access.
diff --git a/tidb-cloud-filesystem/manage-filesystem-tokens.md b/tidb-cloud-filesystem/manage-filesystem-tokens.md
index fa912a70f5aa8..539e11f120a49 100644
--- a/tidb-cloud-filesystem/manage-filesystem-tokens.md
+++ b/tidb-cloud-filesystem/manage-filesystem-tokens.md
@@ -8,34 +8,47 @@ aliases: ['/ai/manage-filesystem-tokens']
In TiDB Cloud Filesystem, you can use file system tokens to give users, applications, and automation access to a file system without sharing your TiDB Cloud API credentials.
-An [owner token](/tidb-cloud-filesystem/filesystem-authorization.md#owner-tokens) grants full access to a file system. A [scoped token](/tidb-cloud-filesystem/filesystem-authorization.md#scoped-tokens) limits access to specific paths and operations. For details, see [Authorization](/tidb-cloud-filesystem/filesystem-authorization.md).
+- An [owner token](/tidb-cloud-filesystem/filesystem-authorization.md#owner-tokens) grants full access to a file system.
+- A [scoped token](/tidb-cloud-filesystem/filesystem-authorization.md#scoped-tokens) limits access to specific paths and operations.
## Prerequisites
Before you begin:
-- [Install TiDB Cloud CLI](/tidb-cloud-filesystem/filesystem-quick-start.md#step-1-install-tidb-cloud-cli).
-- Have access to an existing file system in TiDB Cloud Filesystem. If you do not have one, follow [Get Started with TiDB Cloud Filesystem](/tidb-cloud-filesystem/filesystem-quick-start.md) to create one.
+- Have access to an existing file system in TiDB Cloud Filesystem. If you do not have one, follow [Quick Start via Console](/tidb-cloud-filesystem/filesystem-quick-start-console.md) or [Quick Start via CLI](/tidb-cloud-filesystem/filesystem-quick-start.md) to create one.
+- For CLI operations, [install TiDB Cloud CLI](/tidb-cloud-filesystem/filesystem-quick-start.md#step-1-install-tidb-cloud-cli).
-Listing, enabling, disabling, and deleting tokens require either an owner token supplied through `TI_FS_TOKEN` or `--fs-token`, or TiDB Cloud API credentials with an explicit `--file-system-id`. These operations do not use a locally stored token automatically. Scoped-token generation can use a locally stored owner token. Each section below explains any additional requirements.
+To list, enable, disable, or delete tokens with the CLI, provide an owner token through `TI_FS_TOKEN` or `--fs-token`, or use TiDB Cloud API credentials with an explicit `--file-system-id`. These operations do not automatically use a locally stored token. Scoped-token generation can use a locally stored owner token. Each section below explains any additional requirements.
> **Note:**
>
-> Store file system tokens securely. Commands that create or refresh a token return its value only once; you cannot retrieve it later.
+> Store file system tokens securely. When you create or refresh a token, its plaintext is returned only once and cannot be retrieved later.
## Import an existing token
-If you already have a file system token, import it to the local CLI credential store:
+If you already have a file system token, including the default owner token shown when you create a file system in the TiDB Cloud console, save its plaintext to a secure file and import it to the local CLI credential store:
```shell
-ti fs import-file-system-token --from-file ./fs-token --region aws-us-east-1
+ti fs import-file-system-token --from-file ./fs-token --region ""
```
-The CLI validates the token, extracts the file system ID from it, verifies connectivity, and stores the token locally.
+The CLI validates the token, extracts the file system ID from it, verifies connectivity, and stores the token locally. If the token is still available through `TI_FS_TOKEN`, you can use it for CLI commands without importing it.
## Generate an owner token
-Creating a file system returns an owner token. That token does not expire, and the CLI stores it locally and uses it for later commands. Before you revoke it, generate and validate a replacement as described in [Rotate or revoke a token](#rotate-or-revoke-a-token). Tokens you generate later with `--ttl` expire on their own.
+
+
+
+
+The TiDB Cloud console creates a default owner token when you create a file system. Its plaintext appears only in the **Your File System is Ready!** dialog.
+
+For an additional owner token, use the **CLI** tab.
+
+
+
+
+
+When you create a file system with the CLI, it returns a non-expiring owner token, stores it locally, and uses it for later commands.
Generate an additional owner token when another trusted environment needs full access.
@@ -57,8 +70,37 @@ ti fs generate-file-system-token \
The CLI does not store the generated token locally by default. To store it locally, add `--store-locally` to the preceding command. If a different token is already stored for this file system, also add `--replace`.
+
+
+
+
## Generate and delegate a scoped token
+
+
+
+
+If you want to restrict a token to a specific directory, create that directory before generating the token.
+
+1. In the TiDB Cloud console, navigate to the [**File Systems**](https://tidbcloud.com/filesystems) page, select the cloud provider and region, and then click the name of your target file system.
+2. On the overview page of the file system, click **Access Tokens** in the left navigation pane.
+3. In the upper-right corner, click **Create Token**.
+4. Configure the token by providing the following information:
+
+ - **Token name**: enter a name for the token.
+ - **Access path (optional)**: specify an access path to limit the token's access to a specific directory. If you leave the path empty, the token applies to `/`.
+ - **Expiration**: choose when the token expires. The default is one hour.
+ - **Permission**: select only the operations the token needs. For details, see [Authorization](/tidb-cloud-filesystem/filesystem-authorization.md#scoped-tokens).
+
+5. Click **Create**.
+6. In the displayed dialog, copy the token and store it securely before clicking **Done**. Its plaintext is shown only once.
+
+Provide the token and file system region to the receiving environment. When mounting with a token restricted to a directory, set the CLI `--remote-path` option to that directory.
+
+
+
+
+
On a trusted machine, use an owner token to generate a scoped token. Supply the owner token through `--fs-token` or `TI_FS_TOKEN`, or use the owner token stored locally for the selected file system.
Before using this example, create the remote `/workspace` directory if it does not exist. Use the locally stored owner token to grant an agent permission to read, list, and write files in that directory:
@@ -87,8 +129,29 @@ To mount the directory with this token, specify `--remote-path /workspace`. A to
For more information about scoped permissions and credential selection, see [Authorization](/tidb-cloud-filesystem/filesystem-authorization.md).
+
+
+
+
## Inspect and change token status
+> **Warning:**
+>
+> Before deactivating, rotating, or deleting a token used by an active mount, stop applications that are writing to the mount and successfully unmount it. The CLI can detect known local mounts but cannot discover mounts on other machines. Coordinate with those machines before changing the token. For more information, see [Finish safely](/tidb-cloud-filesystem/filesystem-mount.md#finish-safely).
+
+
+
+
+
+1. In the TiDB Cloud console, navigate to the [**File Systems**](https://tidbcloud.com/filesystems) page, select the cloud provider and region, and then click the name of your target file system.
+2. On the overview page of the file system, click **Access Tokens** in the left navigation pane.
+3. On the **Access Tokens** page, you can view each token's ID, status, access path, permissions, expiration, and creation time.
+4. To suspend a token, click **...** in the row of the target token, and then select **Deactivate**. To restore a deactivated token, click **...**, and then select **Activate**.
+
+
+
+
+
For an owner-token-only environment, set `TI_FS_TOKEN` to the owner token and `TI_REGION_CODE` to the file system's region before running the commands below. Keep management credentials separate from the scoped token you give to the recipient. A scoped token cannot manage other tokens.
List non-secret metadata for file system tokens:
@@ -101,12 +164,30 @@ ti fs list-file-system-tokens \
The output does not include token plaintext. If you lose an owner token, generate a replacement using TiDB Cloud API credentials. You cannot recover the original token by listing tokens.
-Use [`disable-file-system-token`](/ai/ti/reference/ti-fs-disable-file-system-token.md) to temporarily suspend a token, and [`enable-file-system-token`](/ai/ti/reference/ti-fs-enable-file-system-token.md) to restore it.
+Use [`disable-file-system-token`](/ai/ti/reference/ti-fs-disable-file-system-token.md) to temporarily suspend a token, and [`enable-file-system-token`](/ai/ti/reference/ti-fs-enable-file-system-token.md) to restore it. These correspond to **Deactivate** and **Activate** in the console.
With owner token authentication, these two commands can change only scoped tokens. To enable or disable an owner token, use TiDB Cloud API credentials, specify `--file-system-id`, and unset `TI_FS_TOKEN` so it does not override the API credentials. Do not supply `--fs-token` for that request. Allow approximately 10 seconds for the change to take effect before verifying access.
+
+
+
+
## Rotate or revoke a token
+To rotate or revoke a token, it is recommended to use the CLI commands. The TiDB Cloud console does not offer the `refresh-file-system-token` operation of the CLI.
+
+
+
+
+
+To replace a scoped token in the TiDB Cloud console, [create a new token](#generate-and-delegate-a-scoped-token) with the required path, permissions, and expiration. Distribute and validate the new token before retiring the old one. Then, go to the **Access Tokens** page of the target file system, locate the row of the old token, click **...**, and then select **Delete**.
+
+To replace an owner token, [generate another owner token with the CLI](#generate-an-owner-token) before deleting the old one in the TiDB Cloud console.
+
+
+
+
+
Use [`refresh-file-system-token`](/ai/ti/reference/ti-fs-refresh-file-system-token.md) to rotate a file system token.
When you refresh a locally stored token, the CLI automatically updates the local credential. 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 locally.
@@ -115,10 +196,6 @@ When you refresh a locally stored token, the CLI automatically updates the local
>
> If a refresh request times out, the service might have rotated the token without returning the new value to you. Do not retry with the old token. Generate a new owner token using TiDB Cloud API credentials.
-> **Warning:**
->
-> Before rotating, disabling, or deleting a token used by an active mount, stop applications that are writing to the mount and successfully unmount it. The CLI can detect known local mounts but cannot discover mounts on other machines. Coordinate with those machines before changing the token. For more information, see [Finish safely](/tidb-cloud-filesystem/filesystem-mount.md#finish-safely).
-
Before retiring a token, distribute and validate its replacement. Then revoke the old token by its token ID:
```shell
@@ -131,6 +208,10 @@ If the deleted token matches the locally stored token, the CLI automatically rem
Disabling or revoking an owner token does not automatically revoke scoped tokens generated from it. Review and revoke those scoped tokens separately when necessary.
+
+
+
+
## What's next
- [Share a File System](/tidb-cloud-filesystem/filesystem-sharing.md)
diff --git a/tidb-cloud-filesystem/work-with-filesystem-data.md b/tidb-cloud-filesystem/work-with-filesystem-data.md
index 3b7fc9f9ee808..ccd86b8fef4e4 100644
--- a/tidb-cloud-filesystem/work-with-filesystem-data.md
+++ b/tidb-cloud-filesystem/work-with-filesystem-data.md
@@ -1,23 +1,63 @@
---
title: Work with Files and Directories in TiDB Cloud Filesystem
-summary: Learn how to upload, download, read, organize, and search files in TiDB Cloud Filesystem using CLI commands without a local mount.
+summary: Learn how to view file metadata in the console and upload, download, read, organize, and search files with TiDB Cloud CLI.
aliases: ['/ai/work-with-filesystem-data']
---
# Work with Files and Directories in TiDB Cloud Filesystem
-In TiDB Cloud Filesystem, you can use TiDB Cloud CLI (`ti`) to upload, download, read, organize, and search files without mounting the file system. For all commands and options, see the [`ti fs` reference](/ai/ti/reference/ti-filesystem.md).
+In TiDB Cloud Filesystem, you can browse file and directory metadata in the TiDB Cloud console or use TiDB Cloud CLI (`ti`) to upload, download, read, organize, and search files without mounting the file system. For all commands and options, see the [`ti fs` reference](/ai/ti/reference/ti-filesystem.md).
-If your tools need local file paths, [mount the file system](/tidb-cloud-filesystem/filesystem-mount.md).
+If you [mount the file system](/tidb-cloud-filesystem/filesystem-mount.md) to your machine, you can work with files and directories as you do with a local file system.
## Prerequisites
-Before you begin:
+The following prerequisites apply to CLI operations. If you only need to browse file metadata in the TiDB Cloud console, see [View files](#view-files-via-the-console).
- [Install TiDB Cloud CLI](/tidb-cloud-filesystem/filesystem-quick-start.md#step-1-install-tidb-cloud-cli).
- [Create a file system](/tidb-cloud-filesystem/manage-filesystem-resources.md) or obtain access to an existing one.
- Select the file system and make its token available to `ti`. For available access options, see [Access an Existing File System](/tidb-cloud-filesystem/access-filesystem.md).
+## View files
+
+
+
+
+
+1. In the [TiDB Cloud console](https://tidbcloud.com/), navigate to the [**File Systems**](https://tidbcloud.com/filesystems) page for your organization, select the cloud provider and region, and then click the name of your target file system.
+2. In the left navigation pane, click **Files**. The page lists directories and files with their type, size, and modification time.
+3. Expand a directory to browse its contents, use **Search** to filter the visible file tree, or click a file name to view its metadata.
+
+The console displays file metadata. To read file contents or change files and directories, use the CLI commands or [mount the file system](/tidb-cloud-filesystem/filesystem-mount.md).
+
+
+
+
+
+List the contents of a directory:
+
+```shell
+ti fs list-files --path /reports --output text
+```
+
+Example output:
+
+```text
+NAME TYPE SIZE MTIME
+archive dir 0 0
+report.md file 23 0
+```
+
+Inspect metadata for a file or directory:
+
+```shell
+ti fs describe-file --path /reports/report.md
+```
+
+
+
+
+
## Upload and download files
Upload a local file to the file system:
@@ -41,7 +81,7 @@ You can also use `copy-file` to copy files or directories within the file system
To copy a directory recursively, use `--recursive`. For all supported copy operations and options, see the [`copy-file` reference](/ai/ti/reference/ti-fs-copy-file.md).
-## Read and inspect files and directories
+## Read files
Read the complete contents of a file:
@@ -60,26 +100,6 @@ ti fs read-file \
--length 1024
```
-List the contents of a directory:
-
-```shell
-ti fs list-files --path /reports --output text
-```
-
-Example output:
-
-```text
-NAME TYPE SIZE MTIME
-archive dir 0 0
-report.md file 23 0
-```
-
-Inspect metadata for a file or directory:
-
-```shell
-ti fs describe-file --path /reports/report.md
-```
-
## Organize files and directories
Create a directory: