@artos-commerce/ucp-cli

Command-line tools for building agents on Artos (the Universal Commerce Protocol). Scaffold an agent UCP profile, run connectivity diagnostics, inspect a store's UCP profile, search the cross-store catalog, and drive a full cart → checkout → purchase flow (plus buyer-account tools) — without hand-rolling the UCP transport, headers, or signing.

It is the Build track companion to @artos-commerce/ucp-client: the CLI uses the SDK under the hood. If you only want an agent (Claude, Cursor) to shop, use the hosted Connect bridge instead — see the Artos agent docs.

Install

npm install -g @artos-commerce/ucp-cli
# or run ad hoc:
npx @artos-commerce/ucp-cli --help

Requires Node 22+. The crypto settlement rail's @mysten/sui is not needed for any CLI command.

Configuration

Every command resolves its connection from flags first, then the environment, then defaults:

| Setting | Flag | Env | Default | | --- | --- | --- | --- | | Artos API base URL | --api | ARTOS_BASE_URL | https://api.artos.sh | | Platform API key | --key | UCP_PLATFORM_API_KEY | (none — anonymous) | | Agent profile URL | --profile | PLATFORM_PROFILE_URL | (none) |

Catalog discovery is anonymous, so catalog search and discover work with no key. Cart, checkout, and purchase need a real platform key (UCP_PLATFORM_API_KEY). purchase confirm additionally needs your agent signing key (AGENT_PRIVATE_JWK + AGENT_KID) so it can mint the AP2 mandate, and account (and any buyer-bound call) needs a buyer OAuth bearer (ARTOS_BUYER_BEARER). The CLI settles the card / $0 rails; for crypto settlement, use the SDK directly.

Commands

artos init [name]

Scaffolds a runnable Build-track starter project: package.json, tsconfig.json, .env.example, and a src/index.ts wired with UcpClient, createCheckoutHandlers, createAccountHandlers, and OAuthClient (a search → checkout demo plus account-tool and buyer-OAuth examples). Refuses to overwrite a directory that already has a package.json.

artos init my-agent           # → ./my-agent
artos init my-agent --out /path/to/dir
cd my-agent && npm install && cp .env.example .env && npm start

artos profile init

Generates an EC P-256 signing keypair and a UCP profile document.

artos profile init --out ./agent-profile --url https://your-app.example/.well-known/ucp

Writes ucp.json (host it publicly at the --url) and private-jwk.json (secret — load as AGENT_PRIVATE_JWK, never commit). Prints the env vars to export.

artos doctor

Checks your connection to Artos: platform key, the API's UCP discovery profile, the OAuth Authorization Server metadata, and (when configured) your published agent profile. Exits non-zero on any failure.

artos doctor
artos doctor --api https://api.dev.artos.sh --profile https://your-app.example/.well-known/ucp

artos conformance [--store <slug>]

Runs a battery of live UCP conformance checks against a deployment: the platform discovery profile and its declared UCP version, the OAuth metadata (endpoints, PKCE S256, offline_access / purchase:complete scopes), the cross-store catalog search, the buyer-bound 401 + WWW-Authenticate relay contract, and — when a store is given — that the store publishes signing keys for AP2 verification. Exits non-zero if any required check fails (warnings don't fail the run), so it drops straight into CI. Add --json for a machine-readable report.

artos conformance --api https://api.dev.artos.sh --key "$UCP_PLATFORM_API_KEY"
artos conformance --store acme --json

artos discover --store <slug>

Fetches a store's UCP profile and prints its protocol version, signing keys, payment handlers, and capabilities.

artos discover --store about-you
artos discover --store about-you --json

artos catalog search <query>

Searches the cross-store catalog with the correct UCP headers. --max is in major units (dollars) and is converted to minor units for you.

artos catalog search "running shoes" --max 150 --currency USD
artos catalog search shoes --json

artos cart <create|view|update>

Manages a store cart. --item is repeatable and takes a variant id with an optional :quantity (default 1).

artos cart create --store about-you --item <variantId>:2 --item <variantId>
artos cart view   --store about-you --id <cartId>
artos cart update --store about-you --id <cartId> --item <variantId>:3

artos checkout <create|view|update>

Manages a store checkout. Build it from a cart (--cart) or line items (--item), and set nested fields with --set (dotted keys nest, e.g. --set shipping_address.country=US).

artos checkout create --store about-you --cart <cartId> --set shipping_address.country=US
artos checkout view   --store about-you --id <checkoutId>
artos checkout update --store about-you --id <checkoutId> --set [email protected]

artos product <view|get|lookup>

Inspects products. view fetches one product at a store, get fetches one product over the cross-store catalog (no store needed), and lookup resolves one or more products by id / handle / SKU / barcode. get and lookup are anonymous (no key); view uses the store MCP transport.

artos product view   --store about-you --id <productId>
artos product get    --id <productId>
artos product lookup <productId> <productId> --json

artos order view

Views a store order by id (get_order, store-scoped). Reading orders needs a platform key with the orders:read scope.

artos order view --store about-you --id <orderId>

artos purchase confirm

Re-prices the checkout, verifies the store's signed terms, mints the AP2 mandate, and places the order on the card / $0 rail. Needs AGENT_PRIVATE_JWK + AGENT_KID. Exit codes: 0 placed, 2 action required (escalation / pick a rail with --pay), 1 error.

artos purchase confirm --store about-you --id <checkoutId> --pay artos.card
artos purchase confirm --store about-you --id <checkoutId> --no-coupon   # strip an attached coupon

Coupon redemption runs on the crypto rail only, so it is handled by the SDK, not this card/$0 CLI — here only --no-coupon (which removes an attached coupon claim before pricing) is meaningful.

artos account <list|call> [tool]

Lists or calls buyer-account tools. Buyer-bound, so it needs ARTOS_BUYER_BEARER. The available tools are get_buyer_context, list_my_addresses, list_my_orders, get_my_order, list_my_returns, get_wallet_balances, list_my_coupons, list_my_gifts, and claim_gift.

artos account list
artos account call list_my_orders --args '{"limit":5}'
artos account call get_buyer_context --set verbose=true

Development

npm install
npm run check   # lint + typecheck + test:coverage + build

License

MIT