mount-tidb-cloud-fs git:20260818.ad6ce7aA

Immutable. This exact content never changes and is served at /api/v1/blob/89cd08ba7f8ee443.

---
name: mount-tidb-cloud-fs
description: Mount an existing TiDB Cloud Filesystem to a local directory with the ti CLI in a clean or ephemeral environment, using TI_FS_TOKEN and TI_REGION_CODE without ti configure, TiDB Cloud API keys, a profile, or TI_FS_FILE_SYSTEM_ID. Use when an agent needs to mount, access, or persist a Drive9-backed workspace in a sandbox, CI job, container, or local machine.
---

# 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

```bash
: "${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`

```bash
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

```bash
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.

```bash
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

```bash
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

```bash
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.

```bash
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

```bash
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`.