• Modyo Command Line Interface (CLI)

• Introduction
• Commands
• License

Modyo Command Line Interface (CLI)

====================================

The Modyo Command Line Interface (CLI) is a command line tool based in two principles acceleration and integration, and this principles has a command get and push respectively.

Introduction

First, you need to bring the Modyo CLI on your local machine to have the modyo-cli command available, this will allow you to initialize a project with some Front end architectural decisions already taken, or use to initialize a widget from the catalog if you have access.

To use the Modyo's CLI, you have these options.

Global installation on your local machine

  npm i -g @modyo/cli #via npm
  yarn global add @modyo/cli #via yarn

This command will make the command modyo-cli available on the terminal session globally

Through NPX without installation

  npx @modyo/cli #via npx
  npx @modyo/cli@version #via npx - specific version

Commands

• modyo-cli autocomplete [SHELL]
• modyo-cli get NAME [DIRECTORY]
• modyo-cli help [COMMAND]
• modyo-cli preview
• modyo-cli push [NAME]
• modyo-cli support-bundle
• modyo-cli version

modyo-cli autocomplete [SHELL]

Display autocomplete installation instructions.

USAGE
  $ modyo-cli autocomplete [SHELL] [-r]

ARGUMENTS
  [SHELL]  (zsh|bash|powershell) Shell type

FLAGS
  -r, --refresh-cache  Refresh cache (ignores displaying instructions)

DESCRIPTION
  Display autocomplete installation instructions.

EXAMPLES
  $ modyo-cli autocomplete

  $ modyo-cli autocomplete bash

  $ modyo-cli autocomplete zsh

  $ modyo-cli autocomplete powershell

  $ modyo-cli autocomplete --refresh-cache

See code: @oclif/plugin-autocomplete

modyo-cli get NAME [DIRECTORY]

Pull a widget from our catalog into a new directory

USAGE
  $ modyo-cli get NAME [DIRECTORY] [--log] [--log-dir <value>] [-f] [-h] [-o <value>]

ARGUMENTS
  NAME         The name of the widget
  [DIRECTORY]  Name of directory to init

FLAGS
  -f, --force                 Override folder if exist
  -h, --help                  Output usage information
  -o, --organization=<value>  [default: dynamic-framework] Github Organization
      --log                   [env: MODYO_LOG] Enable diagnostic logging for this session
      --log-dir=<value>       [env: MODYO_LOG_DIR] Directory for diagnostic log files (default: .modyo-debug/)

DESCRIPTION
  Pull a widget from our catalog into a new directory

  In general, the `get` command is used to obtain a boilerplate widget.

EXAMPLES
  There are some public widget names that can be accessed via this command

  To initialize a widget

    $ modyo-cli get dynamic-react-base-template [DIRECTORY]

  From this command and on you can continue using the widget like any other front-end widget.
  Your organization can create its own custom templates to initialize new widgets and use them with the `organization`
  option

    $ modyo-cli get --organization=myOrganization my-custom-template-repo [DIRECTORY]

See code: src/commands/get.ts

modyo-cli help [COMMAND]

Display help for modyo-cli.

USAGE
  $ modyo-cli help [COMMAND...] [-n]

ARGUMENTS
  [COMMAND...]  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for modyo-cli.

See code: @oclif/plugin-help

modyo-cli preview

Preview local widget over Modyo platform

USAGE
  $ modyo-cli preview -t <value> -u <value> [--log] [--log-dir <value>] [-h] [-v 8|9|10] [-i <value> | -n
    <value>] [-p <value>] [-s <value>] [-j <value>] [-m]

FLAGS
  -h, --help                 Output usage information
  -i, --site-id=<value>      [env: MODYO_SITE_ID] Id of the site where the widget will be previewed
  -j, --entry-js=<value>     [default: main.js, env: MODYO_LOCAL_ENTRY_JS] Entry JS file of the widget
  -m, --module               [env: MODYO_LOCAL_MODULE] Load entry JS as an ES module (type="module")
  -n, --site-host=<value>    [env: MODYO_SITE_HOST] Host of the site where the widget will be previewed
  -p, --port=<value>         [default: 8080, env: MODYO_LOCAL_PORT] Deploy port local widget running
  -s, --dom-id=<value>       [default: widgetName, env: MODYO_LOCAL_DOM_ID] Container id of the widget
  -t, --token=<value>        (required) [env: MODYO_TOKEN] Modyo Api token
  -u, --account-url=<value>  (required) [env: MODYO_ACCOUNT_URL] URL of your ®Modyo account
                             ex("https://account.modyo.com")
  -v, --version=<option>     [default: 9, env: MODYO_VERSION] Version of Modyo platform
                             <options: 8|9|10>
      --log                  [env: MODYO_LOG] Enable diagnostic logging for this session
      --log-dir=<value>      [env: MODYO_LOG_DIR] Directory for diagnostic log files (default: .modyo-debug/)

DESCRIPTION
  Preview local widget over Modyo platform

  The `preview` command is responsible for informing the platform about local entry points so that the widget can be
  rendered on the platform locally.

  Configuration options can be provided either via environment variables or by defining them inside a .modyo file. Using
  a .modyo file is the recommended file-based approach, as it helps avoid accidentally committing sensitive information
  to version control.

  Note: The .env file is currently supported for backward compatibility but is deprecated and will be removed in future
  versions. When using environment variables, prefer setting them directly in your environment or via your preferred
  secrets management tooling.

  It is highly recommended to migrate any .env-based configuration to a .modyo file and add that file to your
  .gitignore.

  MODYO_VERSION=version
  MODYO_TOKEN=token
  MODYO_ACCOUNT_URL=account-url
  MODYO_SITE_ID=siteId
  MODYO_SITE_HOST=siteHost
  MODYO_LOCAL_PORT=port
  MODYO_LOCAL_DOM_ID=domId
  MODYO_LOCAL_ENTRY_JS=entryJs
  MODYO_LOCAL_MODULE=module


EXAMPLES
  $ modyo-cli preview

See code: src/commands/preview.ts

modyo-cli push [NAME]

Push widget to Modyo platform

USAGE
  $ modyo-cli push [NAME] -t <value> -u <value> [--log] [--log-dir <value>] [-p] [-h] [-d <value>] [-v
    8|9|10] [-i <value> | -n <value>] [-b <value>] [-e] [-l | -f <value>] [-z] [-j <value>] [-c <value>]

ARGUMENTS
  [NAME]  The name of the widget

FLAGS
  -b, --build-command=<value>         [default: build, env: MODYO_BUILD_COMMAND] Build command in package.json
  -c, --zip-entry-css=<value>         [default: main.css, env: MODYO_ZIP_ENTRY_CSS] Entry css file when use --zip flag
  -d, --build-directory=<value>       [default: dist, env: MODYO_BUILD_DIRECTORY] Build directory path
  -e, --[no-]remove-emojis            [deprecated] Remove emojis from the widget that will be pushed
  -f, --disable-liquid-regex=<value>  [env: MODYO_DISABLE_LIQUID_REGEX] Disable liquid on files that match a regex
  -h, --help                          Output usage information
  -i, --site-id=<value>               [env: MODYO_SITE_ID] Id of the site where the widget will be pushed
  -j, --zip-entry-js=<value>          [default: main.js, env: MODYO_ZIP_ENTRY_JS] Entry js file when use --zip flag
  -l, --disable-liquid                Disable liquid on all files
  -n, --site-host=<value>             [env: MODYO_SITE_HOST] Host of the site where the widget will be pushed
  -p, --publish                       Force widget publication
  -t, --token=<value>                 (required) [env: MODYO_TOKEN] Modyo Api token
  -u, --account-url=<value>           (required) [env: MODYO_ACCOUNT_URL] URL of your ®Modyo account
                                      ex("https://account.modyo.com")
  -v, --version=<option>              [default: 9, env: MODYO_VERSION] Version of Modyo platform
                                      <options: 8|9|10>
  -z, --zip                           [env: MODYO_ZIP] Zip bundle to publish
      --log                           [env: MODYO_LOG] Enable diagnostic logging for this session
      --log-dir=<value>               [env: MODYO_LOG_DIR] Directory for diagnostic log files (default: .modyo-debug/)

DESCRIPTION
  Push widget to Modyo platform

  The `push` command is the one in charge of the integration principle, used to send the widget to the selected site in
  the modyo platform.

  It will use an argument called name to upload the widget to the platform and some required flags like token site_base
  id or host to can identify the ®Modyo platform which host the widget and have an additional flag to avoid the manual
  process flow of widget publication.

  Many of the options can be provided either as environment variables or inside a .modyo configuration file. Using a
  .modyo file is the recommended file-based approach, as it helps keep sensitive information out of version control (for
  example, by adding it to your .gitignore).

  Note: Plain .env files are currently supported for backward compatibility but are deprecated and will be removed in
  future versions. It is highly recommended to migrate your configuration to either environment variables managed by
  your platform or a .modyo file.

  The following environment variables (or their equivalents in a .modyo file) are recognized:

  MODYO_WIDGET_NAME=name
  MODYO_BUILD_DIRECTORY=buildDirectoryPath
  MODYO_VERSION=version
  MODYO_TOKEN=token
  MODYO_ACCOUNT_URL=account-url
  MODYO_SITE_ID=siteId
  MODYO_SITE_HOST=siteHost
  MODYO_BUILD_COMMAND=buildCommand
  MODYO_REGEX_EXCLUDE=regexToExcludeFiles
  MODYO_DISABLE_LIQUID_REGEX=regexToDisableLiquidOnFiles
  MODYO_ZIP=true
  MODYO_ZIP_ENTRY_JS=main.js
  MODYO_ZIP_ENTRY_CSS=main.css


EXAMPLES
  $ modyo-cli push

See code: src/commands/push.ts

modyo-cli support-bundle

Package a diagnostic session into a zip file for support tickets

USAGE
  $ modyo-cli support-bundle [-s <value>] [--log-dir <value>]

FLAGS
  -s, --session=<value>  Session ID to package (default: most recent)
      --log-dir=<value>  [default: .modyo-debug, env: MODYO_LOG_DIR] Directory containing diagnostic sessions (default:
                         .modyo-debug/)

DESCRIPTION
  Package a diagnostic session into a zip file for support tickets

EXAMPLES
  $ modyo-cli support-bundle

  $ modyo-cli support-bundle --session push-20260422-183045-12345

  $ modyo-cli support-bundle --log-dir /tmp/my-logs

See code: src/commands/support-bundle.ts

modyo-cli version

USAGE
  $ modyo-cli version [--json] [--verbose]

FLAGS
  --verbose  Show additional information about the CLI.

GLOBAL FLAGS
  --json  Format output as json.

FLAG DESCRIPTIONS
  --verbose  Show additional information about the CLI.

    Additionally shows the architecture, node version, operating system, and versions of plugins that the CLI is using.

See code: @oclif/plugin-version

Using the --zip Flag and Code Splitting Support

The --zip flag is specifically designed for uploading widgets that use code splitting. This means the widget's build, typically configured through Webpack, splits the code into multiple JavaScript files (chunks) instead of a single bundled file.

When using the --zip flag, the CLI will package all widget files (JS, CSS, assets, etc.) into a .zip file. This ensures that Modyo's platform can correctly manage and load the chunks as needed.

Additionally, the --zip-entry-js and --zip-entry-css flags specify which files within the ZIP should be used as the widget's entry points. By default, these are set to main.js and main.css, but it can be customized if the project has a different build configuration.

Exclusive Compatibility with Webpack

The --zip flag is only compatible with Webpack. This is because Modyo uses a dynamic runtime path to load assets, which is specifically supported through Webpack’s configuration. Bundlers other than Webpack are not supported with this flag since they lack the necessary runtime path injection for chunk loading.

WebAssembly (WASM) Support

The CLI also supports uploading .wasm (WebAssembly) files. However, this support is conditional:

• The --zip flag must be enabled.

If .wasm files are present in your widget but the upload is performed without the --zip flag, these files will be ignored and won’t be available on the Modyo platform.

Diagnostics and Support Logging

The CLI includes a built-in diagnostic logger that captures a full, timestamped trace of every command execution. This is designed for troubleshooting — when something goes wrong, you can share the session folder with the Modyo support team or use it to file a detailed bug report.

Enabling diagnostic logging

Via flag (per command):

modyo-cli push --log
modyo-cli get --log
modyo-cli preview --log

Via environment variable (applies to all commands in the session):

MODYO_LOG=1 modyo-cli push

Both the flag and the environment variable produce identical output.

Session folder

Each command run creates a timestamped session folder inside .modyo-debug/ in the current working directory:

.modyo-debug/
└── push-20260422-183045-12345/       # <command>-<YYYYMMDD-HHmmss>-<pid>
    ├── diagnostics/
    │   ├── meta.json                  # Command metadata: argv, CLI version, OS, Node.js version
    │   ├── trace.ndjson               # Newline-delimited JSON event log (timeline of all events)
    │   ├── error.txt                  # Full error stack trace (only present when the command fails)
    │   ├── http-001-get-sites-request.json    # HTTP request body/headers for each API call
    │   ├── http-001-get-sites-response.json   # HTTP response body/headers for each API call
    │   └── ...                        # One pair of files per HTTP call (numbered sequentially)
    ├── build-stdout.txt               # Widget build stdout (push command only)
    └── build-stderr.txt               # Widget build stderr (push command only)

What gets captured

| File | Contents | |---|---| | meta.json | Command name, argv, CLI version, Node.js version, OS, start time, exit status | | trace.ndjson | Timestamped events: command start/end, HTTP calls (method, URL, status, duration), build steps, errors | | error.txt | Full stack trace and error message when the command exits with an error | | http-NNN-*-request.json | Full request body, headers (tokens redacted), URL, method | | http-NNN-*-response.json | Full response body, status code, headers | | build-stdout.txt | Raw stdout from the npm run build step | | build-stderr.txt | Raw stderr from the npm run build step |

Security note: Authorization tokens, API keys, and other secrets are automatically redacted from all captured headers and bodies before being written to disk.

Legacy DEBUG environment variable

The DEBUG=* variable is still supported for low-level module-level debug output to the console (Node.js debug module). The --log / MODYO_LOG=1 mechanism described above is the recommended approach for support diagnostics as it writes structured, persistent files.

Session retention

By default the CLI keeps the 20 most recent sessions. Older sessions are automatically purged each time a new session is created. Control this with the MODYO_LOG_KEEP environment variable:

\# Keep only the last 5 sessions
MODYO_LOG_KEEP=5 modyo-cli push --log

\# Keep only the current session (minimum: 1)
MODYO_LOG_KEEP=1 modyo-cli push --log

| Variable | Default | Description | |---|---|---| | MODYO_LOG_KEEP | 20 | Total number of sessions to keep. Non-numeric values fall back to 20; values less than 1 are clamped to 1. |

Using diagnostics in CI/CD

In CI environments the session folder is destroyed with the ephemeral runner after the job ends. To preserve diagnostics, set MODYO_LOG=1 in your workflow and upload the session folder as an artifact on failure.

Additionally, when the CLI detects a CI environment it automatically prints error.txt and meta.json to stderr at the end of a failed command — no artifact upload needed for a quick triage.

GitHub Actions example:

- name: Push widget
  env:
    MODYO_TOKEN: ${{ secrets.MODYO_TOKEN }}
    MODYO_ACCOUNT_URL: ${{ vars.MODYO_ACCOUNT_URL }}
    MODYO_SITE_HOST: ${{ vars.MODYO_SITE_HOST }}
    MODYO_LOG: "1"
  run: modyo-cli push my-widget

- name: Upload diagnostics
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: modyo-diagnostics
    path: .modyo-debug/

The auto-print only triggers when MODYO_LOG=1 (or --log) is active and a CI environment is detected (CI, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, JENKINS_URL, or TF_BUILD). It does not auto-activate logging on its own.

Creating a support bundle

Once you have reproduced the issue with --log, package the session with:

modyo-cli support-bundle

This creates a modyo-debug-<session-id>.zip file in the current directory. Attach this zip to your support ticket or GitHub issue.

\# Package a specific session
modyo-cli support-bundle --session push-20260422-183045-12345

\# Use a custom log directory
modyo-cli support-bundle --log-dir /tmp/my-logs

Reporting a bug

1. Reproduce with logging enabled:

   modyo-cli push --log   \# or: MODYO_LOG=1 modyo-cli push

2. Package the session:

   modyo-cli support-bundle

3. Attach the generated .zip to your GitHub issue or support ticket.

License

Modyo CLI is licensed under the Modyo Software License .