npm package: @ollie-shop/cli
Description: Ollie Shop CLI - Development tools for custom checkouts
Latest version: 1.1.0

# @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

```bash
pnpm add @ollie-shop/cli
```

Or run directly from the monorepo:

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

## Quick Start

```bash
# 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 |

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.

```bash
ollieshop whoami -o json
# {"data":{"email":"user@example.com"}}
```

#### `store create|list`

Create or list stores in your organization.

```bash
# 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.

```bash
# 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).

```bash
# 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
```

#### `schema`

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

```bash
# 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.

```bash
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:

```json
// 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](./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
│   ├── 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
│   └── 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 + org resolution
    ├── auth.ts          # Browser auth flow + credential storage
    └── config.ts        # ollie.json config loader/saver
```