OQO CLI

The OQO CLI (oqo) is the developer tool for building themes locally. Work in your own editor, use your own toolchain, and sync changes to your site's sandbox theme in real time.

oqo login                     # authenticate
oqo theme init my-theme       # scaffold a new theme
cd my-theme
oqo theme dev                 # watch + live sync

Installation

npm (Recommended)
Homebrew (macOS)
Shell script
Manual download

npm install -g @oqo/cli

brew install oqo/tap/oqo

curl -fsSL https://cli.ooopps.com/install.sh | sh

Verify the installation:

oqo --version

Authentication

oqo login      # interactive: enter site URL + API key
oqo whoami     # show current auth info
oqo logout     # clear stored credentials

During oqo login, you provide your site URL and an API key (generated in your OQO admin panel). Credentials are stored in ~/.oqo/credentials.json with restricted file permissions.

Workflow: init → dev → push

1. Create a theme

oqo theme init my-theme

This creates a remote sandbox theme from the starter template and pulls all files locally. Your directory will look like:

my-theme/
├── .oqo/
│   └── config.json              # project config (theme ID, API URL)
├── .oqoignore                   # files to exclude from sync
├── assets/
│   ├── css/
│   │   ├── _variables.css.liquid
│   │   └── theme.css
│   ├── theme.css
│   └── theme.js
├── config/
│   └── settings_schema.json
├── layouts/
│   └── default.liquid
└── sections/
    └── hero/
        └── simple.liquid

2. Develop with live sync

oqo theme dev

Watches your local files for changes. On every save, the modified file is synced to the sandbox theme on the server. Open the preview URL to see changes live:

oqo theme preview

3. Push and pull

oqo theme push                   # upload all local changes
oqo theme push --path <file>     # push a single file
oqo theme pull                   # download remote to local

Conflict handling

If the remote theme changed since your last sync, oqo shows a conflict summary. Resolve with:

oqo theme push --force-local     # overwrite remote with local
oqo theme pull --force-remote    # overwrite local with remote

Commands Reference

Auth & Context

Command	Description
`oqo login`	Authenticate with your site (URL + API key)
`oqo logout`	Clear stored credentials
`oqo whoami`	Show current auth and site info
`oqo doctor`	Check environment, credentials, and project config

Theme Development

Command	Description
`oqo theme init <name>`	Create a new theme from starter template
`oqo theme list`	List all remote themes on the site
`oqo theme status`	Show diff between local and remote files
`oqo theme dev`	Watch for changes, auto-sync to sandbox
`oqo theme push`	Upload all local changes to remote
`oqo theme push --path <file>`	Push a single file
`oqo theme push --force-local`	Push and delete remote-only files
`oqo theme pull`	Download remote theme files locally
`oqo theme pull --handle <h>`	Clone a remote theme by handle
`oqo theme pull --force-remote`	Overwrite local with remote
`oqo theme activate <handle>`	Set a theme as the active sandbox theme
`oqo theme validate`	Run local + server-side validation
`oqo theme preview`	Get the sandbox preview URL

AI Section Development

Create and modify Liquid sections through an interactive AI conversation. The AI reads your theme context, generates template + schema + CSS, and syncs modified files back locally.

Command	Description
`oqo section create <path>`	Create a new section with AI (e.g., `hero/banner.liquid`)
`oqo section modify <path>`	Modify an existing section with AI

Example session:

$ oqo section create hero/banner.liquid

→ Creating section sections/hero/banner.liquid...

Describe the section you want to create: A hero banner with title, subtitle,
and CTA button on a background image

  →  Reading theme primer...           ✓
  →  Reading docs...                   ✓
  →  Updating template...              ✓
  →  Updating schema...                ✓
  →  Updating CSS...                   ✓

AI: Created hero/banner.liquid with a full-width hero section.

What changes do you want to make?: /done

✓ Synced 2 files:
  ↓ sections/hero/banner.liquid
  ↓ assets/theme.css

Type /done to exit the conversation. Modified files are pulled from the server automatically.

Snapshots

Save and restore theme states for safe experimentation:

Command	Description
`oqo theme snapshot create`	Create a snapshot of the current theme state
`oqo theme snapshot create --name "v1"`	Create a named snapshot
`oqo theme snapshot list`	List all snapshots
`oqo theme snapshot restore <id>`	Restore a snapshot by ID

Project Config

`.oqo/config.json`

Created by oqo theme init. Stores the link between your local directory and the remote sandbox theme:

{
  "api_base_url": "https://yoursite.ooopps.com",
  "sandbox_theme_id": 42,
  "theme_root": "."
}

Field	Description
`api_base_url`	Your OQO site URL (set during `oqo login`)
`sandbox_theme_id`	Remote theme ID (set during `init` or `push`)
`theme_root`	Relative path to theme files (usually `.`)

`.oqoignore`

Glob patterns for files to exclude from sync (same syntax as .gitignore). Default ignores:

.oqo/
.git/
node_modules/
.DS_Store
Thumbs.db
*.swp
*.swo
*~

Theme File Conventions

Directory	Purpose
`layouts/`	Page layouts (`default.liquid`, etc.)
`sections/`	Section components, organized by group (`hero/`, `content/`, `nav/`)
`snippets/`	Small reusable Liquid partials
`templates/`	Page-specific templates
`config/`	`settings_schema.json` and `settings_data.json`
`assets/`	CSS, JS, images, fonts

See Theme Structure for details on each directory.

Typical Development Session

# Start fresh
oqo theme init my-theme && cd my-theme

# Open in your editor
code .

# Terminal 1: Tailwind watch (if using Tailwind)
tailwindcss -i assets/css/tailwind.css -o assets/framework.css --watch

# Terminal 2: OQO live sync
oqo theme dev

# Terminal 3: Check your work
oqo theme preview          # opens sandbox URL
oqo theme status           # see what changed
oqo theme validate         # check for errors

# Save a checkpoint before major changes
oqo theme snapshot create --name "before-redesign"

# Create a new section with AI
oqo section create cta/signup.liquid

# When done, push everything
oqo theme push

Installation​

Authentication​

Workflow: init → dev → push​

1. Create a theme​

2. Develop with live sync​

3. Push and pull​

Conflict handling​

Commands Reference​

Auth & Context​

Theme Development​

AI Section Development​

Snapshots​

Project Config​

.oqo/config.json​

.oqoignore​

Theme File Conventions​

Typical Development Session​