# tidbcloud-cli

Operate TiDB Cloud through the `ticloud` CLI with a resource-focused, interactive-first workflow.

## What this skill covers

- Full documented CLI coverage from the upstream docs directory
- Authentication, config, project, and serverless command families
- Supporting utilities such as `ai`, `completion`, and `upgrade`

## Key behavior

- Supports both API key profiles and OAuth login
- API key takes precedence over OAuth token when both exist in the same profile
- Prefers interactive resource operations whenever the command supports them
- Asks the user to choose `Starter` or `Essential` before cluster creation when unspecified
- Keeps non-interactive output human-friendly when fallback is necessary
- Requires explicit confirmation for dangerous actions
- Prefers the install script from the TiDB Cloud CLI README
- Ignores GitHub Action setup for this workflow

## Authentication

- API key profile: `ticloud config create`
- OAuth login: `ticloud auth login`
- Check or switch profiles with `ticloud config list` and `ticloud config use`
- Profile names must not contain `.`
- If no profiles exist, a successful `ticloud auth login` writes the token to the `default` profile

## Permission handling

- Do not assume every auth failure means OAuth is broken
- A profile may still work through API key auth even if `ticloud auth whoami` is not the best signal
- On auth or permission failures, first check profiles, then decide between `config create`, `config use`, or `auth login`

## Install `ticloud`

Preferred:

```bash
curl https://raw.githubusercontent.com/tidbcloud/tidbcloud-cli/main/install.sh | sh
```

Alternative:

```bash
tiup install cloud
```

## Command references

- Source of truth: `https://github.com/tidbcloud/tidbcloud-cli/tree/main/docs/generate_doc`
- Generated references live under `references/` and should be the default source during normal skill execution
- Start with `references/README.md` and `references/command-index.md`
- Prefer local refreshes with `python3 scripts/generate_references.py --skill-dir /path/to/tidbcloud-cli-skill --docs-dir /path/to/tidbcloud-cli/docs/generate_doc`
- Remote refreshes are supported, but use GitHub caching automatically and work best with `GITHUB_TOKEN` set

Example mapping:

- `ticloud serverless list` -> `ticloud_serverless_list.md`
- `ticloud config use` -> `ticloud_config_use.md`

## Cluster creation

- Always clarify whether the user wants a `Starter` or `Essential` cluster if they did not specify it.
- `Starter` creation uses the basic create flow without `--min-rcu` and `--max-rcu`.
- `Essential` creation uses `--min-rcu` and `--max-rcu`; the CLI interactive defaults are `2000` and `4000`.