CLI Reference

The @selorax/cli package is a command-line tool for building, testing, and deploying extensions to the SeloraX platform. It handles authentication, esbuild bundling, CDN upload, config validation, and atomic deployment.

Installation

npm install -g @selorax/cli

Requires Node.js 18 or later.

After installation, the selorax command is available globally:

selorax --version
selorax --help

Authentication

selorax auth:login

Authenticate with the SeloraX platform. Credentials are stored locally in ~/.config/selorax-cli/config.json.

selorax auth:login \
  --client-id sx_app_abc123 \
  --client-secret sx_secret_xyz789 \
  --store-id 22

Alias: selorax login

selorax auth:logout

Remove stored credentials from the local machine.

selorax auth:logout

Alias: selorax logout

selorax auth:status

Display current authentication state — client ID, store ID, and API URL.

selorax auth:status

Alias: selorax whoami

App Commands

selorax app:info

Show information about the current app and its extensions from selorax.config.json.

selorax app:info
selorax app:info -c path/to/selorax.config.json

Alias: selorax info

selorax app:dev

Start a development server that watches for changes and auto-deploys extensions.

selorax app:dev
selorax app:dev --port 4000
selorax app:dev --no-open

Alias: selorax dev

What dev mode does

1. JSON extensions are deployed immediately to the platform via the API.
2. Sandbox extensions are built with esbuild in watch mode (with source maps, no minification).
3. A local HTTP server starts on the specified port, serving built sandbox bundles.
4. An SSE (Server-Sent Events) endpoint at /__reload sends reload events when bundles are rebuilt.
5. Changes to selorax.config.json trigger an automatic re-deploy of JSON extensions.

The dev server serves files with CORS headers (Access-Control-Allow-Origin: *) so sandbox iframes can load bundles from 127.0.0.1.

  SeloraX Dev Server

  JSON extensions:    2
  Sandbox extensions: 1

  Dev server: http://127.0.0.1:3456
  Serving: /Users/dev/my-app/dist

  my-sandbox-ext: http://127.0.0.1:3456/my-sandbox-ext.js
  Live reload: connect to http://127.0.0.1:3456/__reload (SSE)

  Dev mode active. Press Ctrl+C to stop.

selorax app:deploy

Deploy all extensions defined in the config file. This is an atomic operation — all extensions are replaced at once.

selorax app:deploy
selorax app:deploy --force
selorax app:deploy --dry-run

Alias: selorax deploy

Deploy flow

1. Build — Sandbox extensions with an entry field are built with esbuild (bundled, minified, IIFE, ES2020 target).
2. Upload — If S3/R2 config is present in the config file, bundles are uploaded to CDN and the sandbox_url is set automatically.
3. Preview — The CLI shows a summary of all extensions to be deployed.
4. Confirm — Unless --force is passed, the CLI asks for confirmation.
5. Deploy — The full extension set is sent to POST /api/apps/extensions/app/deploy. The platform validates all extensions, creates a version snapshot, and registers them for all active installations.

The --dry-run flag runs steps 1-3 but does not send anything to the platform. Use it to verify your config and builds before deploying.

selorax app:versions

List the extension version history for your app.

selorax app:versions

Alias: selorax versions

Output shows version number, extension count, and deployment timestamp. The platform retains up to 25 versions.

selorax app:rollback

Rollback extensions to a previous version.

selorax app:rollback -v 3

Alias: selorax rollback

The rollback restores the extension set from the version snapshot and re-registers it for all active installations. A new version snapshot is not created by a rollback — the version history is preserved as-is.

Extension Commands

selorax extension:build

Build sandbox extensions with esbuild without deploying.

selorax extension:build
selorax extension:build -c custom-config.json

Alias: selorax build

Produces bundled, minified IIFE files in the outDir directory (default: dist/). Each sandbox extension with an entry field gets a corresponding <extension_id>.js output file.

selorax extension:validate

Validate extension config and UI trees without deploying. Checks:

• Required fields (extension_id, target, title)
• Valid target values
• Valid component types in JSON UI trees
• Valid action types
• Tree depth limits
• Mode-specific requirements (e.g., sandbox_url for sandbox mode, ui for JSON mode)

selorax extension:validate

Alias: selorax validate

Generate Commands

selorax generate:extension

Scaffold a new extension with boilerplate files.

selorax generate:extension
selorax generate:extension -t order.detail.block -m json -n "Fraud Check"

Alias: selorax generate

When run without options, the CLI prompts interactively for the target, mode, and name.

selorax generate:config

Generate a selorax.config.json for an existing project. Detects existing extension files and populates the config accordingly.

selorax generate:config

Configuration File

The selorax.config.json file is the central configuration for your extensions project. It lives in the root of your project directory.

Schema

{
  "appId": "sx_app_abc123",
  "outDir": "dist",
  "s3": {
    "endpoint": "https://abc.r2.cloudflarestorage.com",
    "bucket": "pap",
    "accessKey": "...",
    "secretKey": "...",
    "publicUrl": "https://cdn.myapp.com"
  },
  "extensions": [
    {
      "extension_id": "order-fraud-check",
      "target": "order.detail.block",
      "title": "Fraud Risk Score",
      "description": "Shows fraud risk assessment for each order",
      "mode": "json",
      "ui": {
        "type": "Card",
        "props": { "title": "Fraud Check" },
        "children": [{ "type": "Text", "props": { "content": "Risk: Low" } }]
      },
      "initial_state": { "loaded": false },
      "load_action": {
        "type": "call_backend",
        "url": "https://myapp.com/api/fraud",
        "method": "POST"
      },
      "sort_order": 0,
      "settings_schema": []
    },
    {
      "extension_id": "product-tag-manager",
      "target": "product.detail.block",
      "title": "Tag Manager",
      "mode": "sandbox",
      "entry": "extensions/tag-manager/index.js",
      "sandbox_url": "https://cdn.myapp.com/extensions/product-tag-manager.js",
      "settings_schema": [
        {
          "key": "max_tags",
          "label": "Maximum Tags",
          "type": "number",
          "default": 10
        }
      ]
    }
  ]
}

Top-Level Fields

S3 Configuration

Extension Fields

Example Workflow

1. Initialize

mkdir my-selorax-app && cd my-selorax-app
npm init -y
npm install @selorax/ui
npm install -g @selorax/cli
selorax auth:login --client-id sx_app_... --client-secret sx_secret_... --store-id 22
selorax generate:config

2. Create an extension

selorax generate:extension -t order.detail.block -m json -n "Order Notes"

Edit the generated extension in selorax.config.json.

3. Develop

selorax dev

Make changes to the config. JSON extensions are re-deployed on save. Sandbox extensions are rebuilt on file change.

4. Validate

selorax validate

5. Deploy

selorax deploy --dry-run    # Preview first
selorax deploy              # Deploy for real

6. Manage versions

selorax versions            # List version history
selorax rollback -v 2       # Rollback if needed

What's Next

• Extension Platform Overview — Architecture and concepts
• JSON Extensions — Build declarative UI trees
• Sandbox Extensions — Build with full JavaScript control
• Merchant Settings — Define configurable settings