docs: add TiDB Cloud CLI (ti) 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 | ✅ 3 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (3 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
| 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. |
| 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
…ote-fs-wait-backend
…remote-fs-wait-backend
Icemap
changed the title
|
|
3 participants
What is changed, added or deleted? (Required)
This PR adds Preview documentation for the TiDB Cloud Command Line Interface (
ti) to the AI documentation:--wait, asynchronous Filesystem deletion, explicit Filesystem selection, and Starter-only database guardrails.~/.ti/.preferencesfile, anonymous telemetry privacy boundaries and controls, and theti updatelocal-state isolation boundary.tdctoti, including~/.tdcto~/.tistate migration, active-mount handling, conflict protection, canonical environment variables, and the temporary legacy-variable compatibility window.tdcname toti.timanages Starter and Filesystem workflows and does not replaceticloudfor TiDB Cloud Essential.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
tiand 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 --checkmake testmake e2emake live-e2e-fs