CLI Commands Reference

The BoardAPI CLI provides tools for developing, testing, building, and publishing external components.

Installation

bash

npm install -g @boardapi/cli
# or use with npx
npx @boardapi/cli <command>

Commands

`boardapi init`

Initialize a new component in the current directory.

Usage:

bash

boardapi init [--template <template>] [--name <name>]

Options:

Option	Description	Default
`--template`	Framework template: `vanilla`, `vue`, `react`	Interactive prompt
`--name`	Component name (lowercase, alphanumeric, hyphens)	Directory name

What it creates:

manifest.json - Component configuration
package.json - Node dependencies
tsconfig.json - TypeScript configuration
src/ - Source code directory
Template-specific starter files

Example:

bash

# Interactive mode
boardapi init

# Specify template and name
boardapi init --template vue --name my-timer

`boardapi dev`

Start the development server with live reload and simulator.

Usage:

bash

boardapi dev [options]

Options:

Option	Description	Default
`--port`	Component server port	`3000`
`--simulator-port`	Simulator UI port	`3001`
`--open`	Open browser automatically	`false`

Features:

Hot reload on file changes
Storage inspector
Event log viewer
WebSocket connection for real-time updates

Example:

bash

# Default ports
npm run dev

# Custom ports
boardapi dev --port 4000 --simulator-port 4001

# Open browser automatically
boardapi dev --open

URLs:

Component: http://localhost:3000
Simulator: http://localhost:3001

`boardapi build`

Build the component for production.

Usage:

bash

boardapi build [options]

Options:

Option	Description	Default
`--minify`	Minify JavaScript output	`true`
`--sourcemap`	Generate source maps	`false`
`--output`	Output directory	`dist`

What it does:

Compiles TypeScript to JavaScript
Bundles dependencies
Processes CSS
Copies assets
Creates .zip archive for publishing

Output:

dist/
├── component.js       # Bundled JavaScript
├── styles.css         # Processed styles
├── manifest.json      # Component manifest
└── assets/            # Static assets

my-component-1.0.0.zip # Ready for publishing

Example:

bash

# Standard build
npm run build

# Development build with source maps
boardapi build --sourcemap --no-minify

# Custom output directory
boardapi build --output build

`boardapi validate`

Validate component structure and manifest.

Usage:

bash

boardapi validate [options]

Options:

Option	Description	Default
`--manifest`	Path to manifest file	`manifest.json`
`--strict`	Enable strict validation	`false`

Validation checks:

Manifest schema compliance
Required files exist
Entry points are valid
Props schema is correct
Storage schema is valid
Asset paths exist
Version format

Example:

bash

# Standard validation
boardapi validate

# Strict mode (warnings as errors)
boardapi validate --strict

# Custom manifest path
boardapi validate --manifest config/manifest.json

`boardapi publish`

Publish the component to BoardAPI registry.

Usage:

bash

boardapi publish [options]

Options:

Option	Description	Default
`--tag`	Publish tag: `latest`, `beta`, `alpha`	`latest`
`--dry-run`	Test without actually publishing	`true`

Prerequisites:

Component must be built (boardapi build)
Validation must pass
Must be logged in (boardapi login)

Example:

bash

# Test publish
boardapi publish --dry-run

# Publish to latest
boardapi publish --no-dry-run

# Publish beta version
boardapi publish --tag beta --no-dry-run

`boardapi logs`

View component logs during development and production.

Usage:

bash

boardapi logs [options]

Options:

Option	Description	Default
`--live`	Watch logs in real-time	`false`
`--level`	Filter by level: `debug`, `info`, `warn`, `error`	All levels
`--filter`	Filter by component ID or message	-
`--tail`	Number of recent entries to show	`100`

Example:

bash

# View last 100 logs
boardapi logs

# Watch live
boardapi logs --live

# Show only errors
boardapi logs --level error

# Filter by component ID
boardapi logs --filter comp-abc123

# Tail last 50 entries
boardapi logs --tail 50

`boardapi migrate`

Migrate component data between versions.

Usage:

bash

boardapi migrate [options]

Options:

Option	Description
`--from`	Source version
`--to`	Target version
`--check`	Check if migration is needed
`--history`	Show migration history

Migration script format:

Create migrations/<from>-to-<to>.ts:

typescript

export default {
  from: '1.0.0',
  to: '2.0.0',
  migrate: (data: any) => {
    // Transform data structure
    return {
      ...data,
      // Add new fields
      newField: 'default',
      // Rename fields
      renamedField: data.oldField,
    }
  }
}

Example:

bash

# Check migration status
boardapi migrate --check

# Run migration
boardapi migrate --from 1.0.0 --to 2.0.0

# View migration history
boardapi migrate --history

`boardapi version`

Bump component version.

Usage:

bash

boardapi version <patch|minor|major>

Version bumping:

patch: 1.0.0 → 1.0.1 (bug fixes)
minor: 1.0.0 → 1.1.0 (new features)
major: 1.0.0 → 2.0.0 (breaking changes)

Example:

bash

# Patch release
boardapi version patch

# Minor release
boardapi version minor

# Major release
boardapi version major

Global Options

Available for all commands:

Option	Description
`--help`, `-h`	Show help
`--version`, `-v`	Show CLI version
`--verbose`	Enable verbose logging
`--quiet`	Suppress non-essential output

Common Workflows

Development Workflow

bash

# 1. Initialize component
boardapi init --template vue --name my-component

# 2. Install dependencies
npm install

# 3. Start dev server
npm run dev

# 4. Build when ready
npm run build

# 5. Validate
boardapi validate

# 6. Publish
boardapi publish

Testing Before Publishing

bash

# 1. Build
npm run build

# 2. Strict validation
boardapi validate --strict

# 3. Dry-run publish
boardapi publish --dry-run

# 4. Check output
ls -lh *.zip

Debugging

bash

# Watch logs during development
boardapi logs --live --level debug

# Check specific component
boardapi logs --filter comp-abc123 --level error

# View recent errors
boardapi logs --level error --tail 20

Environment Variables

Variable	Description	Default
`BOARDAPI_API_URL`	API endpoint	`https://api.boardapi.io`
`BOARDAPI_TOKEN`	Authentication token	-
`NODE_ENV`	Environment mode	`development`

Example:

bash

# Use staging API
BOARDAPI_API_URL=https://staging-api.boardapi.io boardapi publish

# Set auth token
export BOARDAPI_TOKEN=your-token-here
boardapi publish

Troubleshooting

Build Fails

bash

# Check manifest is valid
boardapi validate

# Try clean build
rm -rf dist node_modules
npm install
npm run build

Publish Fails

bash

# Verify build exists
ls dist/

# Check validation
boardapi validate --strict

# Test with dry-run
boardapi publish --dry-run

Dev Server Won't Start

bash

# Check port is available
lsof -i:3000

# Use different port
boardapi dev --port 4000

CLI Commands Reference ​

Installation ​

Commands ​

boardapi init ​

boardapi dev ​

boardapi build ​

boardapi validate ​

boardapi publish ​

boardapi logs ​

boardapi migrate ​

boardapi version ​

Global Options ​

Common Workflows ​

Development Workflow ​

Testing Before Publishing ​

Debugging ​

Environment Variables ​

Troubleshooting ​

Build Fails ​

Publish Fails ​

Dev Server Won't Start ​

Next Steps ​

CLI Commands Reference

Installation

Commands

`boardapi init`

`boardapi dev`

`boardapi build`

`boardapi validate`

`boardapi publish`

`boardapi logs`

`boardapi migrate`

`boardapi version`

Global Options

Common Workflows

Development Workflow

Testing Before Publishing

Debugging

Environment Variables

Troubleshooting

Build Fails

Publish Fails

Dev Server Won't Start

Next Steps