📣
TiDB Cloud Premium is now in public preview. Unlimited growth, instant elasticity, advanced security for enterprise workloads. Try it out →
​
Sign InStart for Free
AI
Developer
Best Practices
API
​
Sign InStart for Free

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.

If your tools need local file paths, mount the file system.

Prerequisites

Before you begin:

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

The command writes file contents directly to standard output; it does not wrap them in JSON.

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

Example output:

NAME       TYPE  SIZE  MTIME
archive    dir   0     0
report.md  file  23    0

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 to find files by 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

Tags are set when you upload a file, with copy-file --tag key=value. Supplying --tag on a later upload of the same path replaces the previous tags instead of adding to them.

The result lists matching paths. An empty table means that nothing matched, not that the command failed.

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

Use command output in scripts

Check the exit status before using command output. read-file and copy-file --to-stdout stream file contents, not CLI metadata. Keep stderr separate when capturing those contents.

In ti v0.2.6 and v0.2.7, create-directory can print a created ... line before its JSON result, even with --output json. Its output cannot be parsed as a single JSON document. Check the exit status, then verify the directory with describe-file or list-files. Check your installed version's output format before relying on it in scripts.

What's next

Was this page helpful?