@ollie-shop/cli

Command-line interface for the Ollie Shop platform. Provides both interactive commands (login, dev server) and agent-first commands designed for AI/LLM consumption.

Installation

pnpm add @ollie-shop/cli

Or run directly from the monorepo:

pnpm --filter @ollie-shop/cli build
node packages/cli/dist/index.js <command>

Quick Start

# 1. Authenticate
ollieshop login

# 2. Set environment variables
export OLLIE_SUPABASE_URL=https://your-project.supabase.co
export OLLIE_SUPABASE_ANON_KEY=your-anon-key

# 3. Verify identity
ollieshop whoami -o json

# 4. List your stores
ollieshop store list -o json --fields id,name,platform

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OLLIE_SUPABASE_URL | Yes (agent commands) | Supabase project URL | | OLLIE_SUPABASE_ANON_KEY | Yes (agent commands) | Supabase anon/public key | | OLLIE_BUILDER_URL | Yes (deploy/status) | Builder service URL |

See .env.example for reference. The CLI will throw a clear error if a required variable is missing.

Commands

Interactive Commands

| Command | Description | |---------|-------------| | ollieshop login | Authenticate via browser (stores token in ~/.ollie-shop/credentials.json) | | ollieshop start | Start the development server with hot reload | | ollieshop help | Show help message | | ollieshop version | Show CLI version |

Agent Commands

Agent commands output structured JSON and are designed for programmatic / AI-agent consumption.

whoami

Show the currently authenticated user and their organization.

ollieshop whoami -o json
# {"data":{"email":"[email protected]"}}

store create|list

Create or list stores in your organization.

# List stores
ollieshop store list -o json --fields id,name,platform

# Create a store (dry-run first)
ollieshop store create --name "My Store" --platform vtex --platform-store-id mystore --dry-run -o json
ollieshop store create --name "My Store" --platform vtex --platform-store-id mystore -o json

# Create using raw JSON input
ollieshop store create -d '{"name":"My Store","platform":"vtex","platformStoreId":"mystore"}' -o json

version create|list

Create or list versions for a store.

# List versions
ollieshop version list --store-id <STORE_UUID> -o json --fields id,name,active

# Create a version
ollieshop version create --store-id <STORE_UUID> --name v1 --active -o json

component create|list

Create or list components for a store (optionally filtered by version).

# List components
ollieshop component list --store-id <STORE_UUID> -o json --fields id,name,slot,active

# Create a component
ollieshop component create --version-id <VERSION_UUID> --name FreeShippingBar --slot cart_header_full_page -o json

function create|list

Create or list functions for a version.

# List functions
ollieshop function list --store-id <STORE_UUID> -o json --fields id,name,active

# Create a function
ollieshop function create --version-id <VERSION_UUID> --name myHook -o json

deploy

Bundle a component directory into a zip and upload to the Builder service.

# Dry-run: validate and show bundle size
ollieshop deploy --component-id <UUID> --name FreeShippingBar --dry-run -o json

# Deploy and wait for build to complete
ollieshop deploy --component-id <UUID> --name FreeShippingBar --wait -o json

# Deploy a function
ollieshop deploy --function-id <UUID> --name myHook --wait -o json

status

Check or poll a build status.

# One-shot status check
ollieshop status --build-id <BUILD_ID> -o json

# Poll until terminal status
ollieshop status --build-id <BUILD_ID> --wait --timeout 300 -o json

schema

Introspect resource schemas at runtime. Returns JSON Schema definitions for all available resources and actions.

# List all available schemas
ollieshop schema -o json

# Get schema for a specific resource action
ollieshop schema store.create -o json
ollieshop schema component.create -o json

init

Write store and version IDs to a local ollie.json config file.

ollieshop init --store-id <STORE_UUID> --version-id <VERSION_UUID> -o json
# Creates ollie.json: {"storeId":"...","versionId":"..."}

Global Flags

| Flag | Short | Description | |------|-------|-------------| | --output json\|pretty | -o | Force output format. Auto-detects: JSON when piped, pretty when TTY | | --dry-run | | Validate inputs without executing mutations | | --fields a,b,c | | Limit output fields (comma-separated) | | --data '{...}' | -d | Raw JSON payload for mutations (alternative to individual flags) | | --stage <name> | -s | Config stage — loads ollie.<stage>.json instead of ollie.json |

Response Format

All agent commands return a consistent JSON envelope:

// Success (exit code 0)
{"data": { ... }}

// Error (exit code 1)
{"error": {"message": "Human-readable error description"}}

The exit code indicates success (0) or failure (1), making the success field redundant.

Available Platforms

vtex, shopify, vnda, custom

Available Slots (common)

• cart_header_full_page
• cart_footer_full_page
• shipping_address_details_form
• payment_header
• summary_after_totals
• profile_after_email

AI/LLM Agent Usage

See CONTEXT.md for detailed guidelines on how AI agents should interact with the CLI, including best practices, the recommended workflow, and introspection patterns.

Architecture

src/
├── index.tsx           # Entry point — routes to agent or interactive commands
├── cli.tsx             # Ink app for interactive commands
├── commands/
│   ├── whoami.ts        # Agent: show current user
│   ├── store-cmd.ts     # Agent: store CRUD
│   ├── version-cmd.ts   # Agent: version CRUD
│   ├── component-cmd.ts # Agent: component CRUD
│   ├── function-cmd.ts  # Agent: function CRUD
│   ├── deploy-cmd.ts    # Agent: bundle + upload builds
│   ├── status-cmd.ts    # Agent: check/poll build status
│   ├── schema-cmd.ts    # Agent: schema introspection
│   ├── init-cmd.ts      # Agent: write ollie.json
│   ├── help.tsx         # Interactive: help display
│   ├── login.tsx        # Interactive: browser auth
│   └── start.tsx        # Interactive: dev server
├── core/
│   ├── store.ts         # Store business logic + Supabase queries
│   ├── version.ts       # Version business logic + Supabase queries
│   ├── component.ts     # Component business logic + Supabase queries
│   ├── function.ts      # Function business logic + Supabase queries
│   ├── deploy.ts        # Builder API client (upload, status, poll)
│   └── schema.ts        # Zod schemas + JSON Schema generation
└── utils/
    ├── parse-args.ts    # CLI argument parser (flags, subcommands, positional)
    ├── output.ts        # JSON/pretty output formatter + field filtering
    ├── validate.ts      # UUID, required, enum, resource name validators
    ├── supabase.ts      # Authenticated Supabase client + builder URL + org resolution
    ├── bundle.ts        # Component zip bundler (archiver)
    ├── auth.ts          # Browser auth flow + credential storage
    └── config.ts        # ollie.json config loader/saver