CLISHOP Documentation

Complete reference for the CLISHOP CLI — the terminal-based shopping tool for humans and AI agents. Search products, manage orders, configure safety agents, and interact with the entire CLISHOP commerce network.

Introduction

CLISHOP is a command-line interface that lets you search, compare, and buy products from your terminal. It connects to the CLISHOP backend, which aggregates products from multiple vendor stores into a single searchable catalog.

Every command supports --json output, making it ideal for integration with AI agents, automation scripts, and LLM tool-calling pipelines. Safety is built-in through agents — configurable profiles that enforce spending limits, category restrictions, and confirmation requirements.

Key Concepts

• Agent — A safety profile that controls what the CLI can buy. Each agent has spending caps, allowed/blocked categories, and a default address + payment method.
• Store — A vendor connected to CLISHOP. Can be a Dark Store (YAML config), Shopify store, eBay store, or custom integration.
• Extended Search — Real-time search that queries vendor stores directly when local catalog results are insufficient.
• Advertise — Post a request describing what you need. Vendors bid to fulfill it.

Installation

CLISHOP requires Node.js 18+. Install globally via npm:

After installation, the clishop command is available globally.

Setup Wizard

On first run (when no subcommand is provided and setup hasn't been completed), CLISHOP automatically starts an interactive setup wizard that walks you through:

1. Account — Register or log in (by creating an account you accept the Terms & Conditions and Privacy Policy)
2. Agent — Configure a safety profile (default: $200 max per order, confirmation required)
3. Shipping Address — Add your delivery address (required — searches need a country to work)
4. Payment Method — Set up a secure payment method via the web portal
5. First Search — Try a sample product search

You can re-run the wizard anytime with:

Quickstart

After setup, here's the fastest path to placing your first order:

For AI Agents

Every command supports --json output. Combined with non-interactive flags, the CLI is fully automatable:

login

Log in to your CLISHOP account. If already logged in, you'll be asked to confirm switching accounts.

register

Create a new CLISHOP account. Always interactive — prompts for name, email, password, and confirmation.

logout

Log out and clear all locally stored tokens from the OS keychain.

Performs a best-effort server-side logout, then always clears local credentials regardless.

whoami

Display the currently logged-in user's name, email, and ID.

Agents Overview

Agents are safety profiles that control what the CLI can do. Each agent has:

• maxOrderAmount — Maximum dollar amount per order (default: $200)
• requireConfirmation — Whether to require email/web confirmation before orders are sent to the vendor (default: true)
• allowedCategories — Whitelist of product categories (empty = all allowed)
• blockedCategories — Blacklist of product categories
• defaultAddressId — Default shipping address for this agent
• defaultPaymentMethodId — Default payment method for this agent

A default agent is always present and cannot be deleted. It comes pre-configured with a $200 spending cap and order confirmation required. You can create additional agents for different use cases (e.g., "work", "personal", "automated").

agent list

List all configured agents. Active agent is marked with a green dot.

Alias: clishop agent ls

agent create

Create a new safety agent.

agent use

Switch the active agent.

agent show

Show details of a specific agent (defaults to the active agent).

agent update

Interactively update an agent's settings — spending limit, confirmation, and category restrictions.

agent delete

Delete an agent. Prompts for confirmation. Cannot delete the default agent.

Alias: clishop agent rm work

search

Search for products across all connected stores. Supports extensive filtering, sorting, and output options.

Product Match Filters

Cost Filters

Delivery Location Filters

Availability & Returns

Trust & Store Filters

Sorting, Pagination & Output

Extended Search

Currency Conversion

Search results automatically display prices converted to your local currency (determined from your delivery country). Exchange rates are fetched from the open.er-api.com service and cached for 1 hour.

product

View detailed information about a specific product by its ID.

Shows: name, price, shipping, availability, rating, reviews, category, store, return policy, and description.

info

Request detailed product information directly from vendor stores. Works with product IDs from extended search results, or result numbers from your last search.

Accepts up to 20 product IDs per request. Returns buyer-relevant data from stores including specifications, images, features, and more.

buy

Quick-buy a product by its ID or search result number. Uses the active agent's default address and payment method.

Safety Checks

Before placing an order, the CLI enforces the active agent's safety rules:

• Max order amount — Rejects if total exceeds the agent's spending cap (default: $200)
• Blocked categories — Rejects if the product is in a blocked category
• Allowed categories — Rejects if the product is not in the whitelist (when set)
• CLI confirmation — Shows order summary and prompts for confirmation (unless -y is passed)

Order Confirmation Flow

When the agent's requireConfirmation is enabled (default), orders go through this flow:

1. Payment is authorized — your card is charged immediately
2. Order is held — the order is not sent to the vendor yet
3. You receive a confirmation email — with a one-click confirm link
4. You confirm — via the email link or on the website dashboard
5. Order ships — only after confirmation is the order sent to the vendor

order list

List your orders with optional status filtering.

order show

View detailed order information including items, tracking, and live vendor status.

If the order has an external reference (e.g., eBay), the CLI fetches live tracking information including carrier, tracking number, and estimated delivery date.

order cancel

Cancel an order. Prompts for confirmation.

address list

List all addresses for the active agent. Default address is marked with a green dot.

Alias: clishop address ls

address add

Add a new shipping address. Interactive prompts for all fields. Supports business addresses with VAT number.

Address Fields

address remove

Remove an address by its ID. Prompts for confirmation.

Alias: clishop address rm addr_xxx

address set-default

Set the default shipping address for the active agent.

payment list

List payment methods for the active agent.

Alias: clishop payment ls

payment add

Add a payment method. Opens a secure web link — card details are never entered in the CLI.

payment remove

Remove a payment method by ID.

Alias: clishop payment rm pay_xxx

payment set-default

Set the default payment method for the active agent.

review order

Review all items and the store from a specific order. Interactive — prompts for rating (1-10), title, and body for each item.

Automatically fetches which items and stores are reviewable. Already-reviewed items are skipped.

review add

Write a review for a specific product.

review store

Write a review for a store.

review list

List all your product and store reviews.

Alias: clishop review ls

review rating

View rating details for a product or store, including Bayesian average and rating cap info.

review delete

Delete one of your reviews.

Alias: clishop review rm

store list

List available stores in the CLISHOP network.

store info

View detailed store information by name, slug, or ID.

store catalog

Browse a specific store's product catalog with search and filters.

Advertise Overview

When you can't find what you need through search, you can advertise a request. This publishes your requirements to all vendors in the CLISHOP network, who can then bid to fulfill it.

Think of it as a reverse marketplace — you describe what you want, and vendors compete to offer the best price and terms.

advertise create

Create a new advertised request through an interactive wizard.

Prompts for: product title, description, SKU, brand, features, quantity, recurring preference, max bid price, delivery speed, return requirements, delivery address, and accepted payment methods.

advertise quick

Quickly advertise a request using flags (non-interactive).

advertise list

List your advertised requests.

advertise show

View an advertised request and all its vendor bids.

advertise accept

Accept a vendor's bid on your request. All other bids are automatically rejected.

advertise reject

Reject a specific vendor bid.

advertise cancel

Cancel an advertised request entirely.

support create

Create a support ticket for an order issue.

Prompts for category, priority, subject, and detailed message.

Ticket Categories

Priority Levels

support list

List your support tickets.

support show

View a ticket and its full message history.

support reply

Reply to a support ticket. Opens your default editor for composing the message.

support close

Close a resolved ticket.

Feedback Overview

Found a bug? Have an idea to make CLISHOP better? The feedback command lets you report bugs and submit suggestions directly from the terminal. The CLISHOP team reviews all feedback and keeps you updated on progress.

• Bug reports — Describe what went wrong, how to reproduce it, and what you expected to happen. Structured fields help us fix issues faster.
• Suggestions — Share feature ideas, improvements, or any other feedback to help shape CLISHOP's future.

Each submission gets a status that you can track:

feedback bug

Report a bug. Interactive prompts walk you through providing a clear bug report with structured fields.

You'll be prompted for:

feedback suggest

Submit a feature request or suggestion.

You'll be prompted for:

feedback list

List all your submitted bug reports and suggestions, with current status for each.

feedback show

View the full details of a specific feedback item, including any status updates or admin notes.

When the team updates the status of your feedback (e.g., marking a bug as fixed), you'll see the new status and any admin notes here.

config show

Display current CLI configuration: active agent, output format, and config file path.

config set-output

Set the default output format for all commands.

Valid values: human (formatted terminal output) or json (structured JSON).

config reset

Reset all local configuration to defaults. This removes all agents, resets the output format, and clears the active agent.

config path

Print the absolute path to the local config file.

status

Show a full account overview: user info, all agents with their addresses and payment methods.

This is the most comprehensive command to see everything at a glance — your user info, all agents, their addresses, and payment methods in one view.

MCP Server

CLISHOP ships as a native Model Context Protocol (MCP) server. Every Claude Desktop, Cursor, Windsurf, or other MCP-compatible AI client gets access to 19 shopping tools out of the box.

The MCP server uses the same authentication and configuration as the CLI — it reads from the OS keychain and local config. Log in once with clishop login, and every MCP client on your machine can use the tools.

How it works

The MCP server runs over stdio — the MCP client spawns the process and communicates via JSON-RPC over stdin/stdout. No HTTP server, no ports, no firewall configuration needed.

There are three ways to start the MCP server:

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your workspace:

Or if installed globally:

After saving, the CLISHOP tools will appear in Copilot's tool list. Ask Copilot things like "Search for USB-C cables under $20".

Claude Desktop

Add to your claude_desktop_config.json (find it via Claude Desktop → Settings → Developer → Edit Config):

Or if you've installed CLISHOP globally:

After saving, restart Claude Desktop. You'll see CLISHOP tools appear in the 🔧 Tools icon. Now you can ask Claude things like:

• "Search for wireless earbuds under $50 with free shipping"
• "Show me my recent orders"
• "Buy product prod_xxx"
• "What stores sell mechanical keyboards?"
• "Add my office address: 123 Main St, Amsterdam, NL"

Cursor

Add to .cursor/mcp.json in your project root (or global config):

Windsurf

Add to ~/.windsurf/mcp.json:

Available Tools

The MCP server exposes 19 tools that mirror the full CLI surface:

Safety & Agent Controls

The MCP server enforces the same safety guardrails as the CLI. The active agent's configuration is checked before every purchase:

• Spending limits — Orders exceeding the agent's maxOrderAmount are rejected
• Category rules — Blocked categories are enforced; allowed-category whitelists are respected
• Default address & payment — The agent's defaults are used automatically when not specified

To configure safety limits, use the CLI: clishop agent update or clishop agent create shopping-bot --max-amount 50.

Error Codes

The CLI uses standard HTTP status codes from the backend. Here are the most common errors you may encounter:

CLI-Side Errors

Global Options

These options can be used with any command:

FAQ

What is CLISHOP and who is it for?

CLISHOP is a command-line shopping tool for anyone who prefers the terminal over clicking through websites. It's also built specifically for AI agents — Claude, GPT, Cursor, Windsurf, and others can use it as an MCP server to place real orders on your behalf. You set the safety limits, and the agent does the shopping.

Is CLISHOP free to use?

Yes. Installing and using the CLI is free. You pay for the products you order (through the vendor), plus any applicable platform fee at checkout. There is no subscription and no upfront cost.

Which countries are supported?

CLISHOP works in any country that the connected stores ship to. When you add a shipping address, searches automatically filter to products that ship to your location. Coverage depends on the stores in the network — some ship worldwide, some only to specific regions.

What happens after I place an order?

By default, every order requires your confirmation before anything ships. Once you place an order:

1. Payment is authorized immediately.
2. You receive a confirmation email with a one-click link.
3. After confirmation, the order is forwarded to the vendor for fulfillment.
4. You can track progress with clishop order show <id>.

You can disable confirmation per-agent with --no-confirm if you trust your automation.

I got an order wrong — can I cancel it?

Yes, if the order hasn't been confirmed yet, it won't have been sent to the vendor — just don't confirm it and it will expire. If already confirmed, run clishop order cancel <id>. Whether cancellation is accepted depends on the vendor's policy. For issues after shipping, use clishop support create <orderId>.

Can I sell my own products on CLISHOP?

Yes. Deploy a Dark Store — a config-driven vendor template. Define your catalog, shipping zones, and pricing in YAML files, deploy to Vercel (or any host), and CLISHOP routes buyer orders to you automatically. No public website required.

Do I need a shipping address before I can search?

Yes. A country is required for every search so CLISHOP can filter to products that actually ship to you. Add one during setup (clishop setup) or any time with clishop address add.

How do I use CLISHOP with an AI agent / LLM?

The recommended way is via the MCP server. Add CLISHOP to your Claude Desktop, Cursor, or Windsurf config and the AI gets 19 shopping tools automatically. See the MCP Server section for setup.

Alternatively, every command supports --json for structured output. Use non-interactive login (-e / -p flags), skip confirmations with -y, and create a dedicated agent with --no-confirm for fully automated workflows.

Where is my config file stored?

Run clishop config path to find it. Typically at ~/.config/clishop/config.json on Linux/macOS.

How do I reset everything?

Run clishop config reset to reset local settings, then clishop logout to clear credentials.

What is extended search?

Extended search queries vendor stores directly in real-time. It auto-triggers when no local catalog results are found. You can force it with -e or disable it with --no-extended-search. It has a configurable timeout (default 30s, max 60s).

How do I use the --ship-to flag?

Pass a saved address label (e.g., --ship-to Home) or address ID. The CLI resolves the address's country, city, and postal code to geo-target search results.

Can I buy products from extended search results?

Yes. Use clishop buy <product-id> with the ID from extended search results (prefixed with xprd_), or just use the result number: clishop buy 1. The CLI first tries the local catalog, then falls back to extended products.

What is an advertise request?

When search doesn't return what you need, clishop advertise create lets you post a request. Vendors see it and can bid to fulfill your order. It's a reverse marketplace where vendors compete for your business.

Is my payment information secure?

Yes. The CLI never handles raw card details. Payment setup happens through a secure web portal. Locally, authentication tokens are stored in the OS keychain (macOS Keychain, Windows Credential Store, or Linux Secret Service).

How does the rating system work?

Ratings are on a 1-10 scale. The system uses Bayesian averaging with rating caps based on order volume. New stores need more orders to unlock higher ratings (100+ for 8.0+, 1000+ for 9.0+).

How do I report a bug or suggest a feature?

Use clishop feedback bug to report bugs or clishop feedback suggest for feature ideas. You can track the status of all your submissions with clishop feedback list. The team reviews every submission and updates the status as work progresses.