MiniProgram Command-line Interface

2026-10-12 01:00

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 keys

The access token consists of the following two parts:

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

To obtain this information, follow these steps:

Log in to Mini Program Platform and navigate to the workspace containing the target mini program.
Click the profile icon in the top-right corner, then click My Profile.
In the Access Keys section, click Generate Keys.
In the confirmation dialog, follow the on-screen instructions to set a password to encrypt the file that contains the keys.
Click Generate Keys.
Check your email inbox for an email titled Your MiniProgram CLI Access Keys Are Ready, then follow the instructions in the email to obtain the keys from the attached ZIP file.

Note: For security reasons, the secret key is always masked on the platform. If you generated keys before September 22, 2026, you will not have received an email containing your keys. If you need the keys, for example, to set up the CLI on a new machine for the first time, you can obtain valid keys in the following ways:
If you have already used the keys to initialize the CLI on another machine, retrieve the existing keys from the CLI configuration file. For details, see Check initialization settings.
If you do not have the keys stored anywhere, click Regenerate Keys to create new ones.

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,--secret-access-key

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

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 ID you obtained in Step 1. Otherwise, you will be prompted to enter the value in the terminal.

-s or

--secret-access-key

Specify this option with the secret access key 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": "-", "secretAccessKey": "-" }

Preview mini programs

After 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 miniprogram-cli preview [options] 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:
#   -m,--mini-program-id       
#   -w,--workspace-id
#   -sa,--super-app-id
#   -p,--project-path

miniprogram-cli preview -w <workspaceId> -sa <superAppId> -m <miniProgramId>

Note:

After confirming that the directory of your mini program project exists (specified by the -p option), it reads the file size (source package) under the directory. The maximum size for uploads from the CLI is 100 MB. For more information, see:

Command syntax

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. Note: 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.
`-sa` or `--super-app-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. Note: 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 super app ID when running the command for the first time. For super apps, you can also obtain the 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 ID.
`-m` or `--mini-program-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. Note: 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

After you finish developing and debugging your mini program, you can upload its project to Mini Program Platform. This prepares you to release the mini program to a super app.

Run the miniprogram-cli upload [options] command to upload your mini-program project:

copy
# miniprogram-cli upload [options]
# Options:
#   -m,--mini-program-id       
#   -w,--workspace-id
#   -sa,--super-app-id
#   -p,--project-path
#   -mv,--mini-program-version

miniprogram-cli upload -w <workspaceId> -sa <superAppId> -m <miniProgramId> -mv <miniProgramVersion>

Note:

Command syntax

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. Note: 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.
`-sa` or `--super-app-id`	No	The unique ID that is assigned by Mini Program Platform to identify the super app where your mini program is to be released. This ID must belong to the default super app determined by the platform. Note: 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 super app ID when running the command for the first time. For super apps, you can also obtain the default super app ID on Mini Program Platform. Go to Apps, then click the app marked with a star 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 merchants: If your mini program can be released to only one app, use the terminal selection feature to obtain the ID. If your mini program can be released to multiple apps, consult the super app to confirm the default app and its ID.
`-m` or `--mini-program-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. Note: 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.
`-mv` or `--mini-program-version`	No	The version number of the uploaded mini program. The value follows the `major.minor.patch` format. Note: 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.