Get Started with TiDB Cloud Filesystem

TiDB Cloud Filesystem is a persistent, shared cloud file system for applications, automation, and AI agents. Files remain available independently of the machine or process that creates them, so you can reuse a workspace across sessions and environments.

This quick start guide walks you through how to create a file system, write and read files, and optionally mount it as a local directory.

Prerequisites

Before you begin, obtain a TiDB Cloud API public key and private key from the TiDB Cloud API Keys page in the TiDB Cloud console. The keys must grant Organization Owner access to your organization.

If someone has already provided you with a file system token, skip resource creation and follow Access an Existing File System.

Use Bash or Zsh on macOS and Linux, or PowerShell on Windows. Keep the same shell open throughout the tutorial. If an agent starts a new shell for each command, pass the environment variables and saved path values to each shell.

Step 1. Install TiDB Cloud CLI

Choose your operating system:

For permanent PATH setup on Windows and other installation options, see Install, Configure, and Update TiDB Cloud CLI.

Step 2. Configure TiDB Cloud CLI

Choose a supported region where you want to store your files, such as aws-us-west-2. The free tier allows one file system per region. If your organization already has one, reuse it, choose another region, or add a payment method.

1. Run the interactive configuration:

   ti configure
   

2. Provide the following information:

   • The region you selected.
   • Your TiDB Cloud API public key and private key.

The CLI saves your credentials and default region locally. The creation command in the next step uses this region.

Step 3. Create and use a file system

1. Create a file system:

   ti fs create-file-system --display-name agent-workspace --wait
   

   Copy the returned file_system_id for the next step. The CLI stores the owner token and region for the file system locally, so you do not need to enter the token again on the same machine.

   Note

   If you need to access the file system from another machine, also save the returned fs_token and region_code. The owner token grants full access and does not expire, so store it securely. For limited access, see Manage File System Tokens.

2. Select your new file system. Replace <file-system-id> with the returned file_system_id:

   export TI_FS_FILE_SYSTEM_ID="<file-system-id>"
   

   $env:TI_FS_FILE_SYSTEM_ID = "<file-system-id>"
   

3. Create a directory, upload a sample file, and read it back:

   ti fs create-directory --path /quick-start
   printf 'Hello from TiDB Cloud Filesystem\n' | ti fs copy-file \
     --from-stdin --to-remote /quick-start/hello.txt
   ti fs read-file --path /quick-start/hello.txt
   

   ti fs create-directory --path /quick-start
   "Hello from TiDB Cloud Filesystem" | ti fs copy-file `
     --from-stdin --to-remote /quick-start/hello.txt
   ti fs read-file --path /quick-start/hello.txt
   

   Expected output from read-file:

   Hello from TiDB Cloud Filesystem
   

   Your first file is now stored in TiDB Cloud Filesystem. To access it from another environment, see Access an Existing File System. To provide access to another user, application, or agent, see Share a File System.

Step 4. Mount the file system (optional)

Mount the file system if your application needs local file paths. Mounting is not supported on Windows. If you are using Windows or only need CLI access, skip to Step 5.

1. Create an empty local directory for the mount:

   mount_dir="$(mktemp -d "$HOME/ti-fs-quick-start.XXXXXX")"
   

2. Mount the /quick-start directory using the command for your operating system:

   This command uses macOS's built-in WebDAV support:

   ti fs mount-file-system --remote-path /quick-start \
     --mount-path "$mount_dir" --driver webdav
   

   Linux requires the fuse3 package and access to /dev/fuse. If needed, follow Install FUSE userspace tools before running the mount command.

   ti fs mount-file-system --remote-path /quick-start \
     --mount-path "$mount_dir" --driver fuse
   

3. Read your file using its local path:

   cat "$mount_dir/hello.txt"
   

   Expected output:

   Hello from TiDB Cloud Filesystem
   

For write verification and troubleshooting, see Verify a mount before using it.

Step 5. Clean up the example (optional)

If you mounted the directory in Step 4, close applications using it, then unmount and remove the empty local mount directory:

ti fs unmount-file-system --mount-path "$mount_dir"
rmdir "$mount_dir"

If unmount fails, follow Finish safely before continuing.

Delete the example directory and its files. This command works on all supported operating systems:

ti fs delete-file --path /quick-start --recursive

The file system and its token remain available for reuse. To remove the entire file system, see Delete a file system.

What's next

• Access an Existing File System to reuse locally stored credentials or connect from another environment.
• Configure for automation to set up CLI credentials for CI jobs or agents.
• Manage File Systems in TiDB Cloud Filesystem to inspect and manage your file systems.
• Manage File System Tokens to create, inspect, and manage tokens for file system access.
• Mount a File System to access its files through a local directory.
• Share a File System to make the same files available to another machine, user, application, or agent.
• Manage File System Layers and Checkpoints to isolate, review, and apply file changes.