--- name: tidbcloud-cli description: Use this skill when users want to operate TiDB Cloud resources through the ticloud CLI. Covers the full CLI command surface, keeps resource operations interactive-first, and handles authentication via API key profiles or OAuth login. --- # TiDB Cloud CLI Skill This skill handles TiDB Cloud operations with the `ticloud` CLI. It covers the full documented CLI command surface, while keeping the trigger focus on real TiDB Cloud workflows such as authentication, profile management, project selection, and serverless resource operations. ## Source of Truth - Do not maintain a hand-written command catalog inside this skill. - The source of truth for supported commands is the upstream docs directory: `https://github.com/tidbcloud/tidbcloud-cli/tree/main/docs/generate_doc` - Use the generated local references in this skill as the default runtime source. - Only consult upstream GitHub docs when the needed reference is missing locally or the user explicitly asks for the latest upstream state. - Treat the GitHub docs as authoritative for command names, options, examples, and whether human output or `--force` is supported when a refresh or verification is needed. ## When to Use This Skill Use this skill when the user wants the agent to operate TiDB Cloud resources or supporting CLI workflows, including: - Authentication: `auth login`, `auth logout`, `auth whoami` - Profile and project setup: `config *`, `project list` - Serverless resource families: cluster, branch, export, import, migration, backup, restore, changefeed, SQL user, private link, audit log, authorized network, and related workflows - Supporting CLI utilities: `completion`, `upgrade`, and `ai` Typical trigger phrases: - "operate TiDB Cloud resources" - "manage cluster, branch, export, import, migration, or sql-user" - "use ticloud to create a cluster" - "delete a TiDB Cloud branch" - "log in to TiDB Cloud CLI" - "switch ticloud profile" - "list TiDB Cloud projects" ## Operating Principles ### 1. Interactive-first for resource operations - For resource operations, always prefer the CLI's interactive workflow. - Start from the bare interactive command whenever the command supports it. - Let the CLI prompt for project, cluster, branch, export, import, migration, or user selection instead of assembling a fully non-interactive command. - If the user provides IDs or names up front, still prefer the interactive command unless there is a strong reason not to. - Use non-interactive mode only when the command itself does not support interactive use, the user explicitly needs automation, or a follow-up step requires structured flags. ### 2. Human-friendly output when non-interactive is unavoidable - If a non-interactive command is truly required, keep the output easy for a human to inspect. - Prefer built-in human-readable output such as `-o human` where supported. - Only use JSON when the user explicitly asks for JSON or when a downstream step requires structured data. - After execution, summarize the key fields the user cares about: resource name, ID, status, region, timestamps, and next step. ### 2a. Cluster creation must confirm the target tier - When the user asks to create a cluster, determine whether they want `Starter` or `Essential`. - If the user did not specify the tier, ask exactly one targeted question: `Which cluster type do you want: Starter or Essential?` - Do not guess the tier silently, because the creation parameters differ materially. - After the tier is clear, proceed with creation using the matching workflow. Creation rules: - `Starter` - Interactive: `ticloud serverless create`, then select `Starter` in the CLI prompt. - Non-interactive shape: use `--display-name` and `--region`. - Optional Starter-specific setting: `--spending-limit-monthly`. - Do not pass `--min-rcu` or `--max-rcu` for Starter. - `Essential` - Interactive: `ticloud serverless create`, then select `Essential` in the CLI prompt. - Non-interactive shape: use `--display-name`, `--region`, `--min-rcu`, and `--max-rcu`. - Default Essential capacity in the CLI interactive flow is `min=2000`, `max=4000`. - Optional Essential-specific setting: `--encryption`. - Explain the chosen tier back to the user before or after creation so the result is audit-friendly. ### 3. Explicit confirmation for dangerous operations - Treat destructive or disruptive commands as dangerous. - Always require explicit user confirmation before running them, even if the CLI itself will prompt later. - Never use `--force` unless the user explicitly asks for force behavior. Dangerous operations include at least: - Common examples: `delete`, `cancel`, `reset`, `disable`, and other irreversible or disruptive actions - Any command whose upstream doc exposes `--force` ### 4. Authentication and permissions - TiDB Cloud CLI supports two valid auth paths: - API key profile: `ticloud config create` - OAuth login: `ticloud auth login` - If both an API key and an OAuth token are present in the current profile, the API key takes precedence. - If no profile exists and `ticloud auth login` succeeds, the OAuth token is assigned to a profile named `default`. - When creating a profile, remember that the profile name must not contain `.`. - Use `ticloud auth whoami` to check identity when OAuth is in use, but do not rely on it as the only health check for all auth states. - If the active profile uses an API key, resource commands may still work even when `ticloud auth whoami` is not useful or returns an auth error. ## Installation and Setup Follow the repository README and prioritize the install script. ### Preferred installation method ```bash curl https://raw.githubusercontent.com/tidbcloud/tidbcloud-cli/main/install.sh | sh ``` ### Alternative installation method ```bash tiup install cloud ``` ### Ignore for this skill - Ignore the GitHub Action installation path. - Do not guide users toward GitHub Action setup when the goal is to operate resources from the agent session. ### Post-install checks ```bash ticloud --help ticloud config create ticloud auth login ticloud auth whoami ``` ## Recommended Workflow ### 1. Check that the CLI is ready Run these before resource operations when setup is uncertain: ```bash ticloud --help ticloud config list ticloud auth whoami ``` If the user wants API key auth, run: ```bash ticloud config create ``` If the user wants OAuth auth, run: ```bash ticloud auth login ``` If the profile needs to be switched first, run: ```bash ticloud config use ``` ### 2. Use the interactive command first Prefer commands like these in interactive mode: ```bash ticloud auth login ticloud config create ticloud config use ticloud project list ticloud serverless list ticloud serverless create ticloud serverless region ticloud serverless describe ticloud serverless update ticloud serverless delete ticloud serverless branch list ticloud serverless branch create ticloud serverless branch describe ticloud serverless branch reset ticloud serverless branch shell ticloud serverless branch delete ticloud serverless export list ticloud serverless export create ticloud serverless export describe ticloud serverless export download ticloud serverless export cancel ticloud serverless import list ticloud serverless import start ticloud serverless import describe ticloud serverless import cancel ticloud serverless migration list ticloud serverless migration create ticloud serverless migration describe ticloud serverless migration pause ticloud serverless migration resume ticloud serverless changefeed list ticloud serverless changefeed create ticloud serverless changefeed edit ticloud serverless changefeed pause ticloud serverless changefeed resume ticloud serverless sql-user list ticloud serverless sql-user create ticloud serverless sql-user update ticloud serverless sql-user delete ``` ### 3. Present the result in a concise operator-friendly format For every completed action, report: - What command family was used - What resource was selected or affected - The resulting status - Important identifiers the user may need next - A practical next command when relevant ## Confirmation Template for Dangerous Actions Before executing a dangerous action, use this exact structure: ```text CAUTION: Dangerous operation confirmation Action: Target: Impact: Reply with "yes" to continue. ``` If the user does not explicitly confirm, stop and do not execute the command. ## Command Coverage Reference Use the generated references in this skill as the primary lookup source. - Source of truth: `https://github.com/tidbcloud/tidbcloud-cli/tree/main/docs/generate_doc` - Start with `references/README.md` - Use `references/command-index.md` for the full command tree - Use `references/generated/commands/` and `references/generated/families/` for detailed pages - Regenerate references with `scripts/generate_references.py` when you intentionally refresh from upstream - Prefer cached or local-doc refresh paths over repeated anonymous GitHub fetches - If you need to inspect a command directly, infer the upstream doc filename from the command name, for example: - `ticloud serverless export cancel` -> `ticloud_serverless_export_cancel.md` - `ticloud auth login` -> `ticloud_auth_login.md` ## Cluster Creation Notes Use these facts when handling cluster creation requests: - The upstream `ticloud serverless create` doc exposes generic flags such as `--display-name`, `--region`, `--spending-limit-monthly`, `--min-rcu`, and `--max-rcu`. - The CLI implementation shows an explicit tier selection in interactive mode: `Starter` or `Essential`. - The CLI implementation also shows the practical non-interactive distinction: - Starter creation uses spending limit style options and no capacity flags. - Essential creation is represented by autoscaling capacity via `--min-rcu` and `--max-rcu`. - If the user says `Essential`, it is valid to create with `--min-rcu 2000 --max-rcu 4000` unless they asked for different capacity. - If the user says `Starter`, create without `--min-rcu` and `--max-rcu`. ## Error Handling Guidance When a command fails: 1. Explain the failure in plain English. 2. State whether it is an auth issue, selection issue, or resource-side issue. 3. Provide the next corrective command. 4. If auth-related, distinguish the failure mode: - No profile configured: recommend `ticloud config create` or `ticloud auth login` - Expired or missing OAuth session: recommend `ticloud auth login` - Wrong active profile: recommend `ticloud config list` and `ticloud config use` - Permission denied or forbidden on a valid identity: explain that authentication succeeded but the current account or API key lacks resource access 5. Do not blindly treat every `401` or `403` as an OAuth problem; check whether the user may be using API key auth via a profile. 6. If one auth check fails but another resource command succeeds, prefer the working evidence and explain the inconsistency clearly. 7. If selection is unclear, return to the interactive list or describe workflow. ## Permission Recovery Playbook Use this sequence when permission or auth behavior is unclear: 1. Check available profiles with `ticloud config list`. 2. If needed, switch profiles with `ticloud config use`. 3. If the user wants API key auth, create or refresh the profile with `ticloud config create`. 4. If the user wants OAuth auth, run `ticloud auth login`. 5. Re-run the smallest safe read command first, such as `ticloud project list` or `ticloud serverless list`. 6. Only after read access is confirmed, proceed to mutating operations.