TiDB Cloud Filesystem Vault CLI Command Reference

ti fs-vault stores structured secrets and delegates limited, expiring access to agents. Owner operations use the Filesystem owner credential; delegated reads use a vault token scoped to selected secrets or fields.

Command tree

ti fs-vault
├── create-secret
├── replace-secret
├── read-secret
├── list-secrets
├── delete-secret
├── create-grant
├── delete-grant
├── list-audit-events
├── run-with-secret
├── mount-vault
└── unmount-vault

Prerequisites

Select a Filesystem through a profile or the config-free FS environment variables. Never print, log, or commit owner or delegated tokens.

Create and replace secrets

Create a secret with repeatable fields:

ti fs-vault create-secret \
  --secret-name db-prod \
  --field DB_URL=mysql://example \
  --field PASSWORD=@./password.txt

key=value uses a literal value, key=@file reads a file, and key=- reads the value from stdin.

Replace all fields with files from a directory:

ti fs-vault replace-secret \
  --secret-path /n/vault/db-prod \
  --from-directory ./secret-fields

Read, list, and delete

ti fs-vault list-secrets
ti fs-vault read-secret --secret-name db-prod
ti fs-vault read-secret --secret-name db-prod --field DB_URL --format raw
ti fs-vault read-secret --secret-name db-prod --field DB_URL --format env

Delete an owner-visible secret:

ti fs-vault delete-secret --secret-name db-prod

Raw and environment output contains plaintext. Direct it only to the intended process.

Delegate limited access

Create a short-lived read grant and capture its token:

export TI_VAULT_TOKEN="$(ti fs-vault create-grant \
  --agent-id deploy-agent \
  --scope db-prod/DB_URL \
  --permission read \
  --ttl 10m \
  --token-only)"

Scopes are repeatable. --label-hint can add non-secret operator context.

Use the delegated token:

ti fs-vault read-secret \
  --secret-name db-prod \
  --field DB_URL \
  --format raw

TI_VAULT_TOKEN is preferred over --vault-token because command-line values can remain in process listings or shell history.

Inject a secret into a process

ti fs-vault run-with-secret \
  --secret-path /n/vault/db-prod \
  -- env

The child receives secret fields as environment variables. Avoid commands that print the complete environment in production; env is shown only to demonstrate the interface.

Audit and revoke

ti fs-vault list-audit-events \
  --secret-name db-prod \
  --agent-id deploy-agent \
  --since 24h \
  --limit 20

ti fs-vault delete-grant \
  --grant-id "<grant-id>" \
  --revoked-by operator \
  --reason rotated

Revocation prevents new authorized operations. It cannot erase secret values a process already read.

Mount a read-only vault

On macOS or Linux with FUSE support:

mkdir -p /path/to/vault
ti fs-vault mount-vault \
  --mount-path /path/to/vault \
  --vault-token "$TI_VAULT_TOKEN"

The mount is read-only. The command starts the runtime in the background, waits until it is ready, and then returns. --ready-timeout changes the readiness wait.

Unmount:

ti fs-vault unmount-vault --mount-path /path/to/vault

Unmount also supports --timeout, --force, and --ignore-absent. Vault mount is unavailable on Windows and requires FUSE support; direct read-secret and run-with-secret do not require a mount.

Security guidance

• Give an agent the narrowest field scope and shortest practical TTL.
• Prefer run-with-secret over writing plaintext to disk.
• Do not store delegated tokens in TiDB Cloud CLI configuration or operation logs.
• Stop processes using a vault mount before unmounting.
• Revoke a grant after the task finishes.

What's next

• Delegate Secrets to an Agent
• TiDB Cloud CLI Regions, Security, and Limitations