Mount a File System
In TiDB Cloud Filesystem, you can work with files either by using ti fs commands directly or by mounting the file system as a local directory.
Mount your file system when an editor, application, agent, or other tool needs to access its files through local file paths. After mounting, the file system appears as a local directory, so the tool can read and write its files using normal filesystem operations.
If you only need to perform file operations through the CLI, such as reading, copying, organizing, or searching files, use ti fs commands directly instead of mounting the file system.
Choose a mount method
The available mount method depends on your environment:
Native file system mounting is not supported on Windows. On Windows, use direct commands such as ti fs copy-file, ti fs read-file, and ti fs list-files instead.
On macOS, WebDAV is sufficient for general file access and does not require additional mount software. FUSE is required for features such as mounting layers or checkpoints and using drain-file-system.
Use a token without configuring a profile
If another user or system administrator gives you a file system token, you can use that token from the current machine without configuring a ti profile or using the creator's API keys:
export TI_FS_TOKEN="<filesystem-token>"
export TI_REGION_CODE="<filesystem-region-code>"
Then follow the guide for your environment. The token identifies the file system and limits the paths and operations available to the current environment. Treat the token as a secret.
Common mount capabilities
File system mounts support several options that change what is exposed through the local mount:
Mount only part of the file system
By default, a mount exposes the file system root /. Use --remote-path to expose a specific remote directory instead. This is also useful when a scoped token grants access only to a specific path.
Create a read-only mount
Use --read-only to prevent writes through a particular mount. This option does not change the permissions of the file system token. To enforce read-only access at the service level, use a scoped token with read-only permissions.
Mount layers and checkpoints
Layers and checkpoints require FUSE. Checkpoint mounts are always read-only.
For layer and checkpoint workflows, see Manage File System Layers and Checkpoints.
Finish safely
Unmount when you are finished
Stop applications from writing to the mounted directory, close open files, and follow your platform guide to run ti fs unmount-file-system. A successful FUSE unmount flushes pending writes before stopping the mount. Unmounting removes the local mount but does not delete the file system or its data.
FUSE write behavior
FUSE mounts can temporarily have writes that have not yet reached the remote file system.
A normal successful unmount flushes pending writes, so you do not need to run drain-file-system before unmounting.
Use drain-file-system only when you need pending writes to reach the file system while keeping the mount running, such as before creating a checkpoint or making updated files available to another environment.
WebDAV mounts do not support drain-file-system.
What's next
Choose the guide for your environment:
For all mount options, see the mount-file-system command reference.