@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. Verify identity (prod Supabase/Builder URLs are baked in — no env setup needed)
ollieshop whoami -o json

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

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OLLIE_SUPABASE_URL | No (prod baked) | Override Supabase project URL — e.g. http://127.0.0.1:54321 for local dev | | OLLIE_SUPABASE_ANON_KEY | No (prod baked) | Override Supabase anon/public key | | OLLIE_BUILDER_URL | No (prod baked) | Override Builder service URL — e.g. a staging endpoint | | OLLIE_SKIP_UPDATE_CHECK | No | Set to any value to silence the "update available" banner |

All three default to prod and are baked into the published binary. Set the env vars only when pointing the CLI at a non-prod environment. See .env.example for local-dev defaults.

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 | | ollieshop check-update | Report whether a newer version is published on npm |

Staying up to date

Every run checks npm for a newer @ollie-shop/cli (cached 24h in ~/.ollie-shop/update-check.json) and prints a banner to stderr when one exists:

⚠  Update available: 1.11.0 → 1.12.0
   Run npm i -g @ollie-shop/cli@latest to update.

The banner is suppressed whenever nothing human is reading: piped output, an explicit -o json, CI, or OLLIE_SKIP_UPDATE_CHECK. The -o json rule matters on its own — agent harnesses often run under a pty, where the terminal test alone would still print. The check never blocks (1.5s timeout) and never fails a command.

For a machine-readable answer, use check-update:

ollieshop check-update -o json
# {"data":{"current":"1.11.0","latest":"1.12.0","outdated":true,"severity":"minor",
#          "updateCommand":"npm i -g @ollie-shop/cli@latest","checkFailed":false}}

ollieshop check-update --force -o json   # skip the 24h cache

checkFailed: true means this run did not get a fresh answer from the registry. latest may still be filled in from an expired cache — useful for the banner, but not evidence that the CLI is current, so do not read outdated: false as "up to date" when the check failed. A cache still inside its 24h TTL counts as a successful check.

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|update|list

Create, update or list functions for a version.

--invocation picks the phase the handler runs in — response (default) rewrites the upstream response, request rewrites the outgoing call. Check it in function list: the hub skips any function whose invocation is null.

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

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

# Update an existing one (at least one field required)
ollieshop function update --function-id <FUNCTION_UUID> --invocation request --active true

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

Trimming the bundle with .ollieignore

The bundle carries the whole project root, and the Builder rejects anything over 10 MB. Add a .ollieignore to the project root to keep files out of it:

# gitignore syntax, matched against paths inside the bundle
public/screenshots/
docs/
*.mp4
assets/*
!assets/icon.svg

Patterns are matched against paths relative to the bundle root, so they read the same way they do in a .gitignore: write public/screenshots/, not screenshots/. Only the root file is read, nested .ollieignore files are not.

Nothing is excluded for being a dotfile, .env included. That is deliberate, since a project may need its config at build time, but it does mean secrets in a dotfile reach the Builder unless you exclude them:

.env
.env.*

Projects scaffolded by create-ollie-shop start with an .ollieignore covering the local caches and tooling directories that the build has no use for.

Three things it cannot do:

1. Re-include a built-in exclusion. node_modules/, .git/ and build output (dist/, build/, .next/, *.d.ts, *.js.map, *.tsbuildinfo) are dropped at any depth, before user patterns are consulted. A ! negation only applies against your own patterns.
2. Re-include a file whose parent directory is excluded, the same restriction git has. public/ followed by !public/keep.png keeps nothing.
3. Drop package.json or the generated entry point. The builder needs both. A pattern matching them warns and is otherwise ignored.

Use --dry-run to see what a pattern actually does before deploying. It reports excludedCount and the excluded paths alongside the bundle size:

ollieshop deploy --component-id <UUID> --name FreeShippingBar --dry-run -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 | | --no-open | | start only: don't auto-open Studio in the browser (also honored via the CI env var) |

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
│   ├── check-update-cmd.ts # Agent: CLI version vs npm latest
│   ├── 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)
    ├── ignore.ts        # .ollieignore loader + matcher
    ├── auth.ts          # Browser auth flow + credential storage
    ├── config.ts        # ollie.json config loader/saver
    └── update-notifier.ts # npm version check + stderr banner