npm package: @qt-test/apex-cli
Description: CLI tools for APEX mini-app development
Author: Interswitch Group
Latest version: 1.1.0

# @qt-test/apex-cli

Command-line interface for APEX mini-app development.

## Installation

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

Or use with npx:

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

## Quick Start

```bash
# 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.

```bash
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.

```bash
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.

```bash
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.

```bash
apex preview
apex preview --device ios
```

Options:
- `-d, --device <device>` - Target device (ios/android)

#### `apex publish`

Publish mini-app to APEX store.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
apex logout
apex logout --all
```

#### `apex whoami`

Show current logged-in user.

```bash
apex whoami
```

### Key Management

#### `apex keys generate`

Generate a new signing key pair.

```bash
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.

```bash
apex keys list
```

#### `apex keys register [path]`

Register a certificate with APEX.

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

#### `apex keys revoke <id>`

Revoke a certificate.

```bash
apex keys revoke cert_abc123
```

### Diagnostics

#### `apex info`

Display project and environment information.

```bash
apex info
apex info --json
```

#### `apex doctor`

Check project setup and diagnose issues.

```bash
apex doctor
```

#### `apex inspect <file>`

Inspect a .map package file.

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

### Other Commands

#### `apex upgrade`

Upgrade CLI to latest version.

```bash
apex upgrade
apex upgrade --check
```

## Configuration

### app.json

The main configuration file for your mini-app:

```json
{
  "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`:

```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:

```javascript
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