# R3PLICA CLI — Reference for Claude Code

Drop this file into your project root (or merge into an existing `CLAUDE.md`) so Claude Code knows the R3PLICA CLI is available and how to use it.

The `r3` CLI ships with the `r3plica` npm package:

```bash
npm install -g r3plica
```

Two binaries are installed:
- `r3` — the catalog CLI documented here
- `r3-mcp` — the MCP server (used when integrating via Claude Desktop or `claude mcp add`)

This file is about the `r3` CLI. Use it directly via Claude Code's shell tool — no MCP protocol, no tool registry, no extra setup. The agent invokes `r3` like any other command, sees the structured output, and reasons on it.

## Output formats

By default `r3` prints a box-drawing table to your terminal. For agents, force markdown:

```bash
r3 product list --markdown
```

Other flags:
- `--json` — raw JSON output
- `--pretty` — formatted table (default in TTY)
- `--verbose` — debug info on stderr

## Common commands

### Products

```bash
r3 product list --markdown                          # List the catalog
r3 product list --brand "Miniforms" --markdown     # Filter by brand
r3 product search "caruso" --markdown               # Free-text search
r3 product get <mongo_id> --markdown                # Single product detail
r3 product compare <id1> <id2> --markdown           # Side-by-side comparison
r3 product stats --group-by brand --markdown        # Catalog statistics
```

### Brands

```bash
r3 brand list --markdown
r3 brand search "minif" --markdown
r3 brand get "Miniforms" --markdown
```

### Product collections

```bash
r3 product-collection list --markdown
r3 product-collection search "eclipse" --markdown
```

### Finish collections (fabric, leather, wood, marble, metal — sold as a set)

```bash
r3 finish-collection list --markdown
r3 finish-collection search "velvet" --markdown
r3 finish-collection get <mongo_id> --markdown
```

## Terminology

R3PLICA uses design-world language. Internalize this when reasoning about user requests:

- **Product** — a single item in the catalog (e.g. "Caruso sideboard")
- **Product variant** — dimensional or additional variation of the same product (e.g. 120cm vs 180cm)
- **Brand** — manufacturer / partner brand
- **Collection** — a brand's product line (e.g. "Eclipse" by Miniforms)
- **Finish collection** — a set of finishes sold as one asset (e.g. "Bolzan Wood")
- **Finish** — a single finish inside a finish collection (e.g. "Walnut")

Do NOT call individual finishes "variants" — that word is reserved for product variants.

## When to use `r3` CLI vs MCP

- **Use `r3` CLI** when working in a terminal agent (Claude Code, Cursor terminal, automation scripts). Lower overhead, more transparency, structured catalog data inline in your shell session.
- **Use MCP** (via `r3-mcp` or `mcp-remote`) when you want richer integration: catalog + scene awareness combined, tool annotations, ownership-aware operations. See https://www.r3plica.space/integrations/mcp for setup.

## Catalog deep-links

Every product, brand and finish collection has a stable URL on the catalog. Use these when generating documents or sharing:

- Product → `https://catalog.r3plica.space/go/product/<mongo_id>`
- Finish collection → `https://catalog.r3plica.space/go/finish/<mongo_id>`

(Note: the finish route is singular `/go/finish/`, NOT `/go/finish-collection/`. Individual finishes do not have their own page — link to the parent collection.)

## CDN asset paths (when embedding images in artifacts)

- Product thumbnails: `https://cdn.r3plica.space/img/products/SM_<asset_name>.0002.webp` (8 frames available, .0002 is the canonical view)
- Finish thumbnails: `https://cdn.r3plica.space/img/materials/MI_<asset_name>.webp`

For inline-friendly sizes, route through Cloudflare Image Resizing:
`https://cdn.r3plica.space/cdn-cgi/image/width=400,fit=cover,format=png/img/<path>`

`SM_` = Static Mesh prefix (products). `MI_` = Material Instance prefix (finishes). These are constant across all brands — do NOT pattern-match brand-derived prefixes.

## Configuration

```bash
r3 config get          # Show current API URL
r3 config set-url ...  # Override the API base URL (rarely needed)
```

The CLI talks to `https://api.r3plica.space` by default.

---

Documentation last updated alongside `r3plica` npm package. For the freshest reference: `r3 --help` and `r3 <command> --help`.