MerchantDuo CLI

Append-only console interface for MerchantDuo deploy and sandbox workflows, with an ora spinner for the current in-flight phase on interactive terminals.

Usage

pnpx @neutrome-labs/merchantduo --help
pnpx @neutrome-labs/merchantduo deploy --help
pnpx @neutrome-labs/merchantduo upgrade --help
pnpx @neutrome-labs/merchantduo sandbox --help

Global flags:

• --config <path>: resolve merchantduo.jsonc from a custom path
• --verbose: print info logs to stderr
• --debug: print debug logs to stderr
• --non-interactive: disable prompts and require config to already be complete

Environment knobs:

• MERCHANTDUO_HTTP_TIMEOUT_MS: override the CLI API request timeout for long remote upgrade/provision calls. Default is 600000.

The CLI always writes durable output as appended stdout/stderr lines. Interactive TTY runs also show a transient spinner on stderr for the current status or running task.

Deploy config prompts use @clack/prompts before long-running work starts. If merchantduo.jsonc is missing required values and prompts are disabled, the command fails and asks you to fill the file manually or rerun interactively.

Remote provision logs stay hidden unless --verbose or --debug is enabled. When enabled, they are appended as raw log lines.

Deploy

deploy deploys current Magento project to the MerchantDuo Cloudflare Cloud. It finalizes staged artifacts into a raw provision payload.

If merchantduo.jsonc already has an id, deploy warns that it will create a brand-new instance and suggests upgrade instead. In non-interactive mode that becomes an error.

Useful runtime toggles:

• --dry-run: run local stage commands and artifact creation, but skip upload and instance provision
• --skip-composer
• --skip-di-compile
• --skip-theme
• --skip-static-content

merchantduo.jsonc also includes local snapshot commands:

• snapshot.fs: builds the filesystem artifact into $SNAPSHOT_FS_OUTFILE from $SNAPSHOT_SOURCE_DIR
• snapshot.db.fast: writes a mydumper-style directory to $SNAPSHOT_DB_DIR
• snapshot.db.slow: writes a gzipped SQL dump to $SNAPSHOT_DB_OUTFILE

These commands run through bash -lc, so you can swap them for local tooling differences. If a snapshot command references n98-magerun2 but only n98-magerun is installed, the CLI falls back automatically.

Upgrade

upgrade updates the instance referenced by merchantduo.jsonc.id in place. It builds the local filesystem, requests an upload quote, uploads only the replacement filesystem, finalizes that upload into a runtime snapshot, then starts a single remote upgrade workflow and waits for it to finish.

Useful runtime toggles:

• --dry-run: run local upgrade stages and filesystem packaging, but skip remote upload and upgrade workflow
• --skip-composer
• --skip-di-compile
• --skip-theme
• --skip-static-content

Sandbox

sandbox provisions a new clean 1 hour Magento 2 instance. Supported sandbox templates:

• magento24
• breeze-blank
• breeze-evolution

Template params are passed with repeatable --param <path=value>.

Examples:

merchantduo sandbox \
  --template breeze-blank \
  --param withSampleData=true \
  --param composerPackages=vendor/package \
  --param [email protected]

Array-valued fields can be repeated:

merchantduo sandbox \
  --param composerPackages=swissup/module-marketplace \
  --param composerPackages=swissup/breeze-blank

Full JSON values are preserved, so you can pass the entire auth object at once:

merchantduo sandbox \
  --param 'authJson={"http-basic":{"repo.magento.com":{"username":"public","password":"secret"}}}'

You can also mix dot notation with JSON object leaves when a nested key itself contains dots:

merchantduo sandbox \
  --param 'authJson.http-basic={"repo.magento.com":{"username":"public","password":"secret"}}'

Supported grades across provision/deploy flows:

• sandbox
• dev
• live