Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

TiDB Cloud CLI New #17056

Merged
merged 22 commits into from
Apr 16, 2024
Merged

TiDB Cloud CLI New #17056

Show file tree
Hide file tree
Changes from 16 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
72b80dc
new cli
shiyuhang0 Apr 9, 2024
d628425
remobe br
shiyuhang0 Apr 10, 2024
51709cc
Apply suggestions from code review
qiancai Apr 11, 2024
3b2b3f8
refine descriptions
qiancai Apr 11, 2024
3ea5f47
update wording and format
qiancai Apr 11, 2024
0a409b2
fix typo
qiancai Apr 11, 2024
e24ad6e
fix accoridng to the review
shiyuhang0 Apr 12, 2024
1eafa2c
refine the new changes
qiancai Apr 12, 2024
0cfac7d
add import
shiyuhang0 Apr 15, 2024
3f25438
use force in export download
shiyuhang0 Apr 15, 2024
80e3104
update get started
shiyuhang0 Apr 15, 2024
fd514e3
polish
shiyuhang0 Apr 15, 2024
72d72b3
Apply suggestions from code review
qiancai Apr 15, 2024
5609a97
Update get-started-with-cli.md
qiancai Apr 15, 2024
939ae3f
polish according to the review
shiyuhang0 Apr 15, 2024
c1bfe25
add alias for serverless
shiyuhang0 Apr 15, 2024
64c5af7
fix dead link
shiyuhang0 Apr 15, 2024
55a492c
Apply suggestions from code review
qiancai Apr 15, 2024
26a1ee9
Indicate CLI is in beta
qiancai Apr 16, 2024
dfc49ae
fix building errors
qiancai Apr 16, 2024
d04925d
regions -> region
qiancai Apr 16, 2024
8e8f4dd
Update tidb-cloud/ticloud-serverless-export-download.md
qiancai Apr 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 28 additions & 17 deletions TOC-tidb-cloud.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -620,18 +620,37 @@
- [Spill to Disk](/tiflash/tiflash-spill-disk.md)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

preview: https://pingcap-docsite-preview-git-pr-qiancais-projects.vercel.app/tidbcloud/cli-reference

- CLI
- [Overview](/tidb-cloud/cli-reference.md)
- cluster
- auth
- [login](/tidb-cloud/ticloud-auth-login.md)
- [logout](/tidb-cloud/ticloud-auth-logout.md)
- serverless
- [create](/tidb-cloud/ticloud-cluster-create.md)
- [delete](/tidb-cloud/ticloud-cluster-delete.md)
- [describe](/tidb-cloud/ticloud-cluster-describe.md)
- [list](/tidb-cloud/ticloud-cluster-list.md)
- [connect-info](/tidb-cloud/ticloud-cluster-connect-info.md)
- branch
- [create](/tidb-cloud/ticloud-branch-create.md)
- [delete](/tidb-cloud/ticloud-branch-delete.md)
- [describe](/tidb-cloud/ticloud-branch-describe.md)
- [list](/tidb-cloud/ticloud-branch-list.md)
- [connect-info](/tidb-cloud/ticloud-branch-connect-info.md)
- [update](/tidb-cloud/ticloud-serverless-update.md)
- [spending-limit](/tidb-cloud/ticloud-serverless-spending-limit.md)
- [region](/tidb-cloud/ticloud-serverless-region.md)
- [shell](/tidb-cloud/ticloud-serverless-shell.md)
- branch
- [create](/tidb-cloud/ticloud-branch-create.md)
- [delete](/tidb-cloud/ticloud-branch-delete.md)
- [describe](/tidb-cloud/ticloud-branch-describe.md)
- [list](/tidb-cloud/ticloud-branch-list.md)
- [shell](/tidb-cloud/ticloud-branch-shell.md)
- import
- [cancel](/tidb-cloud/ticloud-import-cancel.md)
- [describe](/tidb-cloud/ticloud-import-describe.md)
- [list](/tidb-cloud/ticloud-import-list.md)
- [start](/tidb-cloud/ticloud-import-start.md)
- export
- [create](/tidb-cloud/ticloud-serverless-export-create.md)
- [describe](/tidb-cloud/ticloud-serverless-export-describe.md)
- [list](/tidb-cloud/ticloud-serverless-export-list.md)
- [cancel](/tidb-cloud/ticloud-serverless-export-cancel.md)
- [download](/tidb-cloud/ticloud-serverless-export-download.md)
- [ai](/tidb-cloud/ticloud-ai.md)
- [completion](/tidb-cloud/ticloud-completion.md)
- config
- [create](/tidb-cloud/ticloud-config-create.md)
- [delete](/tidb-cloud/ticloud-config-delete.md)
Expand All @@ -640,18 +659,10 @@
- [list](/tidb-cloud/ticloud-config-list.md)
- [set](/tidb-cloud/ticloud-config-set.md)
- [use](/tidb-cloud/ticloud-config-use.md)
- [connect](/tidb-cloud/ticloud-connect.md)
- import
- [cancel](/tidb-cloud/ticloud-import-cancel.md)
- [describe](/tidb-cloud/ticloud-import-describe.md)
- [list](/tidb-cloud/ticloud-import-list.md)
- start
- [local](/tidb-cloud/ticloud-import-start-local.md)
- [s3](/tidb-cloud/ticloud-import-start-s3.md)
- [mysql](/tidb-cloud/ticloud-import-start-mysql.md)
- project
- [list](/tidb-cloud/ticloud-project-list.md)
- [update](/tidb-cloud/ticloud-update.md)
- [help](/tidb-cloud/ticloud-help.md)
- [Table Filter](/table-filter.md)
- [Resource Control](/tidb-resource-control.md)
- [URI Formats of External Storage Services](/external-storage-uri.md)
Expand Down
41 changes: 24 additions & 17 deletions tidb-cloud/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,17 +17,19 @@ The following table lists the commands available for the TiDB Cloud CLI.

To use the `ticloud` CLI in your terminal, run `ticloud [command] [subcommand]`. If you are using [TiUP](https://docs.pingcap.com/tidb/stable/tiup-overview), use `tiup cloud [command] [subcommand]` instead.

| Command | Subcommand | Description |
|------------|------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| cluster | create, delete, describe, list, connect-info | Manage clusters |
| branch | create, delete, describe, list, connect-info | Manage branches |
| completion | bash, fish, powershell, zsh | Generate completion script for specified shell |
| config | create, delete, describe, edit, list, set, use | Configure user profiles |
| connect | - | Connect to a TiDB cluster |
| help | cluster, completion, config, help, import, project, update | View help for any command |
| import | cancel, describe, list, start | Manage [import](/tidb-cloud/tidb-cloud-migration-overview.md#import-data-from-files-to-tidb-cloud) tasks |
| project | list | Manage projects |
| update | - | Update the CLI to the latest version |
| Command | Subcommand | Description |
|-------------------|--------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| auth | login, logout | Login and logout |
| serverless (alias s) | create, delete, describe, list, update, spending-limit, regions, shell | Manage TiDB Serverless clusters |
qiancai marked this conversation as resolved.
Show resolved Hide resolved
| serverless branch | create, delete, describe, list, shell | Manage TiDB Serverless branches |
| serverless import | cancel, describe, list, start | Manage TiDB Serverless import tasks |
| serverless export | create, describe, list, cancel, download | Manage TiDB Serverless export tasks |
| ai | - | Chat with TiDB Bot |
| completion | bash, fish, powershell, zsh | Generate completion script for specified shell |
| config | create, delete, describe, edit, list, set, use | Configure user profiles |
| project | list | Manage projects |
| update | - | Update the CLI to the latest version |
| help | cluster, completion, config, help, import, project, update | View help for any command |

## Command modes

Expand All @@ -43,12 +45,16 @@ The TiDB Cloud CLI provides two modes for some commands for easy use:

## User profile

For the TiDB Cloud CLI, a user profile is a collection of properties associated with a user, including the profile name, public key, and private key. To use TiDB Cloud CLI, you must create a user profile first.
For the TiDB Cloud CLI, a user profile is a collection of properties associated with a user, including the profile name, public key, private key and OAuth token. To use TiDB Cloud CLI, you must have a user profile.
qiancai marked this conversation as resolved.
Show resolved Hide resolved

### Create a user profile
### Create a user profile with Open API key
qiancai marked this conversation as resolved.
Show resolved Hide resolved

Use [`ticloud config create`](/tidb-cloud/ticloud-config-create.md) to create a user profile.

### Create a user profile with OAuth token

Use [`ticloud auth login`](/tidb-cloud/ticloud-auth-login.md) to assign OAuth token to the current profile. If no profiles exist, a profile named `default` will be created automatically.

### List all user profiles

Use [`ticloud config list`](/tidb-cloud/ticloud-config-list.md) to list all user profiles.
Expand Down Expand Up @@ -103,10 +109,11 @@ Use [`ticloud config delete`](/tidb-cloud/ticloud-config-delete.md) to delete a

The following table lists the global flags for the TiDB Cloud CLI.

| Flag | Description | Required | Note |
|----------------------|-----------------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------|
| --no-color | Disables color in output. | No | Only works in non-interactive mode. In interactive mode, disabling color might not work with some UI components. |
| -P, --profile string | Specifies the active user profile used in this command. | No | Works in both non-interactive and interactive modes. |
| Flag | Description | Required | Note |
|----------------------|---------------------------------------------------------|----------|------------------------------------------------------------------------------------------------------------------|
| --no-color | Disables color in output. | No | Only works in non-interactive mode. In interactive mode, disabling color might not work with some UI components. |
shiyuhang0 marked this conversation as resolved.
Show resolved Hide resolved
| -P, --profile string | Specifies the active user profile used in this command. | No | Works in both non-interactive and interactive modes. |
| -D, --debug | Enable debug mode | No | Works in both non-interactive and interactive modes.:wq |
qiancai marked this conversation as resolved.
Show resolved Hide resolved

## Feedback

Expand Down
78 changes: 41 additions & 37 deletions tidb-cloud/get-started-with-cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@ summary: Learn how to manage TiDB Cloud resources through the TiDB Cloud CLI.
TiDB Cloud provides a command-line interface (CLI) [`ticloud`](https://github.com/tidbcloud/tidbcloud-cli) for you to interact with TiDB Cloud from your terminal with a few lines of commands. For example, you can easily perform the following operations using `ticloud`:

- Create, delete, and list your clusters.
- Import data from Amazon S3 or local files to your clusters.
- Import data to your clusters.
- Export data from your clusters.

## Before you begin

- Have a TiDB Cloud account. If you do not have one, [sign up for a free trial](https://tidbcloud.com/free-trial).
- [Create a TiDB Cloud API Key](https://docs.pingcap.com/tidbcloud/api/v1beta#section/Authentication/API-Key-Management).

## Installation

Expand Down Expand Up @@ -81,6 +81,44 @@ Install the MySQL command-line client if you do not have it. You can refer to th
</div>
</SimpleTab>

## Quick start

[TiDB Serverless](/tidb-cloud/select-cluster-tier.md#tidb-serverless) is the best way to get started with TiDB Cloud. In this section, you will learn how to create a TiDB Serverless cluster with TiDB Cloud CLI.

### Create a user profile or log into TiDB Cloud

Before creating a cluster with TiDB Cloud CLI, you need to either create a user profile or log into TiDB Cloud.

- Create a user profile with your [TiDB Cloud API key](https://docs.pingcap.com/tidbcloud/api/v1beta#section/Authentication/API-Key-Management):

```shell
ticloud config create
```

> **Warning:**
>
> The profile name **MUST NOT** contain `.`.

- Log into TiDB Cloud with authentication:

```shell
ticloud auth login
```

After successful login, an OAuth token will be assigned to the current profile. If no profiles exist, the token will be assigned to a profile named `default`.

> **Note:**
>
> In the preceding two methods, the TiDB Cloud API key takes precedence over the OAuth token. If both are available, the API key will be used.

### Create a TiDB Serverless cluster

To create a TiDB Serverless cluster, enter the following command, and then follow the CLI prompts to provide the required information:

```shell
ticloud serverless create
```

## Use the TiDB Cloud CLI

View all commands available:
Expand Down Expand Up @@ -114,7 +152,7 @@ tiup cloud --help
Run commands with `tiup cloud <command>`. For example:

```shell
tiup cloud cluster create
tiup cloud serverless create
```

Update to the latest version by TiUP:
Expand All @@ -123,40 +161,6 @@ Update to the latest version by TiUP:
tiup update cloud
```

## Quick start

[TiDB Serverless](/tidb-cloud/select-cluster-tier.md#tidb-serverless) is the best way to get started with TiDB Cloud. In this section, you will learn how to create a TiDB Serverless cluster with TiDB Cloud CLI.

### Create a user profile

Before creating a cluster, you need to create a user profile with your TiDB Cloud API Key:

```shell
ticloud config create
```

> **Warning:**
>
> The profile name **MUST NOT** contain `.`.

### Create a TiDB Serverless cluster

To create a TiDB Serverless cluster, enter the following command, and then follow the CLI prompts to provide the required information and set the password:

```shell
ticloud cluster create
```

### Connect to the cluster

After the cluster is created, you can connect to the cluster:

```shell
ticloud connect
```

When you are prompted about whether to use the default user, choose `Y` and enter the password that you set when creating the cluster.

## What's next

Check out [CLI reference](/tidb-cloud/cli-reference.md) to explore more features of TiDB Cloud CLI.
Expand Down
47 changes: 47 additions & 0 deletions tidb-cloud/ticloud-ai.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
title: ticloud ai
summary: The reference of `ticloud ai`.
---

# ticloud ai

Chat with TiDB Bot:

```shell
ticloud ai [flags]
```

## Examples

Chat with TiDB Bot in interactive mode:

```shell
ticloud serverless delete
```

Chat with TiDB Bot in non-interactive mode:

```shell
ticloud ai -q "How to create a cluster?"
```

## Flags

In non-interactive mode, you need to manually enter the required flags. In interactive mode, you can just follow CLI prompts to fill them in.

| Flag | Description | Required | Note |
|--------------------|-----------------------------------|----------|------------------------------------------------------|
| -q, --query string | Specifies your query to TiDB Bot. | Yes | Only works in non-interactive mode. |
| -h, --help | Shows help information for this command. | No | Works in both non-interactive and interactive modes. |

## Inherited flags

| Flag | Description | Required | Note |
|----------------------|--------------------------------------------------------------------------------------------|----------|------------------------------------------------------------------------------------------------------------------|
| --no-color | Disables color in output. | No | Only works in non-interactive mode. In interactive mode, disabling color might not work with some UI components. |
| -P, --profile string | Specifies the active [user profile](/tidb-cloud/cli-reference.md#user-profile) used in this command. | No | Works in both non-interactive and interactive modes. |
| -D, --debug | Enables debug mode. | No | Works in both non-interactive and interactive modes. |

## Feedback

If you have any questions or suggestions on the TiDB Cloud CLI, feel free to create an [issue](https://github.com/tidbcloud/tidbcloud-cli/issues/new/choose). Also, we welcome any contributions.
47 changes: 47 additions & 0 deletions tidb-cloud/ticloud-auth-login.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
title: ticloud auth login
summary: The reference of `ticloud auth login`.
---

# ticloud auth login

Authenticate with TiDB Cloud:

```shell
ticloud auth login [flags]
```

## Examples

To log into TiDB Cloud:

```shell
ticloud auth login
```

To log into TiDB Cloud with insecure storage:

```shell
ticloud auth login --insecure-storage
```

## Flags

In non-interactive mode, you need to manually enter the required flags. In interactive mode, you can just follow CLI prompts to fill them in.

| Flag | Description | Required | Note |
|--------------------|---------------------------------------------------------------------------|----------|------------------------------------------------------|
| --insecure-storage | Saves authentication credentials in plain text instead of credential store. | No | Works in both non-interactive and interactive modes. |
| -h, --help | Shows help information for this command. | No | Works in both non-interactive and interactive modes. |

## Inherited flags

| Flag | Description | Required | Note |
|----------------------|--------------------------------------------------------------------------------------------|----------|------------------------------------------------------------------------------------------------------------------|
| --no-color | Disables color in output. | No | Only works in non-interactive mode. In interactive mode, disabling color might not work with some UI components. |
| -P, --profile string | Specifies the active [user profile](/tidb-cloud/cli-reference.md#user-profile) used in this command. | No | Works in both non-interactive and interactive modes. |
| -D, --debug | Enables debug mode. | No | Works in both non-interactive and interactive modes. |

## Feedback

If you have any questions or suggestions on the TiDB Cloud CLI, feel free to create an [issue](https://github.com/tidbcloud/tidbcloud-cli/issues/new/choose). Also, we welcome any contributions.
Loading
Loading