📣

TiDB Cloud Premium is now in public preview. Unlimited growth, instant elasticity, advanced security for enterprise workloads. Try it out →

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 <duration> | --no-expiration) means that you must specify exactly one of the two options.

Resource and token commands

Command	Description
`create-file-system`	Creates a Filesystem and its initial owner token.
`list-file-systems`	Lists Filesystems in the effective region.
`describe-file-system`	Describes one Filesystem by ID.
`check-file-system`	Checks Filesystem selection, routing, credentials, and data-plane access.
`delete-file-system`	Permanently deletes a Filesystem.
`import-file-system-token`	Imports and selects an existing Filesystem token locally.
`generate-file-system-token`	Generates an additional owner token.
`generate-file-system-scoped-token`	Generates a token limited by path, operation, and lifetime.
`list-file-system-tokens`	Lists non-secret token metadata.
`enable-file-system-token`	Re-enables a disabled token.
`disable-file-system-token`	Temporarily disables a token.
`delete-file-system-token`	Permanently revokes a token.
`refresh-file-system-token`	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`	Describes the media extraction provider configuration.
`update-file-system-extract-configuration`	Updates the provider used to extract media content.
`describe-file-system-embedding-configuration`	Describes the embedding provider configuration.
`update-file-system-embedding-configuration`	Updates the provider used to generate embeddings.

Data and namespace commands

Command	Description
`copy-file`	Copies files between local storage and a Filesystem, or within a Filesystem.
`read-file`	Reads a remote file or byte range.
`list-files`	Lists entries under a remote path.
`describe-file`	Describes a remote file or directory.
`move-file`	Moves or renames a remote path.
`delete-file`	Deletes a remote file or directory.
`create-directory`	Creates a remote directory.
`chmod-file`	Changes POSIX-style mode metadata.
`create-symlink`	Creates a symbolic link.
`create-hardlink`	Creates a hard link.
`search-file-content`	Searches extracted file content and descriptions.
`find-files`	Finds files by name, tag, date, size, or type.

Layer and portability commands

Command	Description
`create-layer`	Creates an isolated writable layer.
`list-layers`	Lists layers in a Filesystem.
`fork-layer`	Forks a child layer from a parent tip or checkpoint.
`list-layer-chain`	Lists the pinned ancestry of a layer.
`describe-layer`	Describes a layer by ID.
`diff-layer`	Lists changes recorded in a layer.
`create-layer-checkpoint`	Creates a durable checkpoint in a layer.
`delete-layer`	Logically abandons a layer.
`rollback-layer`	Rolls a layer back without committing its changes.
`commit-layer`	Applies a layer's changes to the base Filesystem.
`pack-file-system`	Archives selected local overlay state to the Filesystem.
`unpack-file-system`	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:<key>=<value>, 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`	Mounts a Filesystem at a local path.
`drain-file-system`	Flushes pending writes from a live FUSE mount.
`unmount-file-system`	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.