npm package: @opencommerceprotocol/cli
Description: Open Commerce Protocol — CLI tool for generating and validating OCP files
Latest version: 1.1.0

# @opencommerceprotocol/cli

Command-line tool for the [Open Commerce Protocol](https://opencommerceprotocol.org). Set up, validate, and manage OCP for any website.

## Installation

```bash
npm install -g @opencommerceprotocol/cli
# or use without installing:
npx @opencommerceprotocol/cli <command>
```

## Commands

### `ocp init`

Interactive wizard to generate OCP files for your store.

```bash
ocp init
ocp init --output ./public
```

Generates:
- `.well-known/ocp.json` — manifest
- `ocp/products.jsonl` — product feed
- `ocp.md` — natural language store description

---

### `ocp crawl <url>`

Crawl a website and extract Schema.org Product JSON-LD to generate OCP files automatically.

```bash
ocp crawl https://mystore.com
ocp crawl https://mystore.com --output ./ocp-output
ocp crawl https://mystore.com --max-products 500
ocp crawl https://mystore.com --product-pattern "/products/"
ocp crawl https://mystore.com --dry-run   # list URLs without fetching
ocp crawl https://mystore.com --verbose   # detailed per-URL output
```

| Flag | Default | Description |
|------|---------|-------------|
| `--output <dir>` | `./ocp-output` | Output directory |
| `--concurrency <n>` | `5` | Max concurrent requests |
| `--delay <ms>` | `200` | Delay between requests |
| `--product-pattern <regex>` | — | URL pattern for product pages |
| `--max-products <n>` | — | Maximum products to extract |
| `--user-agent <string>` | `OCPBot/1.0` | Custom User-Agent |
| `--include-variants` | `true` | Extract product variants |
| `--generate-agent-notes` | `true` | Auto-generate `agent_notes` |
| `--dry-run` | `false` | List URLs without fetching |
| `--resume` | `false` | Resume interrupted crawl |

---

### `ocp validate <target>`

Validate a live site or local directory. Shows a 0–100 quality score.

```bash
ocp validate https://mystore.com
ocp validate ./public   # local directory
```

Checks:
- Manifest structure and required fields
- Product feed validity
- `robots.txt` has `OCP-Manifest` directive
- `llms.txt` has Commerce section
- `agent_notes` quality scores

---

### `ocp generate`

Generate OCP files from a product CSV, JSON, or JSONL file.

```bash
ocp generate --products catalog.csv
ocp generate --products catalog.json
ocp generate --products catalog.jsonl
ocp generate --products catalog.csv --config ocp.config.json --output ./public
```

CSV example:
```csv
id,name,price,currency,url,description
prod-001,Headphones,149.99,USD,https://mystore.com/headphones,Premium wireless headphones
```

| Flag | Default | Description |
|------|---------|-------------|
| `--products <file>` | — | Input file (.csv, .json, or .jsonl) |
| `--config <file>` | — | OCP config file |
| `--output <dir>` | `.` | Output directory |

---

### `ocp bridge`

Generate bridge configuration for other agent protocols.

```bash
ocp bridge --protocol mcp
ocp bridge --protocol ucp
ocp bridge --protocol a2a
ocp bridge --manifest .well-known/ocp.json --output ./bridge
```

| Flag | Default | Description |
|------|---------|-------------|
| `--protocol <protocol>` | `mcp` | Target: `mcp`, `ucp`, or `a2a` |
| `--manifest <file>` | `.well-known/ocp.json` | OCP manifest file |
| `--output <dir>` | `./bridge` | Output directory |

---

### `ocp robots [path]`

Add the `OCP-Manifest` directive to your `robots.txt`.

```bash
ocp robots              # updates ./robots.txt in place
ocp robots /etc/nginx/robots.txt
ocp robots --stdout     # print to stdout
ocp robots --url https://mystore.com/.well-known/ocp.json
```

Result in `robots.txt`:
```
OCP-Manifest: https://mystore.com/.well-known/ocp.json
```

---

### `ocp llms [path]`

Generate or patch `llms.txt` with an OCP Commerce section.

```bash
ocp llms              # updates ./llms.txt in place
ocp llms --stdout     # print to stdout
ocp llms --full       # also generate llms-full.txt with product descriptions
```

---

### `ocp stats [url]`

Analyze server access logs to understand AI agent traffic.

```bash
ocp stats --log /var/log/nginx/access.log
ocp stats https://mystore.com --log access.log --format nginx --days 30
ocp stats --log access.log --format apache
ocp stats --log access.log --format cloudflare
```

Reports:
- Total agent visits by bot (ChatGPT, Claude, Gemini, etc.)
- Products most viewed by agents
- Search queries agents used
- Agent traffic trends over time

| Flag | Default | Description |
|------|---------|-------------|
| `--log <file>` | — | Path to log file |
| `--format <format>` | `nginx` | Log format: `nginx`, `apache`, `cloudflare` |
| `--days <n>` | `30` | Number of days to analyze |

---

### `ocp test-agent <url>`

Simulate an AI agent visiting your store and produce a pass/fail conformance report.

```bash
ocp test-agent https://mystore.com
ocp test-agent https://mystore.com --query "blue running shoes"
ocp test-agent https://mystore.com --verbose
```

| Flag | Default | Description |
|------|---------|-------------|
| `--query <query>` | `product` | Test search query |
| `--verbose` | `false` | Show detailed output and sample `agent_notes` |

---

### `ocp preview <url>`

Render what an AI agent sees when visiting your store.

```bash
ocp preview https://mystore.com
ocp preview https://mystore.com --products 10
ocp preview https://mystore.com --verbose
```

| Flag | Default | Description |
|------|---------|-------------|
| `--products <n>` | `5` | Number of sample products to show |
| `--verbose` | `false` | Show full `ocp.md` and best/worst `agent_notes` |

---

### `ocp agent-discover <url>`

Discover agent tools at any URL via `/.well-known/agent.json` or OCP fallback.

```bash
ocp agent-discover https://mystore.com
ocp agent-discover https://mystore.com --verbose
ocp agent-discover https://mystore.com --format json
ocp agent-discover https://mystore.com --format mcp
ocp agent-discover https://mystore.com --format openai
```

| Flag | Default | Description |
|------|---------|-------------|
| `--verbose` | `false` | Show full tool list with descriptions |
| `--format <format>` | `text` | Output: `text`, `json`, `mcp`, `openai` |

---

## CI/CD Integration

### Validate on deploy (GitHub Actions)

```yaml
- name: Validate OCP
  run: npx @opencommerceprotocol/cli validate https://mystore.com
```

### Cron sync with `generate`

```bash
# crontab: regenerate feed daily at midnight
0 0 * * * ocp generate --products /data/products.csv --output /var/www/html
```

## Configuration File

Create `ocp.config.json` for `generate`:

```json
{
  "merchant": {
    "name": "My Store",
    "url": "https://mystore.com",
    "currency": "USD"
  },
  "capabilities": {
    "catalog": true,
    "search": true,
    "cart": true,
    "checkout": "redirect"
  }
}
```