# CLISHOP CLI — Machine-Readable Documentation
# Version: 1.1.0
# Updated: 2026-03-01
# Docs: https://clishop.ai/docs
# Source: https://github.com/DavooxBv2/CLISHOP
# Website: https://clishop.ai
# Dark Store (vendor template): https://github.com/DavooxBv2/CLISHOP-DARKSTORE

> CLISHOP is an open-source CLI that lets AI agents and humans search for products
> across multiple stores, compare prices, and place real orders from the terminal.
> It connects to a backend that aggregates products from many vendor stores.
> Every command supports --json output for AI agent integration.
> Safety is enforced through configurable "agents" (spending limits, order confirmation, category restrictions).
> Anyone can sell on CLISHOP by deploying a Dark Store (config-driven vendor template).

## MCP Server

CLISHOP ships as a native MCP server with 19 tools. Install globally and run:
```
npm install -g clishop
clishop-mcp
```

Or run without installing:
```
npx -y clishop --mcp
```

VS Code / GitHub Copilot (.vscode/mcp.json):
```json
{
  "servers": {
    "clishop": {
      "command": "clishop-mcp",
      "args": []
    }
  }
}
```

Claude Desktop (claude_desktop_config.json):
```json
{
  "mcpServers": {
    "clishop": {
      "command": "clishop-mcp"
    }
  }
}
```

Cursor (.cursor/mcp.json):
```json
{
  "mcpServers": {
    "clishop": {
      "command": "clishop-mcp"
    }
  }
}
```

Windsurf (~/.windsurf/mcp.json):
```json
{
  "mcpServers": {
    "clishop": {
      "command": "clishop-mcp"
    }
  }
}
```

Prerequisite: Log in once with `clishop login` before using MCP tools.

### Available MCP Tools (19)

- search_products — Search products across all stores with filters
- get_product — Get detailed product info
- buy_product — Place an order with safety checks
- list_orders — List orders by status
- get_order — Get order details + tracking
- cancel_order — Cancel a pending order
- list_addresses — List shipping addresses
- add_address — Add a shipping address
- remove_address — Remove a shipping address
- list_payment_methods — List payment methods
- list_stores — Browse available stores
- get_store — Get store details
- store_catalog — Browse a store's catalog
- account_status — Full account overview
- list_agents — List safety agents
- create_advertise_request — Post a request for vendors to bid on
- create_support_ticket — Open a support ticket
- list_support_tickets — List support tickets
- submit_feedback — Report bugs or suggest improvements

## Installation

```
npm install -g clishop
```

Requires Node.js 18+. Provides two commands: `clishop` (CLI) and `clishop-mcp` (MCP server).
Auth tokens stored in OS keychain via keytar.

## Setup

```
clishop setup
```

The setup wizard walks through:
1. Account creation or login
2. Agent configuration (default: $200 max per order, confirmation required)
3. Shipping address (required — searches need a country)
4. Payment method (secure Stripe link opened in browser)
5. First product search

You can also create an account on https://clishop.ai instead.

By creating an account you agree to the Terms & Conditions (https://clishop.ai/terms) and Privacy Policy (https://clishop.ai/privacy).

## Authentication

### login
Log in to a CLISHOP account.
```
clishop login [-e <email>] [-p <password>]
```
- `-e, --email <email>` — Email (prompts if omitted)
- `-p, --password <password>` — Password (secure prompt if omitted)
- `--password-stdin` — Read password from stdin (for piping)
- For AI agents: `echo "<password>" | clishop login --email user@example.com --password-stdin`

### register
Create a new account. Interactive only.
```
clishop register
```

### logout
Clear local tokens and server session.
```
clishop logout
```

### whoami
Show logged-in user name, email, and ID.
```
clishop whoami
```

## Agents (Safety Profiles)

Agents control: maxOrderAmount (dollars), requireConfirmation (bool), allowedCategories (string[]), blockedCategories (string[]), defaultAddressId, defaultPaymentMethodId.
Default agent always exists with $200 limit and confirmation required.
When confirmation is required, orders are held until confirmed via email link or on the website.

### agent list
```
clishop agent list
```
Alias: `clishop agent ls`

### agent create <name>
```
clishop agent create <name> [--max-amount <dollars>] [--no-confirm]
```
- `--max-amount <amount>` — Max order amount in dollars. Default: 200
- `--no-confirm` — Disable order confirmation requirement. (Confirmation is on by default.)

### agent use <name>
Switch active agent.
```
clishop agent use <name>
```

### agent show [name]
Show agent details. Defaults to active agent.
```
clishop agent show [name]
```

### agent update [name]
Interactive update of agent settings.
```
clishop agent update [name]
```

### agent spending-limit [amount]
View or change your monthly spending limit. Without an amount, displays the current limit.
```
clishop agent spending-limit
clishop agent spending-limit 500
```
Alias: `clishop agent limit`

### agent delete <name>
Delete an agent. Cannot delete "default".
```
clishop agent delete <name>
```
Alias: `clishop agent rm <name>`

## Search & Products

### search <query>
Search products across all stores. A shipping address (country) is required.
```
clishop search <query> [options]
```

Search result numbers can be used with `info` and `buy`:
```
clishop search "wireless headphones"
clishop info 1          # Details on result #1
clishop info 1 2 3      # Details on results #1, #2, #3
clishop buy 2           # Buy result #2
```

Product filters:
- `-c, --category <category>` — Filter by category
- `--brand <brand>` — Filter by brand
- `--model <model>` — Filter by model
- `--sku <sku>` — Filter by SKU
- `--gtin <gtin>` — Filter by GTIN (UPC/EAN/ISBN)
- `--variant <variant>` — Filter by variant (size/color/storage)

Cost filters:
- `--min-price <cents>` — Minimum price in cents
- `--max-price <cents>` — Maximum price in cents
- `--max-shipping <cents>` — Maximum shipping cost in cents
- `--max-total <cents>` — Maximum total (item + shipping) in cents
- `--free-shipping` — Only free shipping items

Delivery location:
- `--ship-to <address>` — Saved address label or ID (auto-resolves location)
- `--country <code>` — ISO 3166-1 alpha-2 country code
- `--city <city>` — Delivery city
- `--postal-code <code>` — Delivery postal/zip code
- `--region <region>` — State/province/region
- `--lat <latitude>` — Latitude for proximity search
- `--lng <longitude>` — Longitude for proximity search
- `--deliver-by <YYYY-MM-DD>` — Need delivery by date
- `--max-delivery-days <days>` — Maximum transit days
- `--express` — 2-day or faster delivery only

Availability:
- `--in-stock` — In-stock items only
- `--exclude-backorder` — Exclude backordered items
- `--min-qty <qty>` — Minimum quantity available

Returns:
- `--free-returns` — Free returns only
- `--min-return-window-days <days>` — Minimum return window

Trust:
- `--store <store>` — Limit to store (ID, slug, or name)
- `--vendor <vendor>` — Alias for --store
- `--trusted-only` — Verified stores only
- `--min-store-rating <0-5>` — Minimum store rating
- `--checkout-mode <mode>` — instant or handoff

Sorting/pagination:
- `--min-rating <1-5>` — Minimum product rating
- `-s, --sort <field>` — price, total-cost, rating, relevance, newest, delivery. Default: relevance
- `--order <dir>` — asc, desc. Default: desc
- `-p, --page <page>` — Page number. Default: 1
- `-n, --per-page <count>` — Results per page. Default: 10

Extended search:
- `-e, --extended-search` — Force extended search (query vendor stores in real-time)
- `--no-extended-search` — Disable auto extended search
- `--extended-timeout <seconds>` — Timeout 5-60s. Default: 30

Output:
- `--json` — Raw JSON output
- `--compact` — One-line-per-result
- `--detailed` — Full details inline
- `-i, --interactive` — Select products interactively

Note: Extended search auto-triggers when no local results found.
Note: When no location flags, uses active agent's default address for geo-targeting.
Note: A country is required for all searches. Add an address first or pass --country.
Note: Extended search results use xprd_ IDs.

### product <id>
View detailed product information from the local catalog.
```
clishop product <id> [--json]
```

### info <ids...>
Request detailed info from vendor stores. Up to 20 product IDs. Also accepts search result numbers.
```
clishop info <id1> [id2] [id3] [--json]
clishop info 1 2 3                        # Use search result numbers
```
Works with extended search product IDs (xprd_...).

## Orders

### buy <productId>
Quick-buy a product. Also accepts search result numbers.
```
clishop buy <productId> [-q <qty>] [--address <id>] [--payment <id>] [-y]
clishop buy 1 -y                          # Buy search result #1
```
- `-q, --quantity <qty>` — Quantity. Default: 1
- `--address <id>` — Address ID. Default: agent's default
- `--payment <id>` — Payment method ID. Default: agent's default
- `-y, --yes` — Skip confirmation prompt

Safety checks enforced: maxOrderAmount, blockedCategories, allowedCategories.

Order confirmation flow:
1. Payment is authorized immediately.
2. If the agent has requireConfirmation enabled (default), you receive a confirmation email.
3. Confirm via the email link or on the website (https://clishop.ai/orders).
4. The order is only sent to the vendor after confirmation.
5. The confirmation email includes a "don't ask for future orders" option to disable confirmation.

### order list
```
clishop order list [--status <status>] [-p <page>] [--json]
```
Status values: pending, pending_confirmation, confirmed, processing, shipped, delivered, cancelled

### order show <id>
View order details, items, tracking, live vendor status.
```
clishop order show <id> [--json]
```

### order cancel <id>
Cancel an order. Prompts for confirmation.
```
clishop order cancel <id>
```

## Addresses

Addresses are linked to agents. Each agent can have a default address.
Address fields: firstName, lastName, line1, line2, postalCode, city, region, country, phone.
Country input accepts full country names (e.g. "Belgium") and normalizes to ISO country codes.

### address list
```
clishop address list
```
Alias: `clishop address ls`

### address add
Interactive. Required fields: firstName, lastName, line1, postalCode, city, country.
```
clishop address add
```

### address remove <id>
```
clishop address remove <id>
```
Alias: `clishop address rm <id>`

### address set-default <id>
Set default address for active agent.
```
clishop address set-default <id>
```

## Payment Methods

### payment list
```
clishop payment list
```
Alias: `clishop payment ls`

### payment add
Opens secure Stripe link in browser. CLI never handles card details.
```
clishop payment add
```

### payment remove <id>
```
clishop payment remove <id>
```
Alias: `clishop payment rm <id>`

### payment set-default <id>
```
clishop payment set-default <id>
```

## Reviews

Rating scale: 1-10.

### review order <orderId>
Review all items and store from an order. Interactive.
```
clishop review order <orderId>
```

### review add <productId>
Write a product review.
```
clishop review add <productId> [--order <orderId>]
```

### review store <storeId>
Write a store review.
```
clishop review store <storeId> [--order <orderId>]
```

### review list
List your reviews.
```
clishop review list [--json]
```
Alias: `clishop review ls`

### review rating <id>
View rating details (Bayesian average, cap info).
```
clishop review rating <id> [--store]
```

### review delete <reviewId>
```
clishop review delete <reviewId> [--store]
```
Alias: `clishop review rm`

## Stores

### store list
```
clishop store list [-q <query>] [--verified] [--min-rating <0-5>] [--country <code>] [-s <field>] [--order <dir>] [-p <page>] [-n <count>] [--json]
```
Sort fields: name, rating, newest, products

### store info <store>
View store details by name, slug, or ID.
```
clishop store info <store> [--json]
```

### store catalog <store>
Browse store catalog.
```
clishop store catalog <store> [-q <query>] [-c <category>] [--min-price <cents>] [--max-price <cents>] [--min-rating <1-5>] [--in-stock] [--free-shipping] [-s <field>] [--order <dir>] [-p <page>] [-n <count>] [--json]
```

## Advertise (Reverse Marketplace)

Post requests for vendors to bid on when search doesn't find what you need.

### advertise create
Interactive wizard.
```
clishop advertise create
```

### advertise quick <title>
Non-interactive with flags.
```
clishop advertise quick <title> [-d <desc>] [--sku <sku>] [--brand <brand>] [--company <company>] [--features <features>] [-q <qty>] [--recurring] [--recurring-note <note>] [--bid-price <dollars>] [--currency <code>] [--speed <days>] [--free-returns] [--min-return-days <days>] [--payment-methods <methods>] [--address <id>]
```

### advertise list
```
clishop advertise list [--status <status>] [-p <page>] [--json]
```
Status values: open, closed, accepted, cancelled, expired

### advertise show <id>
View request and vendor bids.
```
clishop advertise show <id> [--json]
```

### advertise accept <advertiseId> <bidId>
Accept a vendor bid. Rejects all others.
```
clishop advertise accept <advertiseId> <bidId>
```

### advertise reject <advertiseId> <bidId>
```
clishop advertise reject <advertiseId> <bidId>
```

### advertise cancel <id>
```
clishop advertise cancel <id>
```

## Support Tickets

Create and manage support tickets for order issues entirely from the CLI.

### support create <orderId>
Interactive. Prompts for category, priority, subject, message.
```
clishop support create <orderId>
```
Categories: general, damaged, missing, wrong_item, refund, shipping, other
Priorities: low, normal, high, urgent

### support list
```
clishop support list [--status <status>] [--json]
```

### support show <ticketId>
```
clishop support show <ticketId> [--json]
```

### support reply <ticketId>
Opens editor for reply.
```
clishop support reply <ticketId>
```

### support close <ticketId>
```
clishop support close <ticketId>
```

## Feedback (Bug Reports & Suggestions)

Report bugs and submit feature suggestions. Track status updates from the team.

### feedback bug
Interactive bug report. Prompts for: title, description, steps to reproduce, actual behavior, expected behavior.
```
clishop feedback bug
```

### feedback suggest
Submit a feature request. Prompts for: title, suggestion description.
```
clishop feedback suggest
```

### feedback list
List your feedback submissions with status.
```
clishop feedback list [--type <bug|suggestion>] [--json]
```

### feedback show <id>
View feedback details including admin notes and status updates.
```
clishop feedback show <id> [--json]
```

Feedback statuses: open, acknowledged, in_progress, fixed, wont_fix, closed

## Configuration

### config show
Show active agent, output format, config path.
```
clishop config show
```

### config set-output <format>
Set output format: "human" or "json".
```
clishop config set-output <format>
```

### config reset
Reset all local config to defaults.
```
clishop config reset
```

### config path
Print config file path.
```
clishop config path
```

### status
Full account overview: user, agents, addresses, payment methods.
```
clishop status [--json]
```

### setup
Re-run the setup wizard.
```
clishop setup
```

## Global Options

- `--agent <name>` — Override active agent for this command
- `--json` — JSON output (available on all read commands)
- `--version` — Show version
- `--help` — Show help

## Environment Variables

- `CLISHOP_API_URL` — Override API base URL. Default: https://clishop-backend.vercel.app/api

## ID Prefixes

- prod_ — Product (from local catalog)
- xprd_ — Extended product (from real-time vendor search)
- ordr_ — Order
- addr_ — Address
- pymt_ — Payment method
- stor_ — Store
- agnt_ — Agent

All prices are stored in cents (integer). The CLI converts for display: 7999 → $79.99.

## Error Codes

HTTP errors from backend:
- 401 — Session expired. Run `clishop login`.
- 400 — Bad request (e.g. missing country for search). Check error message.
- 404 — Resource not found.
- 422 — Validation error. Check field-level messages.
- 429 — Rate limited. Wait and retry.
- 5xx — Server error. Try again later.

CLI-side errors:
- "No shipping address set" — Run `clishop address add`. A country is required for searches.
- "Agent X does not exist" — Create it with `clishop agent create X`
- "Cannot delete default agent" — The default agent is immutable.
- "No payment method set" — Run `clishop payment add`
- "Order total exceeds limit" — Increase limit with `clishop agent update`
- "Category X is blocked" — Update agent to remove restriction.

## AI Agent Integration Guide

1. Login non-interactively: `echo "pass" | clishop login -e user@example.com --password-stdin`
2. Create an agent: `clishop agent create bot --no-confirm --max-amount 100`
3. Set the agent: `clishop agent use bot`
4. Add an address: `clishop address add` (required before searching)
5. Search with JSON: `clishop search "product" --json`
6. Get info by result number: `clishop info 1 --json`
7. Buy without prompt: `clishop buy 1 -y`
8. Check order: `clishop order show <id> --json`

All commands return structured JSON when --json is passed, suitable for parsing in any programming language or LLM tool-calling framework.

## Dark Store (Vendor Template)

Anyone can sell on CLISHOP by deploying a Dark Store. It's a config-driven vendor service:
- Define your catalog, shipping, taxes, and discounts in YAML files
- Deploy to Vercel (or any host)
- CLISHOP routes buyer orders to your store automatically
- No public website required

Source: https://github.com/DavooxBv2/CLISHOP-DARKSTORE