@onexapis/cli

CLI tool for OneX theme development — scaffold, build, validate, and deploy themes using @onexapis/core.

Installation

# Install globally
npm install -g @onexapis/cli

# Or within the monorepo
cd packages/cli
pnpm build
npm install -g

Requires Node.js >= 18.

Quick Start

# 1. Login to OneX platform
onexthm login

# 2. Create a new theme project
onexthm init my-theme
cd my-theme

# 3. Develop with live preview
onexthm dev

# 4. Publish to marketplace (authenticated, secure)
onexthm publish

Theme Developer Flow

onexthm login                  # Authenticate with OneX platform
onexthm init my-store          # Scaffold theme from template (7 sections, 3 pages)
cd my-store
onexthm dev                    # Live preview at localhost:3456
onexthm create:section pricing # Add new section
onexthm validate               # Check structure
onexthm build                  # Compile for production
onexthm publish                # Register → build → upload → scan → publish
onexthm whoami                 # Check logged-in status
onexthm logout                 # End session

Commands

onexthm init [project-name]

Create a new OneX theme project from a template.

| Option | Description | | --------------------------- | -------------------------------------- | | -t, --template <template> | Template to use (default, minimal) | | --no-install | Skip installing dependencies | | --git | Initialize a git repository | | -y, --yes | Skip prompts and use defaults |

onexthm create:section <name> (alias: cs)

Scaffold a new section inside a theme.

| Option | Description | | --------------------------- | -------------------------------------------------- | | -t, --theme <theme> | Target theme | | -c, --category <category> | Section category (headers, content, footers) | | --template <template> | Initial template variant (default, minimal) |

onexthm create:section hero -t my-theme -c heroes
onexthm cs featured-products -t my-store

onexthm create:block <name> (alias: cb)

Scaffold a new block.

| Option | Description | | --------------------- | ----------------------- | | -t, --theme <theme> | Target theme (optional) |

onexthm create:block product-card
onexthm cb testimonial-item -t my-theme

onexthm create:component <name> (alias: cc)

Scaffold a new UI component.

| Option | Description | | ------------------- | --------------------------------------- | | -t, --type <type> | Component type (ui, layout, form) |

onexthm create:component icon-badge
onexthm cc custom-input -t form

onexthm list

List available themes, sections, blocks, and components in the project.

| Option | Description | | --------------------- | -------------------- | | -s, --sections | List sections only | | -b, --blocks | List blocks only | | -c, --components | List components only | | -t, --theme <theme> | Filter by theme |

onexthm validate

Validate theme structure and files.

| Option | Description | | --------------------- | ------------------------------------- | | -t, --theme <theme> | Theme to validate | | -f, --fix | Auto-fix issues (not yet implemented) |

onexthm build

Build a theme for production. Runs type-check, lint, and compilation.

| Option | Description | | --------------------- | ----------------------------------- | | -t, --theme <theme> | Theme to build | | -p, --production | Production build with optimizations | | -w, --watch | Watch mode for development |

Note: The theme's package.json must have type-check and lint scripts for the build to pass. Example:

{ "scripts": { "type-check": "tsc --noEmit", "lint": "eslint src" } }

onexthm package

Compile and package a theme as a distributable zip file.

| Option | Description | | --------------------- | --------------------------------------------- | | -t, --theme <theme> | Theme to package | | -o, --output <dir> | Output directory | | -n, --name <name> | Custom package name | | -m, --minify | Minify compiled output | | --skip-build | Skip compilation, use existing compiled theme |

onexthm deploy

Upload a theme package to the API server.

| Option | Description | | ------------------------- | ---------------------------------------------------- | | -t, --theme <theme> | Theme to deploy | | -p, --package <file> | Specific package file to upload | | --api-url <url> | API server URL (default: http://localhost:3001) | | -k, --api-key <key> | API key for authentication | | -e, --environment <env> | Environment (production, staging, development) |

onexthm upload

Upload compiled theme to S3 as bundle.zip + source.zip.

| Option | Description | | ------------------------- | --------------------------------------------- | | -t, --theme <theme> | Theme to upload | | -b, --bucket <name> | S3 bucket name | | -v, --version <version> | Theme version | | -e, --environment <env> | Environment (staging or production) | | --dry-run | Show what would be uploaded without uploading | | --skip-source | Skip uploading source.zip | | --source-dir <dir> | Source directory path |

# Dry run first
onexthm upload --theme simple --dry-run

# Upload to staging
onexthm upload --theme simple

# Upload to production
onexthm upload --theme simple -e production

# Override bucket
onexthm upload --theme simple --bucket custom-bucket

onexthm download

Download a compiled theme from S3.

| Option | Description | | ------------------------- | -------------------------------------------- | | -t, --theme-id <id> | Theme ID to download | | -v, --version <version> | Theme version (default: latest) | | -b, --bucket <name> | S3 bucket name | | -e, --environment <env> | Environment (staging or production) | | -o, --output <dir> | Output directory (default: ./active-theme) |

onexthm clone <theme-name>

Clone theme source code from S3.

| Option | Description | | ------------------------- | ----------------------------------------- | | -v, --version <version> | Theme version (default: latest) | | -n, --name <name> | New theme name (skips interactive prompt) | | -o, --output <dir> | Output directory | | -b, --bucket <name> | S3 bucket name | | -e, --environment <env> | Environment (staging or production) | | --no-install | Skip running pnpm install after clone |

onexthm clone simple
onexthm clone simple -n my-store
onexthm clone simple -v 1.0.0 -o ./my-clone --no-install

onexthm login

Authenticate with the OneX platform. Stores encrypted JWT token in ~/.onexthm/auth.json.

onexthm login
# Email: [email protected]
# Password: ********
# ✓ Logged in! Token stored securely.

Required before onexthm publish. Token auto-refreshes on expiry.

onexthm logout

Clear stored authentication tokens.

onexthm logout

onexthm whoami

Show current logged-in developer info.

onexthm whoami
# Email: [email protected]
# Company: 9e61d187-...
# Status: ✓ Active

onexthm publish

Build, scan, and publish theme to the marketplace. Requires login.

onexthm publish
# ✓ Logged in as [email protected]
# Publishing my-store v1.0.0...
#   1. Registering theme...     ✓
#   2. Building...              ✓ (54 KB)
#   3. Getting upload URL...    ✓
#   4. Uploading bundle...      ✓
#   5. Uploading source...      ✓
#   6. Scanning & publishing... ✓ Published!

| Option | Description | | -------------------- | -------------------- | | -t, --theme <path> | Theme directory path |

Security features:

• Ownership check — only theme owner can publish updates
• Presigned URLs — no AWS credentials needed
• Security scan — blocks eval(), XSS, crypto mining, data exfiltration
• Audit logging — every publish is logged with developer identity

onexthm config (Legacy)

Interactive setup for S3 credentials. Not needed for onexthm publish — use onexthm login instead.

onexthm config

| Key | Description | Required | | ------------------------ | --------------------- | -------- | | AWS_ACCESS_KEY_ID | AWS Access Key ID | Yes | | AWS_SECRET_ACCESS_KEY | AWS Secret Access Key | Yes | | AWS_REGION | AWS Region | No | | BUCKET_NAME | S3 Bucket Name | No | | NEXT_PUBLIC_API_URL | API URL | No | | NEXT_PUBLIC_COMPANY_ID | Company ID | No |

Run this once after installing the CLI. Re-run anytime to update values.

S3 Configuration

The upload, download, and clone commands use S3 for storage.

Recommended: use onexthm config

# One-time setup — saves credentials to ~/.onexthm/.env
onexthm config

After running onexthm config, all S3 commands work from any directory:

onexthm clone simple             # works anywhere
onexthm upload --theme simple    # picks up config automatically
onexthm download -t simple       # same

Manual configuration

The CLI loads env files in this order (first found wins):

1. Project-level: .env.local and .env at the project root
2. Global: ~/.onexthm/.env (set by onexthm config, or create manually)

Adapter Modes

# MinIO (set ADAPTER_MODE=vps)
ADAPTER_MODE=vps
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin

# LocalStack (set ADAPTER_MODE=local)
ADAPTER_MODE=local

Bucket Name Resolution

Priority order:

1. --bucket CLI flag
2. BUCKET_NAME environment variable
3. Default: onex-themes-staging or onex-themes-prod (based on --environment)

Theme Structure

Themes live in the themes/ directory at the project root:

themes/
  my-theme/
    theme.config.ts        # Theme metadata (name, version, description)
    bundle-entry.ts        # Build entry point
    index.ts               # Theme exports
    sections-registry.ts   # Section registry
    theme.layout.ts        # Layout definition
    package.json
    tsconfig.json
    sections/              # Section components
      hero/
      features/
      ...
    pages/                 # Page configurations
      home.ts
      about.ts
      ...

Project Detection

The CLI detects a OneX project by looking for a themes/ directory (or legacy src/themes/) from the project root. Within themes, it recognizes any directory containing theme.config.ts, bundle-entry.ts, or manifest.ts as a valid theme.

Architecture

packages/cli/
├── src/
│   ├── cli.ts                  # Main CLI entry point
│   ├── index.ts                # Programmatic API exports
│   ├── commands/
│   │   ├── init.ts             # Theme initialization
│   │   ├── create-section.ts   # Section scaffolding
│   │   ├── create-block.ts     # Block scaffolding
│   │   ├── create-component.ts # Component scaffolding
│   │   ├── list.ts             # Project inventory
│   │   ├── validate.ts         # Theme validation
│   │   ├── build.ts            # Theme build
│   │   ├── package.ts          # Theme packaging
│   │   ├── deploy.ts           # Deploy to API server
│   │   ├── upload.ts           # Upload to S3
│   │   ├── download.ts         # Download from S3
│   │   ├── clone.ts            # Clone source from S3
│   │   └── config.ts           # CLI credential setup
│   └── utils/
│       ├── logger.ts           # Console output utilities
│       ├── file-helpers.ts     # File operations & project detection
│       └── validators.ts       # Input validation
├── bin/
│   └── onexthm.js                 # Executable entry point
├── templates/                  # Scaffolding templates
└── package.json

Development

cd packages/cli

# Build
pnpm build

# Watch mode
pnpm dev

# Type check
pnpm type-check

# Lint
pnpm lint

# Install globally after building
npm install -g . --force

License

MIT