docs: add TiDB Cloud CLI (tdc) Preview documentation#23306
Conversation
|
Skipping CI for Draft Pull Request. |
ti-chi-bot
Bot
added
the
do-not-merge/work-in-progress
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
ti-chi-bot
Bot
added
missing-translation-status
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe PR adds Preview TiDB Cloud CLI documentation covering navigation, concepts, installation, configuration, Starter databases, Filesystem operations, references, troubleshooting, and agent-oriented examples. ChangesTiDB Cloud CLI documentation
Estimated code review effort: 3 (Moderate) | ~25 minutes Suggested labels: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
ti-chi-bot
Bot
removed
the
do-not-merge/work-in-progress
Icemap
added
translation/done
|
|
Icemap
added
translation/no-need
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 4d883b3f-66fa-4bed-96ac-947087cee7c2
📒 Files selected for processing (23)
TOC-ai.mdai/_index.mdai/tdc/concepts/tdc-concepts-and-architecture.mdai/tdc/examples/tdc-agent-sandbox-example.mdai/tdc/examples/tdc-daily-workflow-example.mdai/tdc/examples/tdc-git-workspace-for-agents-example.mdai/tdc/examples/tdc-journal-agent-workflow-example.mdai/tdc/examples/tdc-query-sql-with-roles-example.mdai/tdc/examples/tdc-share-filesystem-across-machines-example.mdai/tdc/examples/tdc-vault-agent-secrets-example.mdai/tdc/guides/tdc-filesystem-git.mdai/tdc/guides/tdc-filesystem-journal.mdai/tdc/guides/tdc-filesystem-vault.mdai/tdc/guides/tdc-filesystem.mdai/tdc/guides/tdc-install-configure-update.mdai/tdc/guides/tdc-organization.mdai/tdc/guides/tdc-starter-database.mdai/tdc/reference/tdc-cli-reference.mdai/tdc/reference/tdc-configuration-and-credentials.mdai/tdc/reference/tdc-regions-security-and-limitations.mdai/tdc/reference/tdc-troubleshooting.mdai/tdc/tdc-overview.mdai/tdc/tdc-quick-start.md
|
|
||
| Coding agents often start in clean, short-lived sandboxes. The local disk disappears when the sandbox is replaced, but the agent still needs previous artifacts, repository state, and files produced by other workers. Rebuilding that state wastes task time, while copying `~/.tdc/` or injecting TiDB Cloud API keys gives the sandbox control-plane credentials it does not need. | ||
|
|
||
| ## Why local storage and full cloud credentials are not enough |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Replace vague quantifiers flagged by Vale.
These replacements make the documentation more precise without changing its technical meaning.
ai/tdc/examples/tdc-agent-sandbox-example.md#L18-L18: replace the heading with “Why local storage and full cloud credentials do not solve the full problem”.ai/tdc/examples/tdc-agent-sandbox-example.md#L20-L20: replace “a much broader security boundary” with “a broader security boundary”.ai/tdc/examples/tdc-git-workspace-for-agents-example.md#L18-L18: replace the heading with “Why a normal clone or partial clone does not solve the startup problem”.ai/tdc/examples/tdc-git-workspace-for-agents-example.md#L20-L20: replace “many on-demand fetches” with “repeated on-demand fetches”.ai/tdc/examples/tdc-journal-agent-workflow-example.md#L18-L18: replace the heading with “Why appending to a normal file does not provide the required guarantees”.ai/tdc/examples/tdc-query-sql-with-roles-example.md#L18-L18: replace the heading with “Why one native database connection does not provide sufficient privilege isolation”.ai/tdc/examples/tdc-share-filesystem-across-machines-example.md#L18-L18: replace the heading with “Why native local disks and manual synchronization do not provide shared state”.ai/tdc/examples/tdc-vault-agent-secrets-example.md#L16-L16: replace “the lifetime that need it” with “the lifetime that require it”.ai/tdc/examples/tdc-vault-agent-secrets-example.md#L18-L18: replace the heading with “Why ordinary environment variables and files do not provide scoped delegation”.
As per path instructions, these Markdown wording fixes should be applied as exact committable replacements.
🧰 Tools
🪛 GitHub Check: vale
[warning] 18-18:
[vale] reported by reviewdog 🐶
[PingCAP.Ambiguous] Consider using a clearer word than 'enough' because it may cause confusion.
Raw Output:
{"message": "[PingCAP.Ambiguous] Consider using a clearer word than 'enough' because it may cause confusion.", "location": {"path": "ai/tdc/examples/tdc-agent-sandbox-example.md", "range": {"start": {"line": 18, "column": 57}}}, "severity": "INFO"}
📍 Affects 6 files
ai/tdc/examples/tdc-agent-sandbox-example.md#L18-L18(this comment)ai/tdc/examples/tdc-agent-sandbox-example.md#L20-L20ai/tdc/examples/tdc-git-workspace-for-agents-example.md#L18-L18ai/tdc/examples/tdc-git-workspace-for-agents-example.md#L20-L20ai/tdc/examples/tdc-journal-agent-workflow-example.md#L18-L18ai/tdc/examples/tdc-query-sql-with-roles-example.md#L18-L18ai/tdc/examples/tdc-share-filesystem-across-machines-example.md#L18-L18ai/tdc/examples/tdc-vault-agent-secrets-example.md#L16-L16ai/tdc/examples/tdc-vault-agent-secrets-example.md#L18-L18
Sources: Path instructions, Linters/SAST tools
| tdc fs create-file-system \ | ||
| --file-system-name daily-workspace \ | ||
| --set-default | ||
|
|
||
| printf 'daily workflow\n' | tdc fs copy-file \ | ||
| --from-stdin \ | ||
| --to-remote /notes/today.txt |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Wait for Filesystem creation before using it.
The create operation is asynchronous unless --wait is supplied, but the next command immediately writes to the new Filesystem. Add the readiness barrier to prevent a provisioning race.
Committable replacement
| tdc fs create-file-system \ | |
| --file-system-name daily-workspace \ | |
| --set-default | |
| printf 'daily workflow\n' | tdc fs copy-file \ | |
| --from-stdin \ | |
| --to-remote /notes/today.txt | |
| tdc fs create-file-system \ | |
| --file-system-name daily-workspace \ | |
| --set-default \ | |
| --wait |
As per path instructions, this Markdown fix is provided as an exact committable replacement.
Source: Path instructions
| cat /path/to/shared-workspace/shared/origin.txt | ||
| printf 'written through mount\n' > /path/to/shared-workspace/shared/mounted.txt | ||
| tdc fs read-file --path /shared/mounted.txt |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Drain before claiming cross-interface visibility.
The mount write may still be pending when tdc fs read-file runs, so this verification can race the FUSE flush. Drain the mount before reading through the data plane.
Committable replacement
| cat /path/to/shared-workspace/shared/origin.txt | |
| printf 'written through mount\n' > /path/to/shared-workspace/shared/mounted.txt | |
| tdc fs read-file --path /shared/mounted.txt | |
| cat /path/to/shared-workspace/shared/origin.txt | |
| printf 'written through mount\n' > /path/to/shared-workspace/shared/mounted.txt | |
| tdc fs drain-file-system --mount-path /path/to/shared-workspace | |
| tdc fs read-file --path /shared/mounted.txt |
As per path instructions, this Markdown fix is provided as an exact committable replacement.
Source: Path instructions
| export TDC_VAULT_TOKEN="$(tdc fs-vault create-grant \ | ||
| --agent-id example-agent \ | ||
| --scope service-demo/ENDPOINT \ | ||
| --permission read \ | ||
| --ttl 10m \ | ||
| --label-hint example \ | ||
| --token-only)" | ||
| ``` | ||
|
|
||
| Record the returned grant ID from the structured create result in a real workflow. The token is captured and not printed. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '## tree\n'
git ls-files .ai/AI-README.md .ai/shared .ai/skills | sed -n '1,200p'
printf '\n## relevant files\n'
fd -a -t f 'AI-README.md|.*' .ai . 2>/dev/null | sed -n '1,200p'Repository: pingcap/docs
Length of output: 10488
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '## .ai/AI-README.md\n'
cat -n .ai/AI-README.md
printf '\n## .ai/shared files\n'
fd -a -t f . .ai/shared 2>/dev/null | sed -n '1,200p'
printf '\n## .ai/skills files\n'
fd -a -t f . .ai/skills 2>/dev/null | sed -n '1,200p'Repository: pingcap/docs
Length of output: 219
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '## .ai/AI-README.md\n'
sed -n '1,220p' .ai/AI-README.md
printf '\n## .ai/shared\n'
for f in .ai/shared/*.md; do
[ -f "$f" ] || continue
printf '\n### %s\n' "$f"
sed -n '1,220p' "$f"
done
printf '\n## .ai/skills matching review-doc-pr if present\n'
if [ -d .ai/skills/review-doc-pr ]; then
find .ai/skills/review-doc-pr -maxdepth 2 -type f | sort | while read -r f; do
printf '\n### %s\n' "$f"
sed -n '1,220p' "$f"
done
fiRepository: pingcap/docs
Length of output: 230
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '## target file excerpt\n'
cat -n ai/tdc/examples/tdc-vault-agent-secrets-example.md | sed -n '1,220p'
printf '\n## search for create-grant / delete-grant usage\n'
rg -n "create-grant|delete-grant|grant ID|token-only|structured create result|label-hint" ai/tdc -SRepository: pingcap/docs
Length of output: 5315
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '## required guidance\n'
sed -n '1,220p' .ai/AI-README.md
printf '\n## shared guidance files\n'
for f in .ai/shared/*.md; do
[ -f "$f" ] || continue
printf '\n### %s\n' "$f"
sed -n '1,220p' "$f"
done
printf '\n## review-doc-pr skill files\n'
if [ -d .ai/skills/review-doc-pr ]; then
find .ai/skills/review-doc-pr -maxdepth 2 -type f | sort | while read -r f; do
printf '\n### %s\n' "$f"
sed -n '1,220p' "$f"
done
fiRepository: pingcap/docs
Length of output: 231
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '## target file excerpt\n'
cat -n ai/tdc/examples/tdc-vault-agent-secrets-example.md | sed -n '1,220p'
printf '\n## related references\n'
rg -n "create-grant|delete-grant|grant ID|token-only|structured create result|label-hint" ai/tdc -SRepository: pingcap/docs
Length of output: 5289
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "README:"
sed -n '1,220p' .ai/AI-README.md
echo
echo "TARGET:"
cat -n ai/tdc/examples/tdc-vault-agent-secrets-example.md | sed -n '1,220p'
echo
echo "MATCHES:"
rg -n "create-grant|delete-grant|grant ID|token-only|structured create result|label-hint" ai/tdc -SRepository: pingcap/docs
Length of output: 218
🏁 Script executed:
#!/bin/bash
set -euo pipefail
cat -n ai/tdc/guides/tdc-filesystem-vault.md | sed -n '50,130p'Repository: pingcap/docs
Length of output: 2747
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
p = Path('ai/tdc/guides/tdc-filesystem-vault.md')
text = p.read_text()
for key in ['create-grant', 'delete-grant', '--token-only', '--format', 'grant-id', 'structured']:
print(f'## {key}')
for i, line in enumerate(text.splitlines(), 1):
if key in line:
print(f'{i}: {line}')
PYRepository: pingcap/docs
Length of output: 778
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
p = Path('ai/tdc/guides/tdc-filesystem-vault.md')
lines = p.read_text().splitlines()
for start in [1, 50, 90, 130]:
print(f'## lines {start}-{min(start+49, len(lines))}')
for i in range(start, min(start+50, len(lines)+1)):
print(f'{i:4d} {lines[i-1]}')
PYRepository: pingcap/docs
Length of output: 5692
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "## guide excerpt"
sed -n '55,115p' ai/tdc/guides/tdc-filesystem-vault.md
echo
echo "## create-grant / delete-grant context"
rg -n -C 3 "create-grant|delete-grant|token-only|grant-id|format" ai/tdc/guides/tdc-filesystem-vault.mdRepository: pingcap/docs
Length of output: 2629
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
p = Path('ai/tdc/examples/tdc-vault-agent-secrets-example.md')
lines = p.read_text().splitlines()
# Print the exact surrounding context for the comment target.
for i in range(40, 86):
if 1 <= i <= len(lines):
print(f'{i:4d} {lines[i-1]}')
PYRepository: pingcap/docs
Length of output: 1429
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
p = Path('ai/tdc/examples/tdc-vault-agent-secrets-example.md')
text = p.read_text()
# Look for any statement that suggests grant ID is available with token-only.
for needle in [
'structured create result',
'returned grant ID',
'--token-only',
'--format',
'grant-id',
]:
print(f'== {needle} ==')
for i, line in enumerate(text.splitlines(), 1):
if needle in line:
print(f'{i}: {line}')
PYRepository: pingcap/docs
Length of output: 578
Preserve the grant ID for revocation. --token-only only returns the vault token, but Step 4 still needs <grant-id> for delete-grant. Show how to keep the grant ID in the flow, or split this into a separate non---token-only create-grant step.
Suggested replacement
| export TDC_VAULT_TOKEN="$(tdc fs-vault create-grant \ | |
| --agent-id example-agent \ | |
| --scope service-demo/ENDPOINT \ | |
| --permission read \ | |
| --ttl 10m \ | |
| --label-hint example \ | |
| --token-only)" | |
| ``` | |
| Record the returned grant ID from the structured create result in a real workflow. The token is captured and not printed. | |
| Record the returned grant ID from the create result in a real workflow. If you need to revoke the grant later, run `tdc fs-vault create-grant` without `--token-only` and save the returned grant ID before exporting the token. |
|
|
||
| ### Mount in Docker and Docker Compose | ||
|
|
||
| Installing FUSE3 inside an image is not sufficient by itself. The Docker host must provide `/dev/fuse`, and the container must receive permission to perform the mount. The following Dockerfile installs the required Ubuntu package and tdc without storing any cloud or Filesystem credentials in the image: |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use clearer wording than “sufficient”.
Replace the ambiguous sentence with the exact wording below.
| Installing FUSE3 inside an image is not sufficient by itself. The Docker host must provide `/dev/fuse`, and the container must receive permission to perform the mount. The following Dockerfile installs the required Ubuntu package and tdc without storing any cloud or Filesystem credentials in the image: | |
| Installing FUSE3 inside an image does not by itself enable mounting. |
🧰 Tools
🪛 GitHub Check: vale
[warning] 225-225:
[vale] reported by reviewdog 🐶
[PingCAP.Ambiguous] Consider using a clearer word than 'sufficient' because it may cause confusion.
Raw Output:
{"message": "[PingCAP.Ambiguous] Consider using a clearer word than 'sufficient' because it may cause confusion.", "location": {"path": "ai/tdc/guides/tdc-filesystem.md", "range": {"start": {"line": 225, "column": 41}}}, "severity": "INFO"}
Source: Linters/SAST tools
| ## Uninstall tdc | ||
|
|
||
| Remove only the binaries: | ||
|
|
||
| ```bash | ||
| rm -f "$HOME/.tdc/bin/tdc" "$HOME/.tdc/bin/tdc-drive9" | ||
| ``` | ||
|
|
||
| On Windows: | ||
|
|
||
| ```powershell | ||
| Remove-Item "$HOME\.tdc\bin\tdc.exe", "$HOME\.tdc\bin\tdc-drive9.exe" | ||
| ``` | ||
|
|
||
| Removing binaries preserves profiles, credentials, Filesystem registrations, DB SQL credentials, logs, and mount locators. Remove `~/.tdc/` only when you intend to delete all local tdc state: |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Require unmount before uninstalling the binaries.
The document explains that mounts can leave long-running companion processes and locator files, but the uninstall steps do not require stopping writers and unmounting first. Following this sequence can leave an active mount or stale locator without the CLI needed for graceful cleanup.
Suggested Markdown insertion
## Uninstall tdc
+Before removing the binaries, stop writers and unmount every active Filesystem or vault mount.
+
Remove only the binaries:As per path instructions, this is a safe contiguous Markdown insertion.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## Uninstall tdc | |
| Remove only the binaries: | |
| ```bash | |
| rm -f "$HOME/.tdc/bin/tdc" "$HOME/.tdc/bin/tdc-drive9" | |
| ``` | |
| On Windows: | |
| ```powershell | |
| Remove-Item "$HOME\.tdc\bin\tdc.exe", "$HOME\.tdc\bin\tdc-drive9.exe" | |
| ``` | |
| Removing binaries preserves profiles, credentials, Filesystem registrations, DB SQL credentials, logs, and mount locators. Remove `~/.tdc/` only when you intend to delete all local tdc state: | |
| ## Uninstall tdc | |
| Before removing the binaries, stop writers and unmount every active Filesystem or vault mount. | |
| Remove only the binaries: | |
Source: Path instructions
| ## Filesystem region is unsupported | ||
|
|
||
| The configured TiDB Cloud region might not have a `tidb_cloud_native` Filesystem endpoint. Compare it with [current Filesystem regions](/ai/tdc/reference/tdc-regions-security-and-limitations.md#filesystem-regions). Change placement with a valid profile or command-scoped `--region`; do not configure a raw server URL. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Clarify that --region is command-scoped.
The configuration contract says --region affects only the current command. “Change placement with … --region” can imply that it persists to the profile.
| ## Filesystem region is unsupported | |
| The configured TiDB Cloud region might not have a `tidb_cloud_native` Filesystem endpoint. Compare it with [current Filesystem regions](/ai/tdc/reference/tdc-regions-security-and-limitations.md#filesystem-regions). Change placement with a valid profile or command-scoped `--region`; do not configure a raw server URL. | |
| Use a profile configured for a supported region, or pass `--region` to override the region for this command only; do not configure a raw server URL. |
| Clean up: | ||
|
|
||
| ```bash | ||
| tdc fs delete-file-system \ | ||
| --file-system-name quickstart-fs | ||
| ``` |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Make asynchronous Filesystem cleanup explicit.
The PR documents Filesystem deletion as asynchronous, but this section ends immediately after submitting the delete request. Users can therefore assume the resource is gone while deletion is still pending.
Suggested Markdown insertion
tdc fs delete-file-system \
--file-system-name quickstart-fs+Filesystem deletion is asynchronous. Verify that the resource reaches its terminal deleted state before treating cleanup as complete.
</details>
As per path instructions, this is a safe contiguous Markdown insertion.
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
Clean up:
Source: Path instructions
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
ai/tdc/reference/tdc-cli-reference.md (1)
17-29: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winPut global flags after command-specific optional flags.
The syntax specifies required flags, then optional flags, then global flags, but this example places global
--outputbefore optional--view. Keep the example consistent with the documented ordering.tdc db describe-db-cluster --db-cluster-id <string> [--view <string>] [--output <string>]Source: Path instructions
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 23d03ff3-8115-45be-bdc2-7b773b107c5a
📒 Files selected for processing (1)
ai/tdc/reference/tdc-cli-reference.md
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
ai/tdc/reference/tdc-cli-reference.md (1)
127-131: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winMake the error example match the documented leading blank line.
The prose states that errors start with a blank line, but the example begins directly with
tdc [ERROR].As per path instructions, this Markdown fix is provided as a committable replacement.
Proposed replacement
```text + tdc [ERROR]: <message></details> <!-- cr-comment:v1:ab4f5392eeee50b178f6f080 --> _Source: Path instructions_ </blockquote></details> </blockquote></details>
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID:
e0107458-475e-4aa2-8ae6-703677039572📒 Files selected for processing (1)
ai/tdc/reference/tdc-cli-reference.md
1 participant
What is changed, added or deleted? (Required)
This PR adds Preview documentation for the TiDB Cloud CLI (
tdc) to the AI documentation:--waitand asynchronous Filesystem deletion behavior.tdcruns without a command.These changes provide task-oriented documentation that gets users and coding agents to a working database or Filesystem quickly while documenting the complete command surface and the boundary between tdc and its bundled Drive9 companion.
Which TiDB version(s) do your changes apply to? (Required)
What is the related PR or file link(s)?
AI agent involvement
Do your changes match any of the following descriptions?
Validation
git diff --checkSummary by CodeRabbit
New Features (Documentation)
tdc), including overview, quick start, concepts/architecture, and install/configure/update.tdc(Preview) sections across Concepts, Guides, Examples, and Reference.Documentation
tdcCLI reference, configuration/credentials, region/security/limitations, and troubleshooting materials.