@gopay/minikit-cli

A CLI tool for scaffolding and managing GoPay mini-app web projects.

Prerequisites

Bun — a fast JavaScript runtime and package manager used to run the CLI.

bun --version

If it's not installed:

curl -fsSL https://bun.com/install | bash -s "bun-v1.3.14"

Installation

bun install -g @gopay/minikit-cli

Verify the installation:

minikit-cli --version

Complete Command Reference

Command Groups

| Group | Commands | |---|---| | Project scaffolding | create | | Feature commands | jsbridge:add, jsbridge:remove, i18n:add, snap:add, vconsole:add | | CLI management | update, migrate | | Utilities | docs, --help |

create

Scaffolds a new mini-app project interactively.

minikit-cli create [project_name] [options]

Arguments

| Argument | Required | Description | |---|---|---| | project_name | No (prompted) | Name of the project to create |

Options

| Flag | Description | |---|---| | --no-install | Skip dependency installation | | --project-dir <path> | Target directory to create the project in (defaults to current directory) |

Examples

# Fully interactive — prompts for everything
minikit-cli create

# Skip the name prompt, still prompts for features
minikit-cli create my-app

# Create project without installing dependencies
minikit-cli create my-app --no-install

# Create project in a specific directory
minikit-cli create my-app --project-dir /tmp/scaffolds --no-install

Interactive prompt flow

When run interactively (with a TTY), the wizard walks through the following steps in order:

1. Project name — text input (skipped if passed as an argument)

   Project name? › my-app

2. Framework — single select

   Choose framework:
   ● React + TypeScript

3. Install dependencies — confirmation

   Install dependencies with pnpm? › yes / no

4. Features — multi-select (space to toggle, enter to confirm)

   Select features to include:
   ◯ Auth
   ◯ i18n
   ◯ Snap Checkout

5. Per-feature options — shown immediately after each selected feature. For example, selecting Auth shows:

   When to fetch auth code?
   ● Before app renders (fetch Auth Code first)
   ○ After app renders (fetch Auth Code after UI loads)

6. Debug tools — multi-select

   Select debug tools:
   ◯ vConsole

After the wizard completes, the CLI prints next steps:

1. cd my-app
2. source "$HOME/.nvm/nvm.sh" && nvm use
3. cp .env.example .env  (update .env values based on your project)
4. pnpm install          (only shown if deps were not installed)
5. pnpm dev

Important notes:

• NVM (source "$HOME/.nvm/nvm.sh" && nvm use): Loads the NVM shell integration and switches to the Node version specified in .nvmrc. Run this every time you:

  • Switch to a different project folder
  • Open a new terminal/shell session
  • If nvm isn't configured to auto-load in your shell config (.bashrc, .zshrc)
  • This ensures pnpm and other tools use the correct Node version for your project

• .env configuration: After copying .env.example to .env, update the values according to your project requirements. Each environment variable is documented in the .env.example file with examples and descriptions.

jsbridge:add

Add a Host App method to call from your Mini App.

minikit-cli jsbridge:add [className] [methodName] [options]

Arguments

| Argument | Format | Example | |---|---|---| | className | PascalCase | GPAuth, GPWallet | | methodName | camelCase | getToken, getBalance |

Both arguments are optional — omit either to be prompted.

Options

| Option | Alias | Description | |---|---|---| | --cache | -c | Cache the result for the session lifetime |

Examples

minikit-cli jsbridge:add
minikit-cli jsbridge:add GPAuth getToken --cache

This creates a handler in src/bridge/handlers/ and automatically exports it.

jsbridge:remove

Remove a previously added JS Bridge method and its generated hook.

minikit-cli jsbridge:remove [className] [methodName]

Both arguments are optional — omit either to pick from a list.

Examples

minikit-cli jsbridge:remove
minikit-cli jsbridge:remove GPAuth getToken

This cleans up the handler files and associated exports.

i18n:add

Add multi-language support with JSON-based translations.

minikit-cli i18n:add

Translations are stored and managed in local JSON files, which is simple and suitable for projects needing basic internationalization.

snap:add

Add Snap Checkout (Midtrans) payment integration.

minikit-cli snap:add

No options or prompts — fully automatic. Generates a Snap Checkout page, registers a /snap-checkout route, and adds required env keys to .env.example.

vconsole:add

Add vConsole, an in-app debug panel.

minikit-cli vconsole:add

No options or prompts — fully automatic. Provides a mobile-friendly console for viewing logs and debugging the app. Active in dev mode by default.

update

Update the MiniKit CLI itself to the latest published version.

minikit-cli update [options]

Options

| Option | Description | |---|---| | --check | Report current vs. latest version without installing | | --tag <tag> | dist-tag to resolve. Defaults to beta for prerelease installs, latest for stable. |

Examples

minikit-cli update
minikit-cli update --check
minikit-cli update --tag latest

Run minikit-cli migrate inside each project after updating to apply project-level migrations.

migrate

Apply version-to-version migrations to an existing project. Run after minikit-cli update.

minikit-cli migrate [target-version] [options]

Options

| Option | Description | |---|---| | --to <version> | Migrate only up to this version | | --dry-run | Show the migration plan without applying changes | | --check | Report the project's current version vs. the latest reachable version |

Examples

minikit-cli migrate
minikit-cli migrate --dry-run
minikit-cli migrate --to 1.3.0
minikit-cli migrate --check

docs

List or search documentation links.

minikit-cli docs [keyword]

Examples

minikit-cli docs
minikit-cli docs jsbridge

Search is case-insensitive, matches document names and titles.

Getting help

Every command supports --help:

minikit-cli --help
minikit-cli create --help
minikit-cli update --help
minikit-cli migrate --help
minikit-cli jsbridge:add --help
minikit-cli jsbridge:remove --help
minikit-cli snap:add --help
minikit-cli vconsole:add --help
minikit-cli i18n:add --help