UCP CLI

A Go CLI for Google's Universal Commerce Protocol — talk to UCP merchants over REST or MCP, search across them in parallel, build carts, and prep checkout drafts that an AP2 CLI can authorize.

UCP-pp-cli is the terminal-grade tool the official Python and JS SDKs don't ship. It speaks both REST and MCP transports so it works against real merchants like checkout.coffeecircle.com (Shopify-hosted, MCP-only) and the bundled mock. Local SQLite holds carts, checkout sessions, and a merchant directory, enabling cross-merchant search, capability diffs, and price-drift watch loops nothing else offers today.

Created by @beetz12 (david).

Real-Merchant Compatibility

v0.1 supports two interaction patterns against UCP merchants:

Command	Real merchants (e.g. checkout.coffeecircle.com)	Bundled mock (mock serve)
check <domain>	✅ Works against any merchant publishing /.well-known/ucp	✅
search / cart / checkout prep	⚠️ Requires REST transport. Most public real merchants advertise MCP-only — those are deferred to v0.2 (MCP client + hosted agent profile + ECDSA-P256 signing)	✅ Full end-to-end flow

Known real merchants that publish a UCP manifest today: checkout.coffeecircle.com (Shopify-hosted, MCP-only). Etsy and Wayfair have UCP-powered checkout via Google AI Mode but their endpoints are gated to approved Google agents. v0.2 will add MCP transport client support to unlock real-merchant transactions.

Authentication

UCP has no global API key. Each merchant declares its own auth shape; the CLI identifies itself via the UCP-Agent: profile="<url>" header and signs requests with a per-agent ECDSA-P256 key. Run ucp profile init once to generate your profile. For account-linked flows, ucp auth link <merchant> walks an OAuth 2.0 flow per merchant (v1: print-mode — agent pastes the redirect URL back).

Quick Start

Real shopping in 3 commands — no mock, no setup, no API key.

# List the dog/pet merchants seeded in the registry
ucp-pp-cli merchants list --rope-toys

# Search bark.co for rope toys (returns real products)
ucp-pp-cli search "rope toy" --merchant bark.co --limit 5 --json

# Add a real product to a local cart and prep a checkout draft
ucp-pp-cli cart add --merchant bark.co --sku BRK-001 --title "Corn Dog Tug" --price 999 --qty 1
ucp-pp-cli checkout prep --cart $(ucp-pp-cli cart list --json | jq -r '.[0].id') --json

The CLI ships with a seeded registry of 58 Grade-A UCP merchants (Shopify-hosted, verified 2026-05-24). Browse with ucp-pp-cli merchants list or filter with --category pet|fashion|beauty|....

Unique Features

These capabilities aren't available in any other tool for this API.

Cross-merchant discovery

• check — Fetch /.well-known/ucp for any domain and return a graded report covering schema validity, advertised transports, and capability coverage — works against any merchant publishing a UCP manifest, including MCP-only Shopify-hosted stores.

  Lets an agent screen a domain for UCP viability without standing up an SDK or hand-rolling manifest parsing.

  ucp-pp-cli check checkout.coffeecircle.com --json
  

Reachability mitigation

• mock serve — Spawn a UCP-compliant reference merchant locally (pure-Go, no external runtime) so ucp check, search, cart, and checkout prep flows work end-to-end without a third-party UCP merchant or extra language toolchains.

  Lets an agent verify its UCP integration without coordinating with a live merchant or waiting for Google AI Mode approval.

  ucp-pp-cli mock serve --port 8080
  

Recipes

Boot a UCP test environment from scratch

ucp-pp-cli mock serve --port 8080  # run in background with & or a separate terminal
ucp-pp-cli profile init
ucp-pp-cli check 127.0.0.1:8080 --json

Three commands to a working UCP-merchant-agent pair — useful for tests and demos.

End-to-end search-to-checkout against the mock merchant

ucp-pp-cli mock serve --port 8080  # run in background with & or a separate terminal
ucp-pp-cli search "coffee" --merchant 127.0.0.1:8080 --limit 5 --json
ucp-pp-cli cart add --merchant 127.0.0.1:8080 --sku coffee_001 --title "Coffee" --price 1500 --qty 2
ucp-pp-cli cart list --json
ucp-pp-cli checkout prep --cart <cart-id> --json

Full buy-side flow from product discovery to a checkout draft, entirely local.

Validate a real UCP merchant manifest

ucp-pp-cli check checkout.coffeecircle.com --json

Fetches and validates the merchant's /.well-known/ucp manifest. Note: Shopify-hosted merchants like coffeecircle.com advertise MCP-only transport; REST calls will fail until v0.2 adds MCP transport client support.

Usage

Run ucp-pp-cli --help for the full command reference and flag list.

Commands

checkout

Operations on checkout

• ucp-pp-cli checkout - POST /checkout

Output Formats

# Human-readable table (default in terminal, JSON when piped)
ucp-pp-cli checkout

# JSON for scripting and agents
ucp-pp-cli checkout --json

# Filter to specific fields
ucp-pp-cli checkout --json --select id,name,status

# Dry run — show the request without sending
ucp-pp-cli checkout --dry-run

# Agent mode — JSON + compact + no prompts in one flag
ucp-pp-cli checkout --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Explicit retries - add --idempotent to create retries when a no-op success is acceptable
• Confirmable - --yes for explicit confirmation of destructive actions
• Piped input - write commands can accept structured input when their help lists --stdin
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

ucp-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/ucp-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
API_TOKEN	per_call	Yes	Set to your API credential.

Troubleshooting

Authentication errors (exit code 4)

• Run ucp-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $API_TOKEN Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• ucp check returns HTTP 404 — The domain hosts a UCP docs site, not a UCP merchant. Confirm the merchant publishes /.well-known/ucp; many real-world UCP retailers (Etsy, Wayfair) are gated to approved Google/Microsoft agents and won't respond to unapproved profiles.
• request fails with 'unsupported transport' — The merchant only advertises MCP (e.g., coffeecircle.com). Re-run with --transport mcp or omit; the CLI picks the negotiated intersection automatically.
• checkout prep fails with 'missing identity_linking' — Run ucp auth link <merchant> first, or skip account-linking with --guest if the merchant allows guest checkout (declared in its manifest).
• mock serve fails with 'address already in use' — Port 8080 is taken. Pass --port 9090 (or any free port) and update downstream commands to point at the new address.

Sources & Inspiration

This CLI was built by studying these projects and resources:

• Universal-Commerce-Protocol/samples — Python (206 stars)
• Universal-Commerce-Protocol/python-sdk — Python (76 stars)
• Universal-Commerce-Protocol/js-sdk — TypeScript (37 stars)
• dhananjay2021/ucp-go-sdk — Go (1 stars)
• OmnixHQ/ucp-client — TypeScript
• awesomeucp/ucp-doctor — TypeScript
• davillafer/UCP-Compliance-Checker — TypeScript
• Upsonic/UCP-Agent — Python

Generated by CLI Printing Press

v1.2 additions

• Native UCP MCP-over-HTTP transport — --transport mcp calls tools/call via JSON-RPC against *.myshopify.com/api/ucp/mcp endpoints with the agent profile URL in the JSON-RPC body. Default profile: https://www.igvita.com/ucp/profile.json. Override with --profile-url.
• Real Shopify cart-add + AP2 envelope — checkout finalize --cart <id> calls anonymous https://<merchant>/cart/add.js for the first line item, then constructs the three AP2 mandates (intent, cart, payment) into a FinalizationEnvelope JSON. Payment completion is deferred — the envelope is meant to be piped into an external AP2 CLI (e.g. ap2-pp-cli) that holds the real Google Pay token and POSTs checkout-sessions/{id}/complete. Multi-item live cart-add is v1.3.

v1.3 adapters (non-UCP merchants)

For merchants that haven't enrolled in UCP, the CLI ships native adapters so the same search command works against them.

Etsy (Open API v3)

export ETSY_API_KEY=<your-key>  # https://www.etsy.com/developers/your-apps
ucp-pp-cli search "dog rope toy" --merchant etsy.com --limit 5 --json

eBay (Browse API)

export EBAY_APP_ID=<your-app-id>
export EBAY_CERT_ID=<your-cert-id>  # https://developer.ebay.com/my/keys
ucp-pp-cli search "dog rope toy" --merchant ebay.com --limit 5 --json

Both adapters return the same SearchHit shape as UCP/Shopify merchants, so the rest of the flow (cart, checkout prep) works identically.

Known Gaps (v1.3)

• Payment completion — checkout finalize builds the envelope but does not sign mandates or call the merchant's POST /checkout-sessions/{id}/complete. Requires a real Google Pay token and an AP2 CLI with signing keys. Out of scope for v1.2.
• Multi-item live cart-add — checkout finalize only adds the first line item live to the merchant; the rest live in the local cart and the AP2 cart_mandate. Multi-add in a single Shopify call is v1.3.
• Cross-merchant carts — One cart, one merchant per the UCP cart capability spec. Optimizing a wishlist across N merchants is v1.3+.
• Identity-linking OAuth — auth link flow not implemented; live MCP requests use anonymous catalog reads only.
• Webhook receiver / order watch loop — deferred to v1.3.
• Rye aggregator evaluation — research deliverable (okt6).

The bundled ucp mock serve provides a pure-Go reference merchant for end-to-end testing of the REST flow without external dependencies (hidden from --help; use ucp-pp-cli mock serve --port N explicitly).