mount-tidb-cloud-fs

Mount a TiDB Cloud Filesystem

Mount an existing TiDB Cloud Filesystem without configuring a ti profile. Do not use this skill to create or delete a file system or to manage its tokens.

This token-only workflow requires ti v0.2.1 or later. The CLI is currently in preview; if installed behavior differs, run ti fs mount-file-system --help and check the official repository: https://github.com/tidbcloud/ti-cli.

Required inputs

Input	Required	Purpose
TI_FS_TOKEN	yes	Owner or scoped Filesystem token. It authenticates the request and identifies the file system.
TI_REGION_CODE	yes	Routing region, for example aws-us-east-1. Use --region only as an explicit alternative.
MOUNT_PATH	yes	Local directory where the file system will be mounted.
TI_FS_FILE_SYSTEM_ID	no	Optional consistency assertion. ti normally derives the ID from the token.

The token does not remove the need for an explicit region in a clean environment. Do not run ti configure or supply TiDB Cloud API keys for this workflow.

Workflow

1. Validate the inputs

: "${TI_FS_TOKEN:?Set TI_FS_TOKEN to an existing Filesystem token}"
: "${TI_REGION_CODE:?Set TI_REGION_CODE to the Filesystem region}"
: "${MOUNT_PATH:?Set MOUNT_PATH to the local mount directory}"

Never print or log TI_FS_TOKEN. Let ti validate the token format and its remote permissions.

2. Install or verify ti

if ! command -v ti >/dev/null 2>&1; then
  curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh \
    | sh -s -- --yes
  export PATH="$HOME/.ti/bin:$PATH"
fi

ti --version

Require v0.2.1 or later. If an older version is installed, upgrade it before mounting with ti update.

3. Prepare the mount path and driver

mkdir -p -- "$MOUNT_PATH"

Prefer a new or empty directory. Do not hide existing local files by mounting over a non-empty directory unless the user explicitly intends that behavior.

Choose the driver by platform:

• On Linux, use FUSE only. Never pass --driver webdav; the current ti implementation rejects WebDAV mounts on Linux.
• macOS automatically uses macFUSE when available and otherwise uses the system WebDAV mount helper. Install macFUSE only when FUSE behavior is required.
• Windows local mounting is not supported by the v0.2.3 implementation. Use Filesystem data-plane commands or mount from a supported Linux/macOS host.

On Linux, do not stop after discovering that fusermount3 or fusermount is missing. Attempt to install the FUSE userspace package first. Do not infer that installation is impossible from a read-only workspace; run the package manager and report its actual error if it fails.

if [ "$(uname -s)" = "Linux" ] &&
   ! command -v fusermount3 >/dev/null 2>&1 &&
   ! command -v fusermount >/dev/null 2>&1; then
  if [ "$(id -u)" -eq 0 ]; then
    fuse_privilege=()
  elif command -v sudo >/dev/null 2>&1; then
    fuse_privilege=(sudo)
  else
    echo "FUSE tools are missing and root or sudo is required to install them" >&2
    exit 1
  fi

  if command -v apt-get >/dev/null 2>&1; then
    "${fuse_privilege[@]}" apt-get update
    "${fuse_privilege[@]}" apt-get install -y fuse3
  elif command -v dnf >/dev/null 2>&1; then
    "${fuse_privilege[@]}" dnf install -y fuse3
  elif command -v yum >/dev/null 2>&1; then
    "${fuse_privilege[@]}" yum install -y fuse3 ||
      "${fuse_privilege[@]}" yum install -y fuse
  elif command -v apk >/dev/null 2>&1; then
    "${fuse_privilege[@]}" apk add --no-cache fuse3
  else
    echo "Unsupported package manager; install fuse3 manually" >&2
    exit 1
  fi

  hash -r
fi

if [ "$(uname -s)" = "Linux" ]; then
  command -v fusermount3 >/dev/null 2>&1 ||
    command -v fusermount >/dev/null 2>&1 ||
    { echo "FUSE userspace tools are still unavailable" >&2; exit 1; }

  if [ ! -c /dev/fuse ]; then
    echo "FUSE tools are installed, but /dev/fuse is not exposed" >&2
    echo "Expose /dev/fuse and grant mount permissions in the host or container runtime" >&2
    exit 1
  fi
fi

4. Mount the file system

mount_driver=auto
if [ "$(uname -s)" = "Linux" ]; then
  mount_driver=fuse
fi

ti fs mount-file-system \
  --mount-path "$MOUNT_PATH" \
  --driver "$mount_driver" \
  --ready-timeout 60s

Rely on the environment variables instead of passing --fs-token; command-line arguments can be exposed through shell history or process inspection.

The mount runs in the background and returns after it is ready. Useful options:

• Add --read-only for inspection or when the token has no write permission.
• Add --foreground when debugging the mount process.
• On macOS, override auto with --driver fuse or --driver webdav only when required. Never use --driver webdav on Linux.
• Use --query and --output when an agent needs a specific machine-readable result.

5. Verify access

ls -la -- "$MOUNT_PATH"

If write access is expected, create a unique probe rather than overwriting a fixed path. Skip this check for a read-only mount or a token without write permission.

probe_path="$(mktemp "$MOUNT_PATH/.ti-mount-probe.XXXXXX")"
printf 'mount probe\n' > "$probe_path"
cat -- "$probe_path"
rm -f -- "$probe_path"

6. Unmount when finished

ti fs unmount-file-system --mount-path "$MOUNT_PATH"

Troubleshooting

• A missing region fails even when the token is valid. Set TI_REGION_CODE or pass --region <code>.
• A supplied TI_FS_FILE_SYSTEM_ID must match the ID derived from the token.
• A scoped token can access only its allowed paths and operations. Do not assume it permits writes.
• On Linux, do not treat missing FUSE userspace tools as a final blocker. Run the installation workflow, then report the actual failing command or missing /dev/fuse device or permissions. Never switch to WebDAV.
• If a background mount times out, inspect the log path reported by ti and retry with --foreground.