Skip to content

Commit

Permalink
TiDB Cloud CLI New (#17056)
Browse files Browse the repository at this point in the history
  • Loading branch information
@shiyuhang0
shiyuhang0 authored Apr 16, 2024
1 parent e56691f commit fae4309
Show file tree
Hide file tree
Showing 47 changed files with 1,198 additions and 699 deletions.
45 changes: 28 additions & 17 deletions TOC-tidb-cloud.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -623,18 +623,37 @@
- [Spill to Disk](/tiflash/tiflash-spill-disk.md)
- 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 @@ -643,18 +662,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
47 changes: 29 additions & 18 deletions tidb-cloud/cli-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,11 @@ title: TiDB Cloud CLI Reference
summary: Provides an overview of TiDB Cloud CLI.
---

# TiDB Cloud CLI Reference
# TiDB Cloud CLI Reference <span style="color: #fff; background-color: #00bfff; border-radius: 4px; font-size: 0.5em; vertical-align: middle; margin-left: 16px; padding: 0 2px;">Beta</span>

> **Note:**
>
> TiDB Cloud CLI is in beta.
TiDB Cloud CLI is a command line interface, which allows you to operate TiDB Cloud from your terminal with a few lines of commands. In the TiDB Cloud CLI, you can easily manage your TiDB Cloud clusters, import data to your clusters, and perform more operations.

Expand All @@ -17,17 +21,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, region, shell | Manage TiDB Serverless clusters |
| 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 +49,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.

### Create a user profile
### Create a user profile with TiDB Cloud API key

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 +113,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. |
| -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. |

## Feedback

Expand Down
82 changes: 45 additions & 37 deletions tidb-cloud/get-started-with-cli.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,16 @@ 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.

> **Note:**
>
> TiDB Cloud CLI is in beta.
## 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 +85,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 +156,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 +165,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
4 changes: 2 additions & 2 deletions tidb-cloud/release-notes-2023.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -861,7 +861,7 @@ This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-c

**CLI changes**

- Add a new command [`ticloud cluster connect-info`](/tidb-cloud/ticloud-cluster-connect-info.md) for [TiDB Cloud CLI](/tidb-cloud/cli-reference.md).
- Add a new command `ticloud cluster connect-info` for [TiDB Cloud CLI](/tidb-cloud/cli-reference.md).

`ticloud cluster connect-info` is a command that allows you to get the connection string of a cluster. To use this command, [update `ticloud`](/tidb-cloud/ticloud-update.md) to v0.3.2 or a later version.

Expand Down Expand Up @@ -890,7 +890,7 @@ This page lists the release notes of [TiDB Cloud](https://www.pingcap.com/tidb-c

**CLI changes**

- Add a new command [`ticloud connect`](/tidb-cloud/ticloud-connect.md) for [TiDB Cloud CLI](/tidb-cloud/cli-reference.md).
- Add a new command [`ticloud connect`](/tidb-cloud/ticloud-serverless-shell.md) for [TiDB Cloud CLI](/tidb-cloud/cli-reference.md).

`ticloud connect` is a command that allows you to connect to your TiDB Cloud cluster from your local machine without installing any SQL clients. After connecting to your TiDB Cloud cluster, you can execute SQL statements in the TiDB Cloud CLI.

Expand Down
47 changes: 47 additions & 0 deletions tidb-cloud/ticloud-ai.md
View file
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.
Loading

0 comments on commit fae4309

Please sign in to comment.