From 72bc4a6ad2fe6aad23b2177d97605dc31a45acdb Mon Sep 17 00:00:00 2001
From: JoyinQ <56883733+Joyinqin@users.noreply.github.com>
Date: Thu, 11 Mar 2021 11:51:04 +0800
Subject: [PATCH] tiup: add command docs of clean, install and status (#4979)

* tiup: add command docs of clean, install and status

* Update tiup-command-install.md

* Update tiup-command-status.md

* refine the docs

* Apply suggestions from code review

Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com>

* Update tiup-command-status.md

* Update tiup/tiup-command-clean.md

* refine the doc

* Update tiup/tiup-command-clean.md

Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com>
---
 tiup/tiup-command-clean.md        | 29 ++++++++++++++++++++++++
 tiup/tiup-command-install.md      | 25 +++++++++++++++++++++
 tiup/tiup-command-status.md       | 37 +++++++++++++++++++++++++++++++
 tiup/tiup-component-management.md |  2 +-
 4 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 tiup/tiup-command-clean.md
 create mode 100644 tiup/tiup-command-install.md
 create mode 100644 tiup/tiup-command-status.md

diff --git a/tiup/tiup-command-clean.md b/tiup/tiup-command-clean.md
new file mode 100644
index 0000000000000..e849216d3635d
--- /dev/null
+++ b/tiup/tiup-command-clean.md
@@ -0,0 +1,29 @@
+---
+title: tiup clean
+---
+
+# tiup clean
+
+The `tiup clean` command is used to clear the data generated during component operation.
+
+## Syntax
+
+```sh
+tiup clean [name] [flags]
+```
+
+The value of `[name]` is the `Name` field output by the [`status` command](/tiup/tiup-command-status.md). If `[name]` is omitted, you must add the `--all` option in the `tiup clean` command.
+
+## Option
+
+### --all
+
+- Clears all operation records
+- Data type: Boolean
+- Default: false
+
+## Output
+
+```
+Clean instance of `%s`, directory: %s
+```
diff --git a/tiup/tiup-command-install.md b/tiup/tiup-command-install.md
new file mode 100644
index 0000000000000..acf5570708e6a
--- /dev/null
+++ b/tiup/tiup-command-install.md
@@ -0,0 +1,25 @@
+---
+title: tiup install
+---
+
+# tiup install
+
+The `tiup install` command is used for component installation. It downloads the component package of a specified version from the mirror repository and decompresses it in the local TiUP data directory for later use. In addition, when TiUP needs to run a component that does not exist in the mirror repository, it tries to download the component first and then runs it automatically. If the component does not exist in the repository, an error is reported.
+
+## Syntax
+
+```sh
+tiup install <component1>[:version] [component2...N] [flags]
+```
+
+`<component1>` and `<component2>` represent component names, and `[version]` represents an optional version number. If `version` is not added, the latest stable version of the specified component is installed. `[component2...N]` means that you can specify multiple components or multiple versions of the same component at the same time.
+
+## Option
+
+None
+
+## Output
+
+- Normally outputs the download information of the component.
+- If the component does not exist, the `The component "%s" not found` error is reported.
+- If the version does not exist, the `version %s not supported by component %s` error is reported.
diff --git a/tiup/tiup-command-status.md b/tiup/tiup-command-status.md
new file mode 100644
index 0000000000000..bdddcdb8b9b3d
--- /dev/null
+++ b/tiup/tiup-command-status.md
@@ -0,0 +1,37 @@
+---
+title: tiup status
+---
+
+# tiup status
+
+The `tiup status` command is used to view the operation information of the components after you run the components using the `tiup [flags] <component> [args...]` command.
+
+> **Note:**
+>
+> You can only query the information of the following components:
+>
+> - Components that are still in operation
+> - Components that run through the tag specified by `tiup -T/--tag`
+
+## Syntax
+
+```sh
+tiup status [flags]
+```
+
+## Option
+
+None
+
+## Output
+
+A table consisting of the following fields:
+
+- `Name`: The tag name specified by `-T/--tag`. If not specified, it is a random string.
+- `Component`: The operating components.
+- `PID`: The corresponding process ID of the operating components.
+- `Status`: The status of the operating components.
+- `Created Time`: The starting time of the components.
+- `Directory`: The data directory of the components.
+- `Binary`: The binary file path of the components.
+- `Args`: The starting arguments of the operating components.
diff --git a/tiup/tiup-component-management.md b/tiup/tiup-component-management.md
index a3abb56204e32..b462559d6124f 100644
--- a/tiup/tiup-component-management.md
+++ b/tiup/tiup-component-management.md
@@ -95,7 +95,7 @@ Example 1: Upgrade all components to the latest versions.
 tiup update --all
 ```
 
-Example: Upgrade all components to the nightly version.
+Example 2: Upgrade all components to the nightly version.
 
 {{< copyable "shell-regular" >}}