@qt-test/apex-cli

Command-line interface for APEX mini-app development.

Installation

npm install -g @qt-test/apex-cli

Or use with npx:

npx @qt-test/apex-cli create my-app

Quick Start

# Create a new project
apex create my-app

# Navigate to project
cd my-app

# Start development server
apex dev

# Build for production
apex build

# Publish to APEX store
apex login
apex publish

Commands

Project Commands

apex create [name]

Create a new APEX mini-app project.

apex create my-app
apex create my-app --template typescript
apex create my-app --skip-install

Options:

• -t, --template <template> - Template to use (default: "default")
• --typescript - Use TypeScript
• --skip-install - Skip npm install

apex dev

Start development server with hot reload.

apex dev
apex dev --port 3001
apex dev --qr

Options:

• -p, --port <port> - Server port (default: 3000)
• -H, --host <host> - Server host (default: 0.0.0.0)
• --no-open - Don't open browser
• --qr - Show QR code for mobile preview

apex build

Build mini-app for production.

apex build
apex build --output dist
apex build --package --sign ./keys/signing-key.pem

Options:

• -o, --output <dir> - Output directory (default: "dist")
• --analyze - Analyze bundle size
• --no-minify - Disable minification
• --sourcemap - Generate source maps
• --package - Create .map package
• --sign <key> - Sign package with key

apex preview

Preview built app on connected device.

apex preview
apex preview --device ios

Options:

• -d, --device <device> - Target device (ios/android)

apex publish

Publish mini-app to APEX store.

apex publish
apex publish --env prod
apex publish --notes "Bug fixes and improvements"

Options:

• --env <env> - Target environment (staging/prod)
• --key <path> - Signing key path
• --cert <path> - Certificate path
• --notes <notes> - Release notes
• --skip-confirmation - Skip confirmation prompt

Code Generation

apex generate page <name>

Generate a new page.

apex generate page settings
apex generate page user/profile
apex g p payment --title "Make Payment"

Options:

• --title <title> - Navigation bar title
• --tabs - Add to tab bar

apex generate component <name>

Generate a new component.

apex generate component button
apex generate component ui/card
apex g c input --props "value,placeholder,disabled"

Options:

• --props <props> - Comma-separated prop names

Authentication

apex login

Log in to APEX developer platform.

apex login
apex login --api-key apex_xxx
apex login --env prod

Options:

• --api-key <key> - Use API key instead of browser auth
• --env <env> - Target environment (staging/prod)
• --email <email> - Email address

apex logout

Log out from APEX developer platform.

apex logout
apex logout --all

apex whoami

Show current logged-in user.

apex whoami

Key Management

apex keys generate

Generate a new signing key pair.

apex keys generate
apex keys generate --name production
apex keys generate --bits 4096

Options:

• -o, --output <dir> - Output directory (default: .apex)
• --name <name> - Key name (default: signing-key)
• --bits <bits> - Key size in bits (default: 2048)

apex keys list

List registered certificates.

apex keys list

apex keys register [path]

Register a certificate with APEX.

apex keys register
apex keys register ./keys/signing-key.pub

apex keys revoke <id>

Revoke a certificate.

apex keys revoke cert_abc123

Diagnostics

apex info

Display project and environment information.

apex info
apex info --json

apex doctor

Check project setup and diagnose issues.

apex doctor

apex inspect <file>

Inspect a .map package file.

apex inspect ./dist/my-app-1.0.0.map
apex inspect package.map --json

Other Commands

apex upgrade

Upgrade CLI to latest version.

apex upgrade
apex upgrade --check

Configuration

app.json

The main configuration file for your mini-app:

{
  "appId": "com.example.myapp",
  "name": "My App",
  "version": "1.0.0",
  "description": "An amazing mini-app",
  "entryPage": "pages/index/index",
  "pages": [
    "pages/index/index",
    "pages/profile/profile"
  ],
  "tabBar": {
    "color": "#8c8c8c",
    "selectedColor": "#1890ff",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "Home",
        "iconPath": "assets/icons/home.png",
        "selectedIconPath": "assets/icons/home-active.png"
      }
    ]
  },
  "window": {
    "navigationBarTitleText": "My App",
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#f8f8f8"
  },
  "permissions": [
    "network",
    "storage"
  ]
}

Page Configuration

Each page can have its own configuration in page.json:

{
  "navigationBarTitleText": "Page Title",
  "navigationBarBackgroundColor": "#1890ff",
  "navigationBarTextStyle": "white",
  "enablePullDownRefresh": true,
  "usingComponents": {
    "my-button": "/components/button/button"
  }
}

Project Structure

my-app/
├── app.json              # App configuration
├── app.js                # App entry point
├── app.acss              # Global styles
├── pages/
│   └── index/
│       ├── index.axml    # Page template
│       ├── index.acss    # Page styles
│       ├── index.js      # Page logic
│       └── index.json    # Page config
├── components/
│   └── button/
│       ├── button.axml
│       ├── button.acss
│       ├── button.js
│       └── button.json
├── assets/
│   └── icons/
└── package.json

Environment Variables

• APEX_TOKEN - API token for CI/CD
• APEX_SIGNING_KEY - Path to signing key
• APEX_ENV - Target environment (staging/prod)

Programmatic API

The CLI can also be used programmatically:

import { createApp, buildApp, devServer } from '@qt-test/apex-cli';

// Create a new project
await createApp('my-app', { template: 'typescript' });

// Build for production
await buildApp({ output: 'dist', minify: true });

// Start dev server
const server = await devServer({ port: 3000 });
server.onConnect((client) => {
  console.log('Client connected:', client.id);
});

Troubleshooting

Common Issues

"app.json not found"

• Make sure you're in the project directory
• Run apex create to start a new project

"Signing key not found"

• Generate keys with apex keys generate
• Or specify path with --key

"Authentication required"

• Run apex login to authenticate

"Build failed"

• Run apex doctor to diagnose issues
• Check for syntax errors in your code

Getting Help

• Documentation: https://docs.apex.interswitch.io
• GitHub Issues: https://github.com/nicksix/apex-platform/issues
• Discord: https://discord.gg/apex-dev

License

MIT