@dg-superapp/cli

Official developer CLI for the DG SuperApp mini-app ecosystem.

Installation

npm install -g @dg-superapp/cli

Important: Configure .npmrc before installing the CLI or any @dg-superapp/* packages:

# 1. Create a GitHub Personal Access Token (PAT) with `read:packages` scope
#    at https://github.com/settings/tokens

# 2. Add to global ~/.npmrc (one-time setup):
echo "@dg-superapp:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT" >> ~/.npmrc

# 3. For project-level .npmrc, add it to .gitignore to avoid leaking your token:
echo ".npmrc" >> .gitignore

Verify installation:

dg --version

Quick Start

# Scaffold a new mini-app
dg miniapp create my-app

# Start development
cd my-app && npm install
dg miniapp dev

# Run tests
dg miniapp test

# Build for production
dg miniapp build

Commands

dg dev --simulator — Browser Cockpit (Phase 58, v2.1.0+)

Adds a full browser-based simulator cockpit on top of dg dev. Pass --simulator to opt in:

dg dev --simulator
dg dev --simulator --cwd ./my-mini-app

The cockpit shell opens at http://127.0.0.1:5200/ and includes:

• Toolbar — platform selector, quick buttons (pause/resume/push/deeplink), scenario picker, QR toggle
• Drawer — Timeline tab (chronological bridge envelope log with filter/export) and State Inspector tab (live bridge-core snapshot)
• QR modal — shows http://<lan-ip>:5300/ for mobile preview on the same network
• Project-local scenarios — drop *.yaml / *.json files in <cwd>/scenarios/ and they appear in the picker

Plain dg dev behaviour is completely unchanged. --simulator is strictly additive.

Full walkthrough: docs/guide/dg-dev-simulator.md

dg dev — Simulated Super-App Host (Phase 57)

Boots two Vite servers and a WebSocket relay so your mini-app runs inside a cross-origin iframe that behaves like a real super-app host shell. Auto-fires lifecycle.init on every iframe load, and exposes ws://127.0.0.1:<port>/__dg/ws for the companion dg trigger CLI to push protocol events into a live session.

# In your mini-app project
dg dev

• Default ports: host shell 5200, mini-app 5300 (auto-increment on conflict).
• Host-shell state (selected platform, recording buffer, init history) survives iframe reloads and platform switches.
• Writes a lockfile at ./.dg/dev-server.json for dg trigger discovery.
• Ctrl+C cleanly stops both Vites and removes the lockfile.

See docs/cli/dg-dev.md for the full flag reference, lockfile schema, boot sequence, and troubleshooting.

dg trigger — Fire protocol events (Phase 57)

Fire-and-forget CLI that discovers a running dg dev via the lockfile and sends a Phase 54 ProtocolMessage envelope over WebSocket with two-step Zod validation. Use a second terminal:

dg trigger pause                                   # lifecycle.pause
dg trigger resume                                  # lifecycle.resume
dg trigger destroy                                 # lifecycle.destroy
dg trigger deeplink myapp://profile/123            # deeplink.open
dg trigger push --title Hello --body World         # push.received + push.tapped
dg trigger platform aba                            # platform.switch
dg trigger init                                    # lifecycle.init
dg trigger scenario lifecycle-basic                # built-in envelope sequence

• Default output is a one-line confirmation with the event id. --json prints the full envelope for scripting (jq-friendly).
• Exits 1 with a grep-stable error when no dg dev is running.
• Scenarios ship as a small in-CLI registry: lifecycle-basic, push-then-deeplink, platform-tour.

See docs/cli/dg-trigger.md for subcommand reference, exit codes, --data JSON handling, and the full list of error strings.

dg miniapp — Mini-App Development

| Command | Description | |---------|-------------| | dg miniapp create <name> | Scaffold a new mini-app project | | dg miniapp dev | Start Vite dev server | | dg miniapp build | Production build with quality gates | | dg miniapp test | Run tests via Vitest | | dg miniapp serve | Start dev server for real device testing (LAN + QR code) | | dg miniapp info | Show mini-app metadata (SDK version, bundle size) |

dg miniapp create

dg miniapp create my-photo-app
dg miniapp create my-app --template vanilla-ts
dg miniapp create my-app --description "My awesome app"

Options:

• -t, --template <template> — Template to use (default: react-vite). Available: react-vite, vanilla-ts
• -d, --description <desc> — App description

The scaffold creates a complete project structure:

my-photo-app/
  ├── src/
  │   ├── main.ts          # App entry point
  │   ├── App.tsx           # Root component (react-vite template)
  │   └── __tests__/        # Test files
  ├── index.html            # HTML entry
  ├── package.json          # Dependencies (bridge-sdk, bridge-mocks, bridge-devtools included)
  ├── vite.config.ts        # Vite configuration
  ├── tsconfig.json         # TypeScript config
  └── vitest.config.ts      # Test configuration

Note: The react-vite template includes @dg-superapp/bridge-sdk, @dg-superapp/bridge-mocks, and @dg-superapp/bridge-devtools as dependencies. You don't need to install them separately. The vanilla-ts template includes only @dg-superapp/bridge-sdk — add mocks and devtools manually if needed.

After scaffolding:

cd my-photo-app
npm install
dg miniapp dev

dg miniapp dev

Starts a Vite dev server for local development.

dg miniapp dev
dg miniapp dev --port 3001

Options:

• -p, --port <port> — Dev server port (default: Vite's default, typically 5173)

Expected output:

Starting dev server with bridge mocks...

  VITE v6.x.x  ready in 500ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

Mock bridge: This command sets VITE_DG_MOCK_BRIDGE=1 in the environment. The scaffolded react-vite template uses this to auto-enable mocks:

// In your main.ts or App.tsx (included in scaffold template)
if (import.meta.env.VITE_DG_MOCK_BRIDGE === '1' || import.meta.env.DEV) {
  const { enableMockBridge } = await import('@dg-superapp/bridge-mocks');
  enableMockBridge({
    profileLevel: '2',    // '0' | '1' | '2' — controls mock profile data
    timingMode: 'realistic', // 'instant' | 'realistic' | 'slow'
  });
}

Requires: Must be run from a mini-app project directory (needs package.json and vite.config.ts).

dg miniapp build

Runs a production build with quality gate checks. Output goes to the dist/ directory (standard Vite output).

dg miniapp build
dg miniapp build --skip-gates
dg miniapp build --size-limit 300

Options:

• --skip-gates — Skip all quality gate checks (build only)
• --size-limit <kb> — Bundle size limit in KB (default: 500)

Quality Gates (run after build):

| Gate | What it checks | Common fix | |------|---------------|------------| | TypeScript | tsc --noEmit — zero type errors | Fix type errors in your code | | Bundle Size | Total .js/.css/.mjs in dist/ ≤ size limit | Reduce imports, use code splitting | | Hash Routing | No BrowserRouter in app files | Use HashRouter instead | | V2 SDK | Has @dg-superapp/bridge-sdk or @dg-superapp/bridge-react in dependencies | Install the SDK: pnpm add @dg-superapp/bridge-sdk. For React projects, @dg-superapp/bridge-react provides hooks (useBridge, useBridgeQuery, usePlatform) — either package satisfies this gate |

Exit code: Exits with code 1 if the build fails OR any quality gate fails. Use in CI pipelines:

dg miniapp build && echo "Ready to deploy" || echo "Build failed"

Output example (passing):

Building for production...
Build completed.

Running quality gates...
  [PASS] TypeScript: No type errors
  [PASS] Bundle Size: 142KB / 500KB
  [PASS] Hash Routing: OK
  [PASS] V2 SDK: @dg-superapp/bridge-sdk found

Results: 4 passed, 0 failed

Output example (failing):

Running quality gates...
  [PASS] TypeScript: No type errors
  [PASS] Bundle Size: 142KB / 500KB
  [FAIL] Hash Routing: Found BrowserRouter in src/App.tsx
  [PASS] V2 SDK: @dg-superapp/bridge-sdk found

Results: 3 passed, 1 failed

Fixing common gate failures:

• Hash Routing: Replace BrowserRouter with HashRouter from react-router-dom — WebView mini-apps require hash-based routing
• Bundle Size: Use code splitting, tree-shaking, or increase limit with --size-limit
• V2 SDK: Install @dg-superapp/bridge-sdk (the V2 SDK package)
• TypeScript: Run npx tsc --noEmit to see type errors

dg miniapp test

Runs tests via Vitest.

dg miniapp test                    # Run all tests once
dg miniapp test --watch            # Run in watch mode
dg miniapp test --coverage         # Collect coverage
dg miniapp test auth               # Filter: only test files matching "auth"
dg miniapp test --watch --coverage # Combine flags

Options:

• -w, --watch — Run in watch mode (re-runs on file changes)
• --coverage — Collect test coverage (writes to coverage/ directory in Vitest's default format)
• [filter] — Positional argument (not --filter) to filter test files by pattern

Note: The CLI delegates to Vitest. Your project's vitest.config.ts controls test setup, coverage format, and output directory. The scaffolded template pre-configures bridge mocks via the @dg-superapp/bridge-testing plugin — mocks are available in all test files without additional setup.

dg miniapp serve

Starts a Vite dev server (with HMR) accessible over your local network, with a QR code for real device testing. Unlike dg miniapp dev which binds to localhost only, serve binds to 0.0.0.0 so devices on your LAN can connect.

dg miniapp serve
dg miniapp serve --port 8080

Options:

• -p, --port <port> — Dev server port (default: 5173)

Output example:

  Device Testing Mode
  ───────────────────────────────────
  Local:   http://localhost:5173
  Network: http://192.168.1.42:5173

  Scan this QR code with DG SuperApp dev mode:

  [QR code]

  Steps:
  1. Open DG SuperApp on your phone
  2. Go to Settings → Developer Mode
  3. Scan the QR code above

dg miniapp info

Shows metadata about your mini-app project.

dg miniapp info

Output example:

Before build:

  my-photo-app v1.0.0

  Bridge SDK:    1.2.0
  React Hooks:   1.1.0
  Built:         No (run dg miniapp build)

After build:

  my-photo-app v1.0.0

  Bridge SDK:    1.2.0
  React Hooks:   1.1.0
  Built:         Yes
  Bundle Size:   142KB

dg bridge — Bridge SDK Utilities

| Command | Description | |---------|-------------| | dg bridge list | List all registered bridge handlers | | dg bridge inspect <handler> | Show detailed handler information | | dg bridge test | Run contract tests against handler mocks |

dg bridge list

dg bridge list                        # List all handlers
dg bridge list --category camera      # Filter by category

Options:

• -c, --category <category> — Filter by handler category (case-insensitive)

Output example:

All bridge handlers (53):

Handler          Category     Description
-------          --------     -----------
capturePhoto     camera       Capture a photo using the device camera
copyToClipboard  clipboard    Copy text to the system clipboard
...

Filter by category: dg bridge list --category <name>
Categories: biometric, camera, clipboard, contacts, data, encryption,
  files, identity, lifecycle, location, navigation, permissions, scanner,
  sharing, sim, ui, web_control

dg bridge inspect

dg bridge inspect capturePhoto
dg bridge inspect userProfile

Shows handler details including category, version, aliases, platform support, and a mock response example.

Output example:

Capture Photo (capturePhoto)

  Category:   camera
  Since:      v1.0.0
  Aliases:    (none)
  Platforms:  ios: full, android: full

  Description:
    Capture a photo using the device camera

  Mock Response Example:
    { "success": true, "data": { "path": "/mock/photo.jpg", ... } }

dg bridge test

Validates that bridge handlers used in your project return valid mock responses.

dg bridge test

What it does:

1. Scans src/ for callBridge('handlerName') calls AND named imports from @dg-superapp/bridge-sdk
2. For each handler found, calls its default mock
3. Validates the mock response against the handler's Zod schema

Both patterns are detected:

// Detected via callBridge() pattern
const result = await callBridge('capturePhoto');

// Also detected via named import
import { capturePhoto, userProfile } from '@dg-superapp/bridge-sdk';

Output example:

Scanning project for bridge handler usage...

Found 3 bridge handler(s): capturePhoto, copyToClipboard, userProfile

Validating mock contracts...

  [PASS] capturePhoto: OK
  [PASS] copyToClipboard: OK
  [PASS] userProfile: OK

Results: 3 passed, 0 failed, 3 total

Exits with code 1 if any handler fails validation. Useful in CI pipelines:

# Example GitHub Actions step
- name: Validate bridge contracts
  run: dg bridge test

dg preview — Bridge Preview (Phone Frame)

| Command | Description | |---------|-------------| | dg preview start | Start bridge-preview server with phone frame | | dg preview open | Open preview in default browser |

dg preview start

Starts a preview server that renders your mini-app inside a phone frame (393x852px) with mock bridge injection.

# 1. Start your mini-app dev server first
dg miniapp dev

# 2. In a separate terminal, start the preview server
dg preview start
dg preview start --port 4000
dg preview start --url http://localhost:3001

Options:

• -p, --port <port> — Preview server port (default: 3000)
• -u, --url <url> — Target mini-app URL to proxy (default: http://localhost:5173)

Important: The preview server proxies your running mini-app. You must start dg miniapp dev (or another dev server) first, then run dg preview start in a separate terminal.

dg preview open

Opens the preview server URL in your default browser. Requires dg preview start to already be running.

dg preview open
dg preview open --port 4000
dg preview open --url http://custom-url.com

Options:

• -p, --port <port> — Preview server port (default: 3000)
• -u, --url <url> — Open a specific URL instead (overrides --port)

dg simulator — Electron Simulator

| Command | Description | |---------|-------------| | dg simulator launch | Launch the DG SuperApp Simulator | | dg simulator load | Load a mini-app into the simulator | | dg simulator status | Show simulator state | | dg simulator screenshot | Capture a screenshot |

All simulator commands support --json for machine-readable output and --port <port> to override auto-discovery.

Prerequisites: Install the DG SuperApp Simulator (Electron app) from your organization's internal releases. Default install locations:

• Windows: %LOCALAPPDATA%\Programs\dg-superapp-simulator\
• macOS: /Applications/DG SuperApp Simulator.app/
• Linux: /usr/local/bin/dg-superapp-simulator

Simulator discovery: The CLI communicates with the simulator via HTTP. The port is auto-discovered from ~/.dg-simulator/api-port (written by the simulator on startup). If the simulator isn't running, you'll see a "Simulator not running" error.

dg simulator launch

dg simulator launch
dg simulator launch --path /custom/path/to/simulator

Options:

• --path <path> — Path to simulator executable
• --json — Output raw JSON

Path resolution order:

1. --path flag
2. DG_SIMULATOR_PATH environment variable
3. Default OS paths (Windows: %LOCALAPPDATA%\Programs\dg-superapp-simulator\, macOS: /Applications/DG SuperApp Simulator.app/, Linux: /usr/local/bin/)

dg simulator load

Load a mini-app into the running simulator.

dg simulator load --url http://localhost:5173
dg simulator load --file ./dist/index.html

Options (one required):

• -u, --url <url> — Load from URL
• -f, --file <path> — Load from local file
• --json — Output raw JSON
• --port <port> — Simulator API port (overrides auto-discovery)

Important: You must specify either --url or --file. Omitting both exits with code 1 and usage examples.

dg simulator status

dg simulator status
dg simulator status --json
dg simulator status --port 9222

Options:

• --json — Output raw JSON
• --port <port> �� Simulator API port (overrides auto-discovery)

Output example:

DG SuperApp Simulator Status
───────────────────────────────────
  App:          My Photo App
  Mode:         url
  State:        ready
  Device:       iPhone 15 Pro (393×852)
  Orientation:  portrait
  Scenario:     default
  Profile:      L2
  Bridge calls: 12

If no mini-app is loaded, shows "No mini-app loaded" for the App field.

dg simulator screenshot

dg simulator screenshot
dg simulator screenshot --output ./screenshots/test.png

Options:

• -o, --output <path> — Save screenshot to file path (e.g., ./screenshots/test.png). Without this flag, the screenshot data is captured in memory but not written to disk — always use --output to save.
• --json — Output raw JSON (includes base64 image data)
• --port <port> — Simulator API port (overrides auto-discovery)

Testing Fidelity Ladder

The CLI supports 5 levels of testing fidelity, each adding realism over the previous:

| Level | Method | Command | What it adds | |-------|--------|---------|-------------| | 1 | Mock browser | dg miniapp dev + enableMockBridge() in code | Fastest iteration — mocked bridge calls in your browser, no native context | | 2 | Phone frame preview | dg preview start | Renders your app inside a phone-sized frame (393x852px) with mock bridge injection — see how it looks on a phone screen | | 3 | Electron simulator | dg simulator launch + dg simulator load | Native desktop app with full bridge stub support — closest to real native callbacks without a phone | | 4 | Real device | dg miniapp serve (scan QR) | Test on your actual phone over LAN — real WebView, real screen size, real touch | | 5 | Auto-registered (stub) | dg miniapp serve --register (prints "coming soon" and exits) | Full production registration (not yet available) |

Simulator installation: The Electron simulator is a separate application. Download the latest version from your organization's internal releases page (ask your team lead for the URL if you don't have access). Install to the default OS path:

• Windows: %LOCALAPPDATA%\Programs\dg-superapp-simulator\
• macOS: /Applications/DG SuperApp Simulator.app/
• Linux: /usr/local/bin/dg-superapp-simulator

You can also set the DG_SIMULATOR_PATH environment variable to point to a custom install location, or use dg simulator launch --path /your/path.

CI / GitHub Actions

To install @dg-superapp/* packages in CI, configure GitHub Packages authentication:

# .github/workflows/ci.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm

      - name: Configure GitHub Packages auth
        run: |
          echo "@dg-superapp:registry=https://npm.pkg.github.com" > .npmrc
          echo "//npm.pkg.github.com/:_authToken=${{ secrets.GITHUB_TOKEN }}" >> .npmrc

      - run: pnpm install --frozen-lockfile
      - run: npm install -g @dg-superapp/cli  # Install CLI globally for dg commands
      - run: dg miniapp build
      - run: dg miniapp test --coverage
      - run: dg bridge test

Note: The built-in GITHUB_TOKEN secret works for GitHub Packages in the same organization. For cross-org access, use a PAT stored as a repository secret.

Troubleshooting

dg: command not found — Install globally: npm install -g @dg-superapp/cli

Not a mini-app project — Run from a directory with both package.json and vite.config.ts

Simulator not running — Launch first with dg simulator launch, or set DG_SIMULATOR_PATH if installed in a non-default location

404 on npm install — Configure .npmrc for GitHub Packages (see Installation above)

dg preview open shows nothing — dg preview start must be running in another terminal first

--coverage output location — Coverage reports are written to coverage/ by default (configurable in vitest.config.ts)