Status: alpha (v0.1.0). Core search, mandate, cart, and order flows work. Expect breaking changes until v1.0. Feedback welcome — open an issue.

Agent-native commerce CLI. All commands return JSON. Humans configure once; agents invoke autonomously.

pip install shop-cli
shop search products "coffee filters" --max-price 20

shop is a CLI built for AI agents as the primary user. It handles product discovery, mandate-enforced purchasing, and order tracking — with JSON output on every command and semantic exit codes agents can branch on.

Agents never see card credentials. Spending policy lives in signed mandate files, not in agent prompts.

pip install shop-cli

Requires Python 3.9+.

Choose the payment network that matches your merchants:

Stripe (works with UCP and ACP merchants):

shop payment add --label "My Visa" --stripe-key sk_live_...
# → opens browser URL for PCI-compliant card entry
shop payment confirm --session-id cs_xxx --stripe-key sk_live_...

Shop Pay (works with Shopify UCP merchants):

shop payment add-shop-pay \
  --token SHOP_PAY_TOKEN \
  --email buyer@example.com \
  --first-name Jane --last-name Smith \
  --address1 "123 Main St" --city "Portland" --province OR --zip 97201

PayPal Fastlane (works with PayPal Fastlane merchants):

shop payment add-paypal-fastlane \
  --token FASTLANE_TOKEN \
  --email buyer@example.com

Shopify Global Catalog — search across ~1M+ Shopify stores:

shop merchant connect-shopify \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

Shopify UCP checkout — agent checkout via Shop Pay at a specific Shopify store:

shop merchant add-shopify-checkout \
  --store-domain my-store.myshopify.com
# uses credentials from connect-shopify above

UCP merchant — any merchant publishing /.well-known/ucp:

shop merchant add https://store.example.com

ACP merchant — Stripe Agentic Commerce Protocol endpoint:

shop merchant add-acp https://store.example.com [--acp-key KEY]

PayPal Fastlane merchant:

shop merchant add-paypal \
  --name "Acme Store" \
  --client-id PP_CLIENT_ID \
  --client-secret PP_CLIENT_SECRET

Mandates define what an agent is allowed to buy. They're Ed25519-signed YAML files stored in ~/.shop/mandates/.

shop mandate create \
  --budget-total 500 \
  --per-order-max 50 \
  --period monthly \
  --category-allow "office supplies,coffee"

# Search
shop search products "coffee filters" --max-price 20 --in-stock-only

# Add to cart
shop cart add --sku shopify:abc123 --quantity 2

# Place order
shop order create --from-cart --idempotency-key $(uuidgen) --yes

shop supports five payment credential types. Each is stored as an opaque token in ~/.shop/payment.yaml — agents never see card numbers.

Stripe flow: shop payment add creates a Stripe Checkout Session and returns a browser URL. The user enters card details in Stripe's hosted page (PCI scope stays with Stripe). shop payment confirm polls until complete, then stores only opaque Stripe IDs.

shop payment list   # view stored methods (last4/brand/expiry only)
shop payment remove --id pm_xxx

All commands exit 0 on success and return a JSON object on stdout. Errors also return JSON with error_code, detail, and exit_code.

Search across all registered merchants in parallel.

shop search products QUERY [--max-price FLOAT] [--min-rating FLOAT] [--in-stock-only] [--explain]

{
  "results": [
    {
      "sku": "shopify:abc123",
      "title": "Arabica Coffee Filters 100-pack",
      "price": 12.99,
      "availability": "InStock",
      "confidence": 0.87
    }
  ],
  "total": 1,
  "meta": { "total_queried": 1, "failed_merchants": [] }
}

--explain adds a per-result confidence_explanation breakdown.

shop mandate create \
  --budget-total FLOAT \
  --per-order-max FLOAT \
  --period monthly|weekly|one-time \
  [--category-allow "cat1,cat2"] \
  [--category-deny "cat1,cat2"] \
  [--merchant-allow "slug1,slug2"] \
  [--merchant-deny "slug1,slug2"] \
  [--expires-at ISO8601]

shop mandate list                        # all mandates with budget utilization
shop mandate verify --mandate-id ID      # check Ed25519 signature
shop mandate usage --mandate-id ID       # live budget + pending orders

shop cart add --sku MERCHANT:SKU [--quantity 1] [--dry-run]
shop cart view [--session-id ID]
shop cart clear --yes [--session-id ID]

--dry-run validates mandate compliance and confidence scoring without writing to the database.

shop order create \
  --from-cart \
  --idempotency-key UUID \
  --yes \
  [--mandate-id ID]

shop order status --order-id ID

Every order requires --idempotency-key — safe to retry on network failure.

shop history [--last 20] [--merchant slug]

Transaction audit log from local SQLite. Never leaves the machine.

shop schema commands

Returns the full machine-readable CLI contract — all commands, flags, types, and exit codes. Agents use this for runtime capability discovery without reading docs.

Agents branch on exit codes rather than parsing error text.

Every search result includes a confidence score (0.0–1.0) computed from six signals:

Default threshold is 0.80 — results below threshold cause exit 5. Configure in ~/.shop/config.yaml:

confidence_threshold: 0.80
default_mandate: mandate-id-here
max_workers: 10

Override the config directory with SHOP_HOME=/path/to/dir — useful in read-only home environments or for testing.

# 1. Discover what's available
shop schema commands | jq '.commands[].noun' | sort -u

# 2. Create a mandate (once, at session start)
MANDATE=$(shop mandate create --budget-total 200 --per-order-max 40 --period monthly | jq -r '.mandate_id')

# 3. Search with confidence filter
shop search products "USB-C hub" --max-price 40 --in-stock-only

# 4. Validate before committing
shop cart add --sku shopify:xyz --dry-run

# 5. Place order with idempotency key
shop order create --from-cart --mandate-id $MANDATE \
  --idempotency-key $(uuidgen) --yes

import subprocess, json

result = subprocess.run(["shop", "search", "products", "coffee"], capture_output=True)
data = json.loads(result.stdout)

match result.returncode:
    case 0: process(data["results"])
    case 3: request_approval(data["detail"])   # mandate violation
    case 5: surface_to_human(data["results"])  # low confidence
    case 6: retry()                            # network error, safe to retry

Tested on Python 3.9, 3.10, 3.11, 3.12.

MIT