Work with Files and Directories in TiDB Cloud Filesystem

You can work with files and directories in TiDB Cloud Filesystem directly from TiDB Cloud CLI (ti) without mounting the file system.

Use ti fs commands to upload and download files, read file contents, list and inspect paths, organize files and directories, and search for data. For the complete command reference, see ti fs reference.

Prerequisites

Before you begin:

• Install TiDB Cloud CLI.
• Create a file system 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.

Upload and download files

Upload a local file to the file system:

ti fs copy-file \
  --from-local ./report.md \
  --to-remote /reports/report.md

Download a file from the file system:

ti fs copy-file \
  --from-remote /reports/report.md \
  --to-local ./downloads/report.md \
  --create-parents

You can also use copy-file to copy files or directories within the file system, stream data through standard input or output, append to a file, or resume an interrupted transfer.

To copy a directory recursively, use --recursive. For all supported copy operations and options, see the copy-file reference.

Read and inspect files and directories

Read the complete contents of a file:

ti fs read-file --path /reports/report.md

To read only part of a file, use --offset and --length. For example, the following command reads the first 1024 bytes:

ti fs read-file \
  --path /reports/report.md \
  --offset 0 \
  --length 1024

List the contents of a directory:

ti fs list-files --path /reports --output text

Inspect metadata for a file or directory:

ti fs describe-file --path /reports/report.md

Organize files and directories

Create a directory:

ti fs create-directory --path /reports/archive

Move a file to another path:

ti fs move-file \
  --from-remote /draft.md \
  --to-remote /reports/final.md

Delete a file or directory:

ti fs delete-file --path /scratch --recursive

For workflows that need POSIX-style metadata or links, you can also use chmod-file, create-symlink, and create-hardlink.

Search files and content

Use search-file-content when you want to find files based on their content:

ti fs search-file-content \
  --path /reports \
  --pattern "TODO"

--pattern is a text query, not a regular expression or glob. Use --limit to control the maximum number of results.

For details, see the search-file-content reference.

If you know something about the file itself rather than its contents, use find-files. You can filter by file name, type, tags, size, or modification time.

For example, find Markdown files tagged stage=review:

ti fs find-files \
  --path /reports \
  --file-name-pattern "*.md" \
  --tag stage=review

For all available filters, see the find-files reference.

What's next

• Mount a File System to work with file system data through a local directory and existing local tools.
• Manage File System Layers and Checkpoints to make and review isolated changes before applying them to the base file system.
• Share a File System Across Machines to give another machine or environment access to the file system.
• TiDB Cloud Filesystem CLI Command Reference for complete command syntax and options.