O2VEND Theme CLI

The O2VEND Theme CLI is a standalone command-line tool for developing O2VEND themes locally. It provides a complete development environment with hot reload, mock API server, and theme validation tools.

Installation

Install the CLI globally via npm:

npm install -g @o2vend/theme-cli

Verify installation:

o2vend --version

Quick Start

Option 1: Use the O2VEND Theme Starter (Recommended)

Clone the ready-to-use starter template:

git clone https://github.com/Jeyan-Technologies/o2vend-theme-starter.git
cd o2vend-theme-starter
npm run setup
o2vend serve

Option 2: Create a New Theme

Initialize a new theme from scratch:

o2vend init my-theme
cd my-theme
o2vend serve

Commands

`serve`

Start development server with hot reload:

o2vend serve [options]

Options:

-m, --mode <mode> - API mode (mock|real) [default: mock]
-p, --port <port> - Server port [default: 3000]
--host <host> - Server host [default: localhost]
-t, --theme <themePath> - Path to theme directory [default: current]
-e, --env <envFile> - Path to .env file [default: .env]
--open - Open browser automatically [default: true]
--no-open - Don't open browser
--mock-api-port <port> - Mock API port [default: 3001]
--cwd <path> - Working directory (theme path)

Examples:

# Start in mock mode (default) - works offline
o2vend serve

# Connect to real O2VEND API
o2vend serve --mode real

# Custom port
o2vend serve --port 8080

# Don't open browser automatically
o2vend serve --no-open

# Specify theme directory
o2vend serve --cwd /path/to/theme

`init <name>`

Initialize a new theme project:

o2vend init my-theme

Creates a new theme directory with:

Complete theme structure (templates, sections, widgets, assets)
Configuration files (settings_schema.json, settings_data.json)
Example templates and widgets
VS Code configuration
.env file template

`validate`

Validate theme structure and configuration:

o2vend validate

Checks for:

Required theme files and directories
Valid Liquid syntax
Proper theme structure
Configuration file validity
Widget template compatibility

`check`

Check theme for issues and best practices:

o2vend check

Performs various checks:

Syntax errors in Liquid templates
Missing required files
Performance issues
Accessibility concerns
Best practice violations

`optimize`

Analyze and optimize theme performance:

o2vend optimize

Provides analysis for:

CSS file sizes
JavaScript file sizes
Image optimization opportunities
Asset bundling recommendations
Performance metrics

`package`

Package theme for O2VEND marketplace submission:

o2vend package [options]

Options:

-o, --output <path> - Output ZIP file path [default: dist/theme.zip]
--validate - Run validation before packaging
--theme-id <id> - Theme ID for theme.json
--theme-name <name> - Theme name for theme.json
--theme-version <version> - Theme version for theme.json
--author <author> - Author name for theme.json
--description <description> - Theme description for theme.json

Creates a marketplace-ready ZIP file with:

theme.json manifest (auto-generated if missing)
All theme files
Optional migrations folder
Proper file structure

Features

Hot Reload

Automatic browser refresh on file changes:

CSS changes - Injected without page reload
Liquid/JS changes - Full page reload
File watching - Automatic change detection
WebSocket-based - Real-time updates

Mock API

Built-in mock API provides realistic test data for offline development:

Products (20+ sample items)
Categories (10+ sample items)
Brands (8+ sample items)
Widgets (multiple sections: hero, products, footer)
Store information
Shopping cart simulation

Perfect for:

Developing themes without API access
Testing theme layouts
Prototyping new designs
Learning O2VEND theme structure

Real API Mode

Connect to actual O2VEND Storefront API:

Full API compatibility
Authentication support
Widget loading from API
Real-time data from your tenant
Product, category, and brand data

Environment Variables

Create a .env file in your theme directory:

# API Configuration (for real API mode)
O2VEND_TENANT_ID=your-tenant-id
O2VEND_API_KEY=your-api-key
O2VEND_API_BASE_URL=https://api.o2vend.com

# Development Server
PORT=3000
HOST=localhost
MOCK_API_PORT=3001

# Options
OPEN_BROWSER=true
DEBUG_API_ERRORS=false

Variable	Description	Default
`O2VEND_TENANT_ID`	Tenant ID (real mode)	-
`O2VEND_API_KEY`	API Key (real mode)	-
`O2VEND_API_BASE_URL`	API Base URL (real mode)	-
`PORT`	Development server port	`3000`
`HOST`	Development server host	`localhost`
`MOCK_API_PORT`	Mock API server port	`3001`
`OPEN_BROWSER`	Auto-open browser	`true`
`DEBUG_API_ERRORS`	Debug API errors	`false`

Development Workflow

# 1. Start development server
o2vend serve

# 2. Make changes to theme files
# Edit templates, sections, widgets, or assets

# 3. Validate theme structure
o2vend validate

# 4. Check for issues
o2vend check

# 5. Optimize assets
o2vend optimize

# 6. Package for marketplace
o2vend package

Connecting to Real API

# Create .env file
cat > .env << EOF
O2VEND_TENANT_ID=your-tenant-id
O2VEND_API_KEY=your-api-key
O2VEND_API_BASE_URL=https://api.o2vend.com
EOF

# Start server in real mode
o2vend serve --mode real

Theme Structure

O2VEND themes follow a specific structure:

theme/
├── layout/
│   └── theme.liquid          # Main layout template
├── templates/
│   ├── index.liquid          # Homepage
│   ├── product.liquid        # Product page
│   ├── collection.liquid     # Collection page
│   └── ...
├── sections/
│   ├── header.liquid
│   ├── footer.liquid
│   └── ...
├── widgets/
│   ├── product.liquid
│   ├── banner.liquid
│   └── ...
├── snippets/
│   └── ...
├── assets/
│   ├── theme.css
│   ├── theme.js
│   └── ...
└── config/
    ├── settings_schema.json
    └── settings_data.json

Important: Templates, sections, and widgets are predefined by O2VEND and come from the O2VEND Storefront API. You can customize existing files but cannot create new templates, sections, or widget types.

Troubleshooting

Port Already in Use

# Use a different port
o2vend serve --port 8080

Layout Not Found Error

Make sure your templates use the correct layout path:

{% layout 'layout/theme' %}

The layout file should be at: theme/layout/theme.liquid

API Connection Issues

If using real API mode:

Verify .env file has correct credentials
Check API base URL is correct
Ensure tenant ID and API key are valid
Try mock mode first: o2vend serve --mode mock

Hot Reload Not Working

Check browser console for WebSocket errors
Verify firewall isn't blocking WebSocket connections
Try refreshing the page manually
Restart the server: o2vend serve

Local Development Setup

For local development of the CLI itself:

Using npm link

cd packages/cli
npm run build
npm link

Then use it from your theme folder:

cd /path/to/your/theme
o2vend serve

Rebuild after changes

After making changes to CLI source files:

cd packages/cli
npm run build  # Rebuild (copies src/ to lib/)

O2VEND Theme Starter - Ready-to-use starter template with complete default theme
O2VEND Liquid VS Code Extension - Syntax highlighting and IntelliSense for O2VEND Liquid templates

Support & Resources

O2VEND Developer Documentation - Complete API documentation and guides
Support Email: [email protected] or [email protected]
Support Desk: O2VEND Support Portal
Community: O2VEND Community Program
Partnership: O2VEND Partnership Program
Developer Portal: www.o2vend.com

License

MIT License

Installation​

Quick Start​

Option 1: Use the O2VEND Theme Starter (Recommended)​

Option 2: Create a New Theme​

Commands​

serve​

init <name>​

validate​

check​

optimize​

package​

Features​

Hot Reload​

Mock API​

Real API Mode​

Environment Variables​

Development Workflow​

Connecting to Real API​

Theme Structure​

Troubleshooting​

Port Already in Use​

Layout Not Found Error​

API Connection Issues​

Hot Reload Not Working​

Local Development Setup​

Using npm link​

Rebuild after changes​

Related Tools​

Support & Resources​

License​