docs: add transfer command to pipectl CLI documentation

Author: vedantlavale

docs/content/en/docs-dev/user-guide/command-line-tool.md

@@ -153,6 +153,7 @@ Available Commands:
   piped        Manage piped resources.
   plan-preview Show plan preview against the specified commit.
   plugin       Do plugin tasks.
+  transfer     Transfer data between control planes.
   version      Print the information of current binary.
 
 Flags:
@@ -357,11 +358,11 @@ You can encrypt it the same way you do [from the web](../managing-application/se
       --input-file={PATH_TO_SECRET_FILE}
   ```
 
-Note: The docs for pipectl available command is maybe outdated, we suggest users use the `help` command for the updated usage while using pipectl.
+> **Note:** The docs for pipectl available command may be outdated. We suggest users use the `help` command for the updated usage while using pipectl.
 
 ### Migrating application configs and database
 
-Migrate v0 application configs and database records to be compatible with the plugin-based pipedv1.
+Migrate v0 application configs and database records to be compatible with the plugin-based piped v1.
 
 #### Migrating application config
 
@@ -383,7 +384,7 @@ The `--config-files` and `--dirs` flags are mutually exclusive; one of them is r
 
 #### Migrating database
 
-Migrate database records to be compatible with plugin-architectured piped:
+Migrate database records to be compatible with plugin-architected piped:
 
 ``` console
 pipectl migrate database \
@@ -408,6 +409,49 @@ pipectl plugin push \
 
 The `--files` flag maps platforms to binary files in `os/arch=filepath` format. All of `--files`, `--tag`, `--registry`, and `--repository` are required. Add `--insecure` to skip TLS verification when using an HTTP-only registry.
 
+### Transferring data between control planes
+
+Transfer pipeds and applications from one control plane to another.
+
+#### Backing up data
+
+Back up all pipeds and applications from the source control plane to a local file:
+
+``` console
+pipectl transfer backup \
+    --address={SOURCE_CONTROL_PLANE_API_ADDRESS} \
+    --api-key={SOURCE_API_KEY} \
+    --output-file=backup.json
+```
+
+Add `--labels` to filter applications by labels (comma-separated `KEY:VALUE` pairs, e.g. `--labels=env:prod,team:backend`). Deployment history is not included, because the API does not expose a write endpoint for deployments.
+
+#### Restoring data
+
+Restoring is a two-step process, because the control plane validates that each application's Git repository is registered on the target piped before the application can be created, and repository registration only happens after the piped agent connects.
+
+1. Register the pipeds on the target control plane, then update each piped's configuration with the new ID and key before restarting the piped agents:
+
+    ``` console
+    pipectl transfer restore piped \
+        --address={TARGET_CONTROL_PLANE_API_ADDRESS} \
+        --api-key={TARGET_API_KEY} \
+        --input-file=backup.json \
+        --output-file=mapping.json
+    ```
+
+2. Once the piped agents have reconnected to the target control plane and registered their repositories, restore the applications:
+
+    ``` console
+    pipectl transfer restore application \
+        --address={TARGET_CONTROL_PLANE_API_ADDRESS} \
+        --api-key={TARGET_API_KEY} \
+        --input-file=backup.json \
+        --piped-id-mapping-file=mapping.json
+    ```
+
+Disabled applications from the source are restored and immediately re-disabled on the target to preserve their original status.
+
 ### You want more?
 
 We always want to add more needed commands into pipectl. Please let us know what command you want to add by creating issues in the [pipe-cd/pipecd](https://github.com/pipe-cd/pipecd/issues) repository. We also welcome your pull request to add the command.

docs/content/en/docs-v0.57.x/user-guide/command-line-tool.md

@@ -144,13 +144,16 @@ Usage:
 
 Available Commands:
   application  Manage application resources.
+  completion   Generate the autocompletion script for the specified shell
   deployment   Manage deployment resources.
   encrypt      Encrypt the plaintext entered in either stdin or the --input-file flag.
   event        Manage event resources.
   help         Help about any command
-  init         Generate an application config (app.pipecd.yaml) easily and interactively.
+  migrate      Do migration tasks.
   piped        Manage piped resources.
   plan-preview Show plan preview against the specified commit.
+  plugin       Do plugin tasks.
+  transfer     Transfer data between control planes.
   version      Print the information of current binary.
 
 Flags:
@@ -355,39 +358,99 @@ You can encrypt it the same way you do [from the web](../managing-application/se
       --input-file={PATH_TO_SECRET_FILE}
   ```
 
-Note: The docs for pipectl available command is maybe outdated, we suggest users use the `help` command for the updated usage while using pipectl.
+> **Note:** The docs for pipectl available command may be outdated. We suggest users use the `help` command for the updated usage while using pipectl.
 
-### Generating an application config (app.pipecd.yaml)
+### Migrating application configs and database
 
+Migrate v0 application configs and database records to be compatible with the plugin-based piped v1.
 
-Generate an app.pipecd.yaml interactively:
+#### Migrating application config
+
+Convert v0 application config files to the v1 format:
+
+``` console
+pipectl migrate application-config \
+    --config-files=path/to/app.pipecd.yaml
+```
+
+Or migrate all application config files in a directory:
+
+``` console
+pipectl migrate application-config \
+    --dirs=path/to/app/directory
+```
+
+The `--config-files` and `--dirs` flags are mutually exclusive; one of them is required. The original file is backed up with a `.old` extension.
+
+#### Migrating database
+
+Migrate database records to be compatible with plugin-architected piped:
+
+``` console
+pipectl migrate database \
+    --address={CONTROL_PLANE_API_ADDRESS} \
+    --api-key={API_KEY} \
+    --applications={APPLICATION_ID}
+```
+
+The `--applications` flag accepts a list of application IDs and is required.
+
+### Pushing a plugin
+
+Push a plugin binary to an OCI registry:
 
 ``` console
-$ pipectl init
-Which platform? Enter the number [0]Kubernetes [1]ECS: 1
-Name of the application: myApp
-...
+pipectl plugin push \
+    --files=linux/amd64=./plugin-linux-amd64,linux/arm64=./plugin-linux-arm64 \
+    --tag=v0.1.0 \
+    --registry=ghcr.io/pipe-cd \
+    --repository=my-plugin
 ```
 
-After the above interaction, you can get the config YAML:
-
-```yaml
-apiVersion: pipecd.dev/v1beta1
-kind: ECSApp
-spec:
-  name: myApp
-  input:
-    serviceDefinitionFile: serviceDef.yaml
-    taskDefinitionFile: taskDef.yaml
-    targetGroups:
-      primary:
-        targetGroupArn: arn:aws:elasticloadbalancing:ap-northeast-1:123456789012:targetgroup/xxx/xxx
-        containerName: web
-        containerPort: 80
-  description: Generated by `pipectl init`. See https://pipecd.dev/docs/user-guide/configuration-reference/ for more.
+The `--files` flag maps platforms to binary files in `os/arch=filepath` format. All of `--files`, `--tag`, `--registry`, and `--repository` are required. Add `--insecure` to skip TLS verification when using an HTTP-only registry.
+
+### Transferring data between control planes
+
+Transfer pipeds and applications from one control plane to another.
+
+#### Backing up data
+
+Back up all pipeds and applications from the source control plane to a local file:
+
+``` console
+pipectl transfer backup \
+    --address={SOURCE_CONTROL_PLANE_API_ADDRESS} \
+    --api-key={SOURCE_API_KEY} \
+    --output-file=backup.json
 ```
 
-See [Feature Status](../feature-status/_index.md#pipectl-init).
+Add `--labels` to filter applications by labels (comma-separated `KEY:VALUE` pairs, e.g. `--labels=env:prod,team:backend`). Deployment history is not included, because the API does not expose a write endpoint for deployments.
+
+#### Restoring data
+
+Restoring is a two-step process, because the control plane validates that each application's Git repository is registered on the target piped before the application can be created, and repository registration only happens after the piped agent connects.
+
+1. Register the pipeds on the target control plane, then update each piped's configuration with the new ID and key before restarting the piped agents:
+
+    ``` console
+    pipectl transfer restore piped \
+        --address={TARGET_CONTROL_PLANE_API_ADDRESS} \
+        --api-key={TARGET_API_KEY} \
+        --input-file=backup.json \
+        --output-file=mapping.json
+    ```
+
+2. Once the piped agents have reconnected to the target control plane and registered their repositories, restore the applications:
+
+    ``` console
+    pipectl transfer restore application \
+        --address={TARGET_CONTROL_PLANE_API_ADDRESS} \
+        --api-key={TARGET_API_KEY} \
+        --input-file=backup.json \
+        --piped-id-mapping-file=mapping.json
+    ```
+
+Disabled applications from the source are restored and immediately re-disabled on the target to preserve their original status.
 
 ### You want more?
 

docs/content/en/docs-v1.0.x/user-guide/command-line-tool.md

@@ -153,6 +153,7 @@ Available Commands:
   piped        Manage piped resources.
   plan-preview Show plan preview against the specified commit.
   plugin       Do plugin tasks.
+  transfer     Transfer data between control planes.
   version      Print the information of current binary.
 
 Flags: