CommercePOS Plugin CLI

A command-line tool for creating and building plugins for CommercePOS. Build plugins using HTML, CSS, and JavaScript that integrate seamlessly with the POS app via WebView.

Installation

From npm (Recommended)

# Install globally
npm install -g cpos-plugin-cli

# Verify installation
cpos-plugin --version

Using npx (No Installation)

# Run without installing
npx cpos-plugin-cli create my-plugin

From GitHub Packages (Enterprise)

# Install from GitHub Packages
npm install -g @withcommmerce/pos-cli --registry=https://npm.pkg.github.com

From Source

# Clone the repository
git clone https://github.com/withcommmerce/commmerce-pos-cli.git
cd commmerce-pos-cli

# Install dependencies
npm install

# Link globally
npm link

Quick Start

# Create a new plugin
cpos-plugin create my-awesome-plugin

# Navigate to plugin directory
cd my-awesome-plugin

# Start development server
cpos-plugin serve

# Build for production
cpos-plugin build

# Package for distribution
cpos-plugin package

Commands

`cpos-plugin create <plugin-name>`

Creates a new plugin project with all necessary files.

Options:

Option	Description	Default
`-t, --template <template>`	Template to use (basic, payment, report)	`basic`
`-d, --directory <dir>`	Directory to create plugin in	`.`

Examples:

# Create basic plugin
cpos-plugin create my-plugin

# Create payment integration plugin
cpos-plugin create razorpay-gateway --template payment

# Create custom report plugin
cpos-plugin create sales-analytics --template report

# Create in specific directory
cpos-plugin create my-plugin --directory ./plugins

Templates:

Template	Description	Use Case
`basic`	Simple plugin structure	General purpose plugins
`payment`	Payment gateway integration	Razorpay, Stripe, PayTM, etc.
`report`	Custom reporting	Sales reports, analytics

`cpos-plugin serve`

Starts a development server with hot reload.

Options:

Option	Description	Default
`-p, --port <port>`	Port to run server on	`3000`
`--host <host>`	Host to bind to	`localhost`

Examples:

# Start on default port
cpos-plugin serve

# Start on custom port
cpos-plugin serve --port 8080

# Bind to all interfaces
cpos-plugin serve --host 0.0.0.0

Features:

Auto-refresh on file changes
Live reload in browser
Development mode mock data

`cpos-plugin build`

Builds the plugin for production.

Options:

Option	Description	Default
`-o, --output <dir>`	Output directory	`dist`
`--minify`	Minify output files	`true`

Examples:

# Build with defaults
cpos-plugin build

# Build to custom directory
cpos-plugin build --output ./release

# Build without minification
cpos-plugin build --minify false

Build process:

Cleans output directory
Processes and minifies HTML
Processes and minifies CSS
Processes and minifies JavaScript
Copies assets
Creates production manifest

`cpos-plugin package`

Packages the plugin as a .cposplugin file for distribution.

Options:

Option	Description	Default
`-o, --output <file>`	Output file name	`<plugin-id>-<version>.cposplugin`

Examples:

# Package with auto-generated name
cpos-plugin package

# Package with custom name
cpos-plugin package --output my-plugin-v1.cposplugin

Output files:

<plugin-name>-<version>.cposplugin - Plugin package (ZIP)
<plugin-name>-<version>.json - Package metadata

Plugin Structure

my-plugin/
├── index.html          # Main entry point
├── styles.css          # Plugin styles
├── main.js             # Main JavaScript
├── manifest.json       # Plugin configuration
├── README.md           # Plugin documentation
├── assets/
│   ├── images/         # Image files
│   └── icons/          # Plugin icons
└── lib/
    ├── pos-sdk.js      # POS SDK bridge
    └── pos-ui.css      # POS UI components

Manifest Configuration

The manifest.json file configures your plugin:

{
  "name": "My Plugin",
  "id": "my-plugin",
  "version": "1.0.0",
  "description": "A great plugin for CommercePOS",
  "author": "Your Name",
  "email": "your@email.com",
  "homepage": "https://yoursite.com",
  "license": "MIT",
  "minPosVersion": "1.0.0",
  "entryPoint": "index.html",
  "icon": "assets/icons/plugin-icon.png",
  "category": "utility",
  "permissions": [
    "orders",
    "products",
    "payments"
  ],
  "settings": [
    {
      "key": "apiKey",
      "label": "API Key",
      "type": "password",
      "required": true
    }
  ]
}

Available Permissions:

Permission	Description
`orders`	Access and manage orders
`products`	Access products and inventory
`customers`	Access customer data
`payments`	Process payments and refunds
`reports`	Generate and view reports
`settings`	Modify POS settings
`staff`	Access staff information
`printer`	Use receipt printer
`cashDrawer`	Control cash drawer
`notifications`	Show notifications
`storage`	Store data locally
`network`	Make external requests

Categories:

payment - Payment integrations
report - Reports and analytics
integration - Third-party integrations
utility - Utility tools
other - Other plugins

POS SDK

The POS SDK (lib/pos-sdk.js) provides communication between your plugin and CommercePOS.

Initialization

// Wait for SDK to be ready
await POS_SDK.ready();

// Check if connected
if (POS_SDK._ready) {
  console.log('Connected to POS!');
}

Orders & Cart

// Get current order
const order = await POS_SDK.getCurrentOrder();

// Get shopping cart
const cart = await POS_SDK.getCart();

// Add item to cart
await POS_SDK.addToCart({
  productId: 'PROD-001',
  quantity: 2,
  price: 99.99
});

// Remove item from cart
await POS_SDK.removeFromCart('item-id');

// Update quantity
await POS_SDK.updateCartItemQuantity('item-id', 5);

Products

// Get all products
const products = await POS_SDK.getProducts();

// Get products with filters
const filtered = await POS_SDK.getProducts({
  category: 'electronics',
  limit: 50,
  offset: 0
});

// Search products
const results = await POS_SDK.searchProducts('laptop');

// Get categories
const categories = await POS_SDK.getCategories();

Customers

// Get current customer
const customer = await POS_SDK.getCustomer();

// Set customer for order
await POS_SDK.setCustomer({
  id: 'CUST-001',
  name: 'John Doe',
  phone: '+91 9876543210'
});

Payments

// Process payment
const result = await POS_SDK.processPayment(1500.00, {
  method: 'card',
  orderId: 'ORD-001'
});

if (result.success) {
  console.log('Payment successful:', result.transactionId);
}

Notifications

// Show toast notification
POS_SDK.showToast({
  message: 'Order saved successfully!',
  type: 'success',  // success, error, warning, info
  duration: 3000
});

// Show dialog
const result = await POS_SDK.showDialog({
  title: 'Confirm Action',
  message: 'Are you sure you want to proceed?',
  buttons: ['Cancel', 'Confirm']
});

Hardware

// Print receipt
await POS_SDK.printReceipt({
  orderId: 'ORD-001',
  items: [...],
  total: 1500.00
});

// Open cash drawer
await POS_SDK.openCashDrawer();

Navigation

// Navigate to POS screen
await POS_SDK.navigateTo('orders', { filter: 'pending' });

// Close plugin
await POS_SDK.close();

Settings

// Get plugin settings
const settings = await POS_SDK.getSettings();

// Save settings
await POS_SDK.saveSettings({
  apiKey: 'xxx-xxx-xxx',
  enabled: true
});

Events

// Listen for order updates
POS_SDK.on('orderUpdated', (order) => {
  console.log('Order updated:', order);
  updateUI(order);
});

// Listen for cart changes
POS_SDK.on('cartChanged', (cart) => {
  console.log('Cart changed:', cart);
});

// Listen for customer changes
POS_SDK.on('customerChanged', (customer) => {
  console.log('Customer changed:', customer);
});

// Remove listener
POS_SDK.off('orderUpdated', myHandler);

HTTP Requests

// Make HTTP request via POS proxy
const response = await POS_SDK.httpRequest({
  url: 'https://api.example.com/data',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ key: 'value' })
});

Store & Staff Info

// Get store information
const store = await POS_SDK.getStoreInfo();

// Get current staff info
const staff = await POS_SDK.getStaffInfo();

Analytics

// Log custom event
await POS_SDK.logEvent('button_clicked', {
  button: 'checkout',
  value: 1500
});

POS UI Components

Use the POS UI library (lib/pos-ui.css) to match CommercePOS design.

Cards

<div class="pos-card">
  <h2 class="pos-card-title">Card Title</h2>
  <p class="pos-text">Card content goes here.</p>
</div>

<div class="pos-card pos-card-success">
  <h3 class="pos-card-subtitle">Success Card</h3>
</div>

Buttons

<button class="pos-btn pos-btn-primary">Primary</button>
<button class="pos-btn pos-btn-secondary">Secondary</button>
<button class="pos-btn pos-btn-success">Success</button>
<button class="pos-btn pos-btn-danger">Danger</button>
<button class="pos-btn pos-btn-outline">Outline</button>

<!-- Sizes -->
<button class="pos-btn pos-btn-primary pos-btn-sm">Small</button>
<button class="pos-btn pos-btn-primary pos-btn-lg">Large</button>
<button class="pos-btn pos-btn-primary pos-btn-block">Full Width</button>

Forms

<div class="pos-form-group">
  <label class="pos-label">Email</label>
  <input type="email" class="pos-input" placeholder="Enter email">
</div>

<div class="pos-form-group">
  <label class="pos-label">Message</label>
  <textarea class="pos-input pos-textarea"></textarea>
</div>

<select class="pos-input pos-select">
  <option>Option 1</option>
  <option>Option 2</option>
</select>

Badges

<span class="pos-badge pos-badge-success">Active</span>
<span class="pos-badge pos-badge-warning">Pending</span>
<span class="pos-badge pos-badge-danger">Failed</span>

Alerts

<div class="pos-alert pos-alert-success">Success message!</div>
<div class="pos-alert pos-alert-warning">Warning message!</div>
<div class="pos-alert pos-alert-danger">Error message!</div>

Tables

<table class="pos-table">
  <thead>
    <tr>
      <th>Product</th>
      <th>Price</th>
      <th>Qty</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Item 1</td>
      <td>₹100</td>
      <td>2</td>
    </tr>
  </tbody>
</table>

Loading States

<!-- Spinner -->
<div class="pos-spinner"></div>
<div class="pos-spinner pos-spinner-lg"></div>

<!-- Skeleton -->
<div class="pos-skeleton pos-skeleton-title"></div>
<div class="pos-skeleton pos-skeleton-text"></div>

Layout

<!-- Grid -->
<div class="pos-grid pos-grid-2">
  <div>Column 1</div>
  <div>Column 2</div>
</div>

<!-- Flex -->
<div class="pos-flex pos-items-center pos-justify-between">
  <span>Left</span>
  <span>Right</span>
</div>

Development Workflow

Create plugin:

cpos-plugin create my-plugin
cd my-plugin

Start dev server:
```
cpos-plugin serve
```
Edit files - Changes auto-reload in browser
Test in POS:
- Build: cpos-plugin build
- Package: cpos-plugin package
- Install in CommercePOS app
Distribute:
- Share .cposplugin file
- Users install via Settings > Plugins

Troubleshooting

Command not found after npm link:

# Try with npx
npx cpos-plugin create my-plugin

# Or run directly
node ./bin/cpos-plugin.js create my-plugin

Port already in use:

cpos-plugin serve --port 3001

Build fails:

Ensure you're in a plugin directory (has manifest.json)
Check for syntax errors in HTML/CSS/JS

Plugin not loading in POS:

Verify manifest.json is valid JSON
Check minPosVersion compatibility
Ensure entryPoint file exists

Examples

Basic Plugin

// main.js
const Plugin = {
  async init() {
    await POS_SDK.ready();
    this.updateStatus('Connected');

    POS_SDK.on('cartChanged', (cart) => {
      this.updateCartDisplay(cart);
    });
  },

  updateStatus(status) {
    document.getElementById('status').textContent = status;
  },

  updateCartDisplay(cart) {
    const total = cart.items.reduce((sum, item) =>
      sum + (item.price * item.quantity), 0);
    document.getElementById('cart-total').textContent = `₹${total}`;
  }
};

document.addEventListener('DOMContentLoaded', () => Plugin.init());

Payment Plugin

// payment-handler.js
const PaymentGateway = {
  async processPayment(amount) {
    const order = await POS_SDK.getCurrentOrder();

    // Call your payment gateway API
    const result = await this.callGateway({
      amount,
      orderId: order.id,
      currency: 'INR'
    });

    if (result.success) {
      await POS_SDK.showToast({
        message: 'Payment successful!',
        type: 'success'
      });
    }

    return result;
  }
};

Support

For issues and feature requests, create an issue at github.com/withcommmerce/commmerce-pos-cli/issues.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github/workflows		.github/workflows
bin		bin
docs		docs
src		src
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

License

withcommmerce/commmerce-pos-cli

Folders and files

Latest commit

History

Repository files navigation

CommercePOS Plugin CLI

Installation

From npm (Recommended)

Using npx (No Installation)

From GitHub Packages (Enterprise)

From Source

Quick Start

Commands

cpos-plugin create <plugin-name>

cpos-plugin serve

cpos-plugin build

cpos-plugin package

Plugin Structure

Manifest Configuration

POS SDK

Initialization

Orders & Cart

Products

Customers

Payments

Notifications

Hardware

Navigation

Settings

Events

HTTP Requests

Store & Staff Info

Analytics

POS UI Components

Cards

Buttons

Forms

Badges

Alerts

Tables

Loading States

Layout

Development Workflow

Troubleshooting

Examples

Basic Plugin

Payment Plugin

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

`cpos-plugin create <plugin-name>`

`cpos-plugin serve`

`cpos-plugin build`

`cpos-plugin package`

Packages