MiniProgram Command-line Interface

2024-03-22 03:05

MiniProgram Command-line Interface (MiniProgram CLI) offers mini-program developers a text-based tool for managing mini programs on Mini Program Platform. This tool is available across Windows, macOS, and Linux systems. It enables you to automate development processes and integrate your workflow into a continuous integration and delivery (CI/CD) pipeline.

This topic provides a comprehensive reference of available commands of MiniProgram CLI and instructions on how to use the CLI.

Command reference

The following table lists all available commands of MiniProgram CLI and the corresponding command descriptions:

Command name	Description
`miniprogram-cli -v` or `miniprogram-cli --version`	Check the installed CLI's version information.
`miniprogram-cli -h` or `miniprogram-cli --help`	Get a full list of commands and their usage, or help of a specific command.
`miniprogram-cli init`	Initialize the CLI with your access token. For more information, refer to Initialize MiniProgram CLI.
`miniprogram-cli info`	Retrieve the current CLI initialization settings. For more information, refer to Check initialization settings.
`miniprogram-cli preview`	Generate a QR code for previewing your mini program. For more information, refer to Preview mini programs.
`miniprogram-cli upload`	Upload a mini-program package to Mini Program Platform. For more information, refer to Upload mini programs.

Prerequisites

Before using the CLI commands, ensure that you meet the following prerequisites:

Have a basic knowledge of running command lines in Windows, macOS, or Linux systems.
Install Node.js 16 on your operating system.
Learn the permissions of your user role on Mini Program Platform to prevent any unauthorized operation errors. For more information, refer to Member roles.
Ensure that the mini program that you intend to operate via MiniProgram CLI is already created within your workspace. For guidance on creating a mini program, refer to Create mini programs.

Install or upgrade MiniProgram CLI

You can install or upgrade the latest MiniProgram CLI version by running the following command in your preferred terminal:

copy
npm install -g @antglobal/miniprogram-cli

If you require a specific CLI version, include the version number by adding @<version> after the package name. The installation process only takes a few seconds. To confirm the installation or check the installed version, run the following command:

copy
miniprogram-cli -v
> 1.0.0

Initialize MiniProgram CLI

After installing MiniProgram CLI for the first time, you must initialize it with your access token. This step links the CLI to your Mini Program Platform account, which verifies your identity and access permissions. To complete the initialization, take the following two steps:

Step 1: Obtain access token

The access token consists of the following two parts:

Access Key: The unique identifier of the user.
Access Secret: The confidential key used to authenticate and verify the user's identity.

To obtain this information, follow these steps:

Log into Mini Program Platform.
(Optional) If you have multiple workspaces, select and click one to enter a workspace.
Click the profile icon in the top right corner, then click Profile.
Click Add in the Access Token section to generate the access key and access secret.

Note: If your access token is compromised, you can click Delete in the Access Token section to deactivate your current access key and access secret. Then click Add to generate a new one.

Step 2: Run the initialization command

To initialize the CLI, run the following command:

copy
# miniprogram-cli init [options]
# Options:
#  -i,--access-key-id
#  -s,--access-key-secret

miniprogram-cli init --access-key-id <accessKeyId> --access-key-secret <accessKeySecret>

You can also use this command to update your credentials later. Refer to the following table for details about the command options:

Option

Required

Description

-i or

--access-key-id

Specify this option with the access key you obtained in Step 1. Otherwise, you will be prompted to enter the value in the terminal.

-s or

--access-key-secret

Specify this option with the access secret you obtained in Step 1. Otherwise, you will be prompted to enter the value in the terminal.

Use the CLI commands

Mini-program developers can use the MiniProgram CLI commands for various scenarios. The commands offer multiple options and parameters, allowing for customization of their behavior. The following sections provide detailed descriptions and sample codes for using the CLI commands.

Check initialization settings

If you encounter a permission error, you might need to review your current initialization settings. You can run the following command to obtain the location of your configuration file and the current settings:

copy
miniprogram-cli info
> configuration file:  /User/yourname/.miniprogram-cli/settings.json
> { "accessKeyId": "-", "accessKeySecret": "-" }

Preview mini programs

Once you complete the development process, you can preview your mini program from an end user's perspective within the target super app. To initiate the preview, run the following command to generate a QR code, and then use the super app to scan the code to open your mini program.

copy
# miniprogram-cli preview [options]
# Options:
#   -a,--app-id       
#   -w,--workspace-id
#   -c,--client-id
#   -p,--project-path

miniprogram-cli preview -w <workspaceId> -c <clientId> -a <appId>

When using this command, you can specify the following options:

Option	Required	Description
`-w` or `--workspace-id`	No	The unique ID that is assigned by Mini Program Platform to identify the workspace where your mini program is created. Notes: If this option is not specified, the terminal prompts you to select from a list of accessible workspaces. This list includes the workspace names and corresponding IDs. If only one workspace is available, it will be selected by default. It is recommended to use this selection feature to obtain a workspace ID when running the command for the first time. You can also obtain the workspace ID on Mini Program Platform by navigating to the target workspace. The ID is specified by the wsid query parameter in the URL.
`-c` or `--client-id`	No	The unique ID that is assigned by Mini Program Platform to identify the super app that is used to scan the generated QR code for previewing your mini program. Notes: If this option is not specified, the terminal prompts you to select from a list of super apps associated with the specified workspace. This list includes the super app names and corresponding IDs. If only one super app is available, it will be selected by default. It is recommended to use this selection feature to obtain a client ID when running the command for the first time. For super apps, you can also obtain the client ID on Mini Program Platform by navigating to Apps and then clicking the app to enter its details page. The ID is located in two places: Under the APP ID field. The value of the mobileAppId query parameter in the URL. For mini-program developers, you can also consult the super app for the client ID.
`-a` or `--app-id`	No	The unique ID that is assigned by Mini Program Platform to identify a mini program that you need to preview. This mini program must be accessible by your role in the specified workspace. Notes: If this option is not specified, the terminal prompts you to select from a list of mini programs that you can access in the specified workspace. If only one mini program is available, it will be selected by default. It is recommended to use this selection feature to obtain a mini-program ID when running the command for the first time. You can also obtain the mini-program ID on Mini Program Platform by navigating to the details page of the target mini program. The ID is located in two places: Under the Mini Program ID field. The value of the appId query parameter in the URL.
`-p` or `--project-path`	No	The directory of your mini-program project. If not specified, the value is the current working directory by default.

Upload mini programs

Once you finish developing and debugging your mini program, you can upload its project to Mini Program Platform. This prepares you to launch the mini program to a super app. Run the following command to upload your mini-program project:

copy
# miniprogram-cli upload [options]
# Options:
#   -a,--app-id       
#   -w,--workspace-id
#   -c,--client-id
#   -p,--project-path
#   -n,--next-version

miniprogram-cli upload -w <workspaceId> -c <clientId> -a <appId> -n <nextVersion>

When using this command, you can specify the following options:

Option	Required	Description
`-w` or `--workspace-id`	No	The unique ID that is assigned by Mini Program Platform to identify the workspace where your mini program is uploaded. Notes: If this option is not specified, the terminal prompts you to select from a list of accessible workspaces. This list includes the workspace names and corresponding IDs. If only one workspace is available, it will be selected by default. It is recommended to use this selection feature to obtain a workspace ID when running the command for the first time. You can also obtain the workspace ID on Mini Program Platform by navigating to the target workspace. The ID is specified by the wsid query parameter in the URL.
`-c` or `--client-id`	No	The unique ID that is assigned by Mini Program Platform to identify the super app where your mini program is to be launched. Notes: If this option is not specified, the terminal prompts you to select from a list of super apps associated with the specified workspace. This list includes the super app names and corresponding IDs. If only one super app is available, it will be selected by default. It is recommended to use this selection feature to obtain a client ID when running the command for the first time. For super apps, you can also obtain the client ID on Mini Program Platform by navigating to Apps and then clicking the app to enter its details page. The ID is located in two places: Under the APP ID field. The value of the mobileAppId query parameter in the URL. For mini-program developers, you can also consult the super app for the client ID.
`-a` or `--app-id`	No	The unique ID that is assigned by Mini Program Platform to identify the mini program for upload. This mini program must be accessible by your role in the specified workspace. Notes: If this option is not specified, the terminal prompts you to select from a list of mini programs that you can access in the specified workspace. If only one mini program is available, it will be selected by default. It is recommended to use this selection feature to obtain a mini-program ID when running the command for the first time. You can also obtain the mini-program ID on Mini Program Platform by navigating to the details page of the target mini program. The ID is located in two places: Under the Mini Program ID field. The value of the appId query parameter in the URL.
`-p` or `--project-path`	No	The directory of your mini-program project. If not specified, the value is the current working directory by default.
`-n` or `--next-version`	No	The version number of the uploaded mini program. The value follows the `major.minor.patch` format. Notes: The new version number must be greater than the previous one. It is recommended to specify a version number according to Semantic Versioning. If not specified, the value defaults to the previous version number incremented by one at the patch level.