Use the CLI

@artos-commerce/ucp-cli is the fastest way to poke at Artos from a terminal or a CI job. It is the Build-track companion to the @artos-commerce/ucp-client SDK — it speaks UCP through the SDK under the hood, so anything the CLI does, your own client can do.

Use it to scaffold a starter, verify connectivity (doctor) and protocol conformance, generate an agent profile + signing key, and run a real search → checkout → purchase flow without writing transport code.

If you only want an agent (Claude, Cursor) to shop, you don’t need the CLI — use the hosted Connect bridge. Reach for the CLI when you are building an integration.

Install


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

Requires Node 22+. The crypto rail’s @mysten/sui is not needed for any CLI command (the CLI settles the card / $0 rails; for crypto settlement use the SDK directly).

Configure

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

Setting	Flag	Env	Default
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. Cart / checkout / purchase need a platform key; purchase confirm also needs your signing key (AGENT_PRIVATE_JWK + AGENT_KID) to mint the AP2 mandate; account needs a buyer bearer (ARTOS_BUYER_BEARER). See Authentication.

Scaffold a project

artos init writes a runnable Build-track starter wired with UcpClient, createCheckoutHandlers, createAccountHandlers, and OAuthClient (a search → checkout demo plus account-tool and buyer-OAuth examples):


artos init my-agent
cd my-agent && npm install && cp .env.example .env && npm start

Generate an agent profile

artos profile init mints an EC P-256 signing keypair and the /.well-known/ucp document you host (see Profiles & trust):


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

It writes ucp.json (host it publicly) and private-jwk.json (secret — load as AGENT_PRIVATE_JWK, never commit), and prints the env vars to export.

Verify connectivity & conformance


# Your own setup: key, API, OAuth metadata, your published profile.
artos doctor
 
# The deployment's UCP contract: discovery/version, OAuth PKCE + scopes,
# catalog search, the 401 relay, and store signing keys.
artos conformance --key "$UCP_PLATFORM_API_KEY"

conformance exits non-zero on a required failure, so it drops into CI — see Conformance & CI for the full check list and a GitHub Actions guide.

Shop from the terminal

The same flow the Connect an assistant guide describes, as commands. Replace energy-sport with a store slug that exists on your target API (from catalog search results’ metadata.artos_seller.slug, or your own dashboard store):


# 1. Inspect a store's UCP profile
artos discover --store energy-sport
 
# 2. Search the cross-store catalog (price in major units / dollars)
artos catalog search "running shoes" --max 100
 
# 3. Inspect a product — globally (no key) or at a store
artos product get --id product_123
artos product lookup product_123 product_456
artos product view --store energy-sport --id product_123
 
# 4. Build a cart, then a checkout (repeat --item; dotted --set keys nest)
artos cart create --store energy-sport --item variant_123:1
artos checkout create --store energy-sport --item variant_123:1 \
  --set shipping_address.country=US --set shipping_address.postal_code=94105
 
# 5. Re-price, sign the AP2 mandate, and place the order (card / $0)
artos purchase confirm --store energy-sport --id checkout_456 --pay artos.card
 
# 6. Read an order at a store (platform key with orders:read scope)
artos order view --store energy-sport --id order_789
 
# 7. Read the buyer's orders across every store (needs ARTOS_BUYER_BEARER)
artos account list
artos account call list_my_orders

Add --json to any command for machine-readable output.

purchase confirm takes two more optional flags:

--mandate <uuid> — reference a server-side allowance (an AP2 payment_mandate id) minted ahead of time, e.g. for human-not-present flows.
--coupon / --no-coupon — apply the best available coupon or strip an attached coupon claim. Coupon redemption settles on the crypto rail, which the CLI does not drive — so on this card/$0 CLI only --no-coupon changes the outcome; use the SDK to apply coupons on crypto.

In Cursor

Install the bundled shopping skill so the agent applies Artos’s UCP rules, then drive the CLI from chat:

Copy skills/artos-ucp/ from a clone of this repo into your agent project’s skills directory.

See Local development for connecting an agent to a local dev stack.

Next steps

Catalog crawler — index the catalog read-only
Shopping agent (SDK) — the full Build-track flow
Build with the SDK — the library the CLI uses
Conformance & CI — gate a deployment in CI
Checkout — rails, AP2, coupons, $0 orders