docs: add TiDB Cloud CLI (ti) Preview documentation - #23306
Conversation
|
Skipping CI for Draft Pull Request. |
ti-chi-bot
Bot
added
do-not-merge/work-in-progress
|
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 reorganizes AI documentation navigation and adds extensive documentation for the Preview ChangesAI navigation and CLI naming
CLI foundations and database workflows
Filesystem workflows
Specialized references and scenarios
Priority: ⬇️ Low Estimated code review effort: 3 (Moderate) | ~25 minutes Change: Other Merge Risk: 🟠 High · up to Following the new documentation can expose powerful credentials, give read-only workers destructive access, or produce unreliable deletion and durability results. These issues should be corrected before merge. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 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
| > **Note:** | ||
| > | ||
| > tdc is currently in Preview. Its features and command-line interface might change without prior notice. | ||
|
|
There was a problem hiding this comment.
Before "What you can do with td", users also need to know "When to use tdc"
- In what scenarios should users choose tdc instead of ticloud/Console?
- What can tdc do that ticloud cannot?
| ## When to use tdc | |
| Use tdc when you need to: | |
| - **Manage TiDB Cloud Filesystem**: create Filesystem resources, access files, use Git workspaces, journals, or vault — these capabilities are only available through tdc. | |
| - **Automate with AI agents**: tdc commands are non-interactive (except `tdc configure`), return structured JSON by default, and support JMESPath queries, making them suitable for agent-generated command sequences. | |
| - **Use explicit SQL role permissions**: tdc creates read-only, read-write, and admin SQL users with separate connection strings, so you can grant agents the minimum required access. | |
|
@coderabbitai please do a full review of this PR. |
|
✅ Action performedFull review finished. |
There was a problem hiding this comment.
Actionable comments posted: 31
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Advanced
Run ID: 6f54e229-def1-4050-bb5f-417b265c0f4c
📒 Files selected for processing (119)
TOC-ai.mdTOC-tidb-cloud-essential.mdTOC-tidb-cloud-starter.mdai/_index.mdai/examples/basic-with-pytidb.mdai/guides/tables.mdai/ti/guides/configure-filesystem-ai-providers.mdai/ti/guides/manage-filesystem-layers.mdai/ti/guides/manage-filesystem-resources.mdai/ti/guides/manage-filesystem-tokens.mdai/ti/guides/manage-filesystem-vault-secrets.mdai/ti/guides/manage-git-workspaces.mdai/ti/guides/manage-starter-instances.mdai/ti/guides/mount-filesystem.mdai/ti/guides/use-filesystem-journals.mdai/ti/guides/work-with-filesystem-data.mdai/ti/reference/commands/db/ti-db-create-db-cluster-branch.mdai/ti/reference/commands/db/ti-db-create-db-cluster.mdai/ti/reference/commands/db/ti-db-create-db-sql-users.mdai/ti/reference/commands/db/ti-db-delete-db-cluster-branch.mdai/ti/reference/commands/db/ti-db-delete-db-cluster.mdai/ti/reference/commands/db/ti-db-describe-db-cluster-branch.mdai/ti/reference/commands/db/ti-db-describe-db-cluster.mdai/ti/reference/commands/db/ti-db-execute-sql-statement.mdai/ti/reference/commands/db/ti-db-format-db-connection-string.mdai/ti/reference/commands/db/ti-db-list-db-cluster-branches.mdai/ti/reference/commands/db/ti-db-list-db-clusters.mdai/ti/reference/commands/db/ti-db-update-db-cluster.mdai/ti/reference/commands/fs-git/ti-fs-git-add-git-worktree.mdai/ti/reference/commands/fs-git/ti-fs-git-clone-git-workspace.mdai/ti/reference/commands/fs-git/ti-fs-git-hydrate-git-workspace.mdai/ti/reference/commands/fs-git/ti-fs-git-remove-git-worktree.mdai/ti/reference/commands/fs-journal/ti-fs-journal-append-journal-entries.mdai/ti/reference/commands/fs-journal/ti-fs-journal-create-journal.mdai/ti/reference/commands/fs-journal/ti-fs-journal-read-journal-entries.mdai/ti/reference/commands/fs-journal/ti-fs-journal-search-journal-entries.mdai/ti/reference/commands/fs-journal/ti-fs-journal-verify-journal.mdai/ti/reference/commands/fs-vault/ti-fs-vault-create-grant.mdai/ti/reference/commands/fs-vault/ti-fs-vault-create-secret.mdai/ti/reference/commands/fs-vault/ti-fs-vault-delete-grant.mdai/ti/reference/commands/fs-vault/ti-fs-vault-delete-secret.mdai/ti/reference/commands/fs-vault/ti-fs-vault-list-audit-events.mdai/ti/reference/commands/fs-vault/ti-fs-vault-list-secrets.mdai/ti/reference/commands/fs-vault/ti-fs-vault-mount-vault.mdai/ti/reference/commands/fs-vault/ti-fs-vault-read-secret.mdai/ti/reference/commands/fs-vault/ti-fs-vault-replace-secret.mdai/ti/reference/commands/fs-vault/ti-fs-vault-run-with-secret.mdai/ti/reference/commands/fs-vault/ti-fs-vault-unmount-vault.mdai/ti/reference/commands/fs/ti-fs-check-file-system.mdai/ti/reference/commands/fs/ti-fs-chmod-file.mdai/ti/reference/commands/fs/ti-fs-commit-layer.mdai/ti/reference/commands/fs/ti-fs-copy-file.mdai/ti/reference/commands/fs/ti-fs-create-directory.mdai/ti/reference/commands/fs/ti-fs-create-file-system.mdai/ti/reference/commands/fs/ti-fs-create-hardlink.mdai/ti/reference/commands/fs/ti-fs-create-layer-checkpoint.mdai/ti/reference/commands/fs/ti-fs-create-layer.mdai/ti/reference/commands/fs/ti-fs-create-symlink.mdai/ti/reference/commands/fs/ti-fs-delete-file-system-token.mdai/ti/reference/commands/fs/ti-fs-delete-file-system.mdai/ti/reference/commands/fs/ti-fs-delete-file.mdai/ti/reference/commands/fs/ti-fs-delete-layer.mdai/ti/reference/commands/fs/ti-fs-describe-file-system-embedding-configuration.mdai/ti/reference/commands/fs/ti-fs-describe-file-system-extract-configuration.mdai/ti/reference/commands/fs/ti-fs-describe-file-system.mdai/ti/reference/commands/fs/ti-fs-describe-file.mdai/ti/reference/commands/fs/ti-fs-describe-layer.mdai/ti/reference/commands/fs/ti-fs-diff-layer.mdai/ti/reference/commands/fs/ti-fs-disable-file-system-token.mdai/ti/reference/commands/fs/ti-fs-drain-file-system.mdai/ti/reference/commands/fs/ti-fs-enable-file-system-token.mdai/ti/reference/commands/fs/ti-fs-find-files.mdai/ti/reference/commands/fs/ti-fs-fork-layer.mdai/ti/reference/commands/fs/ti-fs-generate-file-system-scoped-token.mdai/ti/reference/commands/fs/ti-fs-generate-file-system-token.mdai/ti/reference/commands/fs/ti-fs-import-file-system-token.mdai/ti/reference/commands/fs/ti-fs-list-file-system-tokens.mdai/ti/reference/commands/fs/ti-fs-list-file-systems.mdai/ti/reference/commands/fs/ti-fs-list-files.mdai/ti/reference/commands/fs/ti-fs-list-layer-chain.mdai/ti/reference/commands/fs/ti-fs-list-layers.mdai/ti/reference/commands/fs/ti-fs-mount-file-system.mdai/ti/reference/commands/fs/ti-fs-move-file.mdai/ti/reference/commands/fs/ti-fs-pack-file-system.mdai/ti/reference/commands/fs/ti-fs-read-file.mdai/ti/reference/commands/fs/ti-fs-refresh-file-system-token.mdai/ti/reference/commands/fs/ti-fs-rollback-layer.mdai/ti/reference/commands/fs/ti-fs-search-file-content.mdai/ti/reference/commands/fs/ti-fs-unmount-file-system.mdai/ti/reference/commands/fs/ti-fs-unpack-file-system.mdai/ti/reference/commands/fs/ti-fs-update-file-system-embedding-configuration.mdai/ti/reference/commands/fs/ti-fs-update-file-system-extract-configuration.mdai/ti/reference/commands/ti/ti-configure.mdai/ti/reference/commands/ti/ti-update.mdai/ti/reference/ti-agent-sandbox-example.mdai/ti/reference/ti-ci-artifact-handoff-example.mdai/ti/reference/ti-cli-reference.mdai/ti/reference/ti-configuration-and-credentials.mdai/ti/reference/ti-daily-workflow-example.mdai/ti/reference/ti-filesystem-git.mdai/ti/reference/ti-filesystem-journal.mdai/ti/reference/ti-filesystem-vault.mdai/ti/reference/ti-filesystem.mdai/ti/reference/ti-git-workspace-for-agents-example.mdai/ti/reference/ti-install-configure-update.mdai/ti/reference/ti-journal-agent-workflow-example.mdai/ti/reference/ti-migrate-from-tdc.mdai/ti/reference/ti-parallel-agent-dataset-example.mdai/ti/reference/ti-persistent-agent-state-example.mdai/ti/reference/ti-query-sql-with-roles-example.mdai/ti/reference/ti-regions-security-and-limitations.mdai/ti/reference/ti-share-filesystem-across-machines-example.mdai/ti/reference/ti-starter-database.mdai/ti/reference/ti-troubleshooting.mdai/ti/reference/ti-vault-agent-secrets-example.mdai/ti/ti-overview.mdai/ti/ti-quick-start.mdtidb-cloud/cli-reference.mdtidb-cloud/get-started-with-cli.md
💤 Files with no reviewable changes (1)
- ai/examples/basic-with-pytidb.md
Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.
| --- | ||
| title: Working with Tables | ||
| summary: Learn how to work with tables in TiDB. | ||
| aliases: ['/ai/basic-with-pytidb/'] |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
set -eu
printf '%s\n' '--- diff ---'
git diff -- ai/guides/tables.md ai/examples/basic-with-pytidb.md
printf '%s\n' '--- current guide ---'
cat -n ai/guides/tables.md | sed -n '1,20p'
printf '%s\n' '--- historical file in HEAD ---'
if git cat-file -e HEAD:ai/examples/basic-with-pytidb.md 2>/dev/null; then
git show HEAD:ai/examples/basic-with-pytidb.md | sed -n '1,35p'
else
printf '%s\n' 'not present in HEAD'
fi
printf '%s\n' '--- repository URL/permalink configuration references ---'
rg -n --glob '*.yml' --glob '*.yaml' --glob '*.json' --glob '*.js' --glob '*.ts' --glob '*.md' 'permalink|pretty|base_url|url:' ai .github 2>/dev/null | head -120Repository: pingcap/docs
Length of output: 1706
🏁 Script executed:
set -eu
commit="$(git log -1 --format='%H' --all -- ai/examples/basic-with-pytidb.md || true)"
printf 'last-touch=%s\n' "$commit"
if [ -n "$commit" ]; then
printf '%s\n' '--- file at last-touch commit ---'
git show "$commit:ai/examples/basic-with-pytidb.md" | sed -n '1,35p' || true
printf '%s\n' '--- file at parent of last-touch commit ---'
git show "$commit^:ai/examples/basic-with-pytidb.md" | sed -n '1,35p' || true
fiRepository: pingcap/docs
Length of output: 1452
🏁 Script executed:
set -eu
printf '%s\n' '--- likely documentation configuration files ---'
git ls-files | rg '(^|/)(config|hugo|mkdocs|docusaurus|book|site)([^/]*)(/|$)|\.(toml|ini)$' | head -120
printf '%s\n' '--- URL and alias configuration ---'
rg -n --hidden --glob '!node_modules/**' --glob '!dist/**' --glob '!build/**' 'aliases:|permalinks|uglyURLs|prettyURLs|baseURL|url:' . | head -160
printf '%s\n' '--- alias declarations near related pages ---'
rg -n -B3 -A3 '^aliases:' ai | head -160Repository: pingcap/docs
Length of output: 47219
🤖 get_repo_knowledge executed:
get_repo_knowledge pingcap/docs /tmp/coderabbit-repo-knowledge/pingcap-docs-9c73f70c/conventions
Length of output: 3147
🏁 Script executed:
set -eu
printf '%s\n' '--- root files ---'
git ls-files | sed -n '1,120p'
printf '%s\n' '--- documentation generator references ---'
rg -n --hidden --glob '!node_modules/**' --glob '!dist/**' --glob '!build/**' 'Hugo|hugo|Docsy|docsy|mkdocs|Docusaurus|docusaurus|permalink|aliases' README* .github scripts resources 2>/dev/null | head -180Repository: pingcap/docs
Length of output: 4757
🏁 Script executed:
set -eu
printf '%s\n' '--- AI section metadata ---'
cat -n ai/_index.md | sed -n '1,80p'
printf '%s\n' '--- AI navigation references ---'
rg -n -A2 -B2 'ai/(examples|guides)/|examples|guides' TOC-ai.md README.md _docHome.md ai/_index.md | head -180
printf '%s\n' '--- route-shaped links ---'
rg -n --glob '*.md' '/ai/(examples|guides)/' . | head -160Repository: pingcap/docs
Length of output: 26138
Preserve the deleted example URL.
The deleted ai/examples/basic-with-pytidb.md page has no explicit permalink, so /ai/examples/basic-with-pytidb/ can miss the current alias. Add the deleted route.
Suggested change
| aliases: ['/ai/basic-with-pytidb/'] | |
| aliases: ['/ai/basic-with-pytidb/', '/ai/examples/basic-with-pytidb/'] |
Source: Path instructions
[LGTM Timeline notifier]Timeline:
|
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: qiancai The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
|
@qiancai: You cannot manually add or delete the cherry pick approval state labels, only I and the tursted members have permission to do so. You can approve it in internal platform. DetailsIn response to removing label named approved. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the ti-community-infra/tichi repository. |
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-fsSummary by CodeRabbit
ti) guidance, including installation, configuration, Starter instances, Filesystem management, Git workspaces, journals, Vault secrets, troubleshooting, migration, and command references.tiversus the legacyticloudCLI.