CLI

This is Claude Code and the sangria CLI in your terminal. Using Claude in the browser or desktop app? See Claude.

1. Install the CLI and skill

In Claude Code, paste this URL and let Claude run it:

https://getsangria.com/skill

Claude fetches the Sangria setup skill, globally installs the sangria CLI, and installs the sangria skill into ~/.claude/skills/. Re-paste the same URL anytime to update to the latest version.

command -v npm >/dev/null 2>&1 || { echo "npm not found. Install Node.js (which bundles npm) from https://nodejs.org/ and re-run." >&2; exit 1; }

npm install -g @sangria-sdk/cli

mkdir -p ~/.claude/skills/sangria
curl -fsSL https://getsangria.com/skills/sangria/SKILL.md -o ~/.claude/skills/sangria/SKILL.md

curl -o overwrites in place, so re-running the commands updates the skill.

The skill should now appear in Claude Code — look for sangria in /skills.

The CLI should also work:

sangria --help

Sign in at getsangria.com, then generate an agent API key from your dashboard — this is a dashboard agent, the one kind whose key you hold and can revoke yourself. Agent keys start with sg_agents_. The same key authenticates both discovery and buying.

3. Save your key

Save the key with the CLI:

sangria auth set "sg_agents_…"

Verify it works by checking your balance:

sangria auth status

You can also set SANGRIA_API_KEY if you prefer environment variables. The CLI resolves credentials in this order: the --api-key flag first, then saved CLI config, then SANGRIA_API_KEY — so a saved key wins over the environment variable, and the flag wins over both.

Saved config lives at $XDG_CONFIG_HOME/sangria/config.json when XDG_CONFIG_HOME is set, and ~/.config/sangria/config.json otherwise.

4. Make your first purchase

Just ask your agent in plain language:

Buy me decaf espresso pods that work with a Nespresso machine.

Behind the scenes:

The sangria skill finds matches and a price-locked quote (valid ~45 minutes).
Your agent shows you each match's item price, estimated tax, and estimated total, and asks for the go-ahead.
The sangria skill commits the chosen match, charges your credits the total, and returns the merchant's confirmation.

If the quote lapses before you approve, your agent re-discovers for a fresh price before buying. Buying draws from your credit balance and there's no overdraft, so top up from your dashboard before your first purchase.

Discovery has two modes

Intent mode searches by description and returns up to 5 matches:

sangria discover "decaf espresso pods nespresso compatible" \
  --reasoning 'Everyday morning coffee, $20-50 range.' \
  --max-price 50 --json

URL mode quotes one specific product:

sangria discover --url "https://www.amazon.com/dp/B07Q7S4HDJ" --json

The URL must be a product page (/dp/<ASIN> or /gp/product/<ASIN>) on the Amazon marketplace for your country — not a search or category page. Amazon short links (a.co, amzn.to, amzn.asia) work here too and are resolved to the canonical product page automatically.

The two modes are mutually exclusive: pass an intent or a --url, never both.

Quote example strings carefully

In bash, double quotes expand $. --reasoning "Decaf pods, $20-50 range." reaches the API as Decaf pods, -50 range., because $2 expands to an empty positional argument. Single-quote any string containing a literal $, backtick, or backslash. Variables you want expanded — "$DISCOVERY_ID", "$SKU" — stay double-quoted.

Command reference

sangria auth status [--json]
sangria auth set <api_key>
sangria auth unset
sangria balance [--json]
sangria settings show [--json]
sangria settings set-phone <phone> [--json]
sangria settings update [--country <US|SG>] [--line1 <line1>] [--line2 <line2>] [--city <city>] [--state <state>] [--postal-code <code>] [--json]
sangria discover <intent> --reasoning <text> [--context <json>] [--min-price <amount>] [--max-price <amount>] [--json]
sangria discover --url <product_url> [--context <json>] [--json]
sangria buy <discovery_id> <sku> [--json]
sangria orders [--limit <n>] [--cursor <next_cursor>] [--scope <key|operator>] [--json]
sangria topup --amount <amount> [--json]
sangria topup confirm <topup_id> --code <code> [--json]

Discover flags — intent mode

Flag	What it does
`--reasoning <text>`	Short explanation of why this purchase fits the request. Required.
`--context <json>`	Optional free-form JSON with situation context.
`--min-price <amount>`	Inclusive lower bound in your account currency, e.g. `--min-price 20`.
`--max-price <amount>`	Inclusive upper bound in your account currency, e.g. `--max-price 49.99`.

Discover flags — URL mode

Flag	What it does
`--url <product_url>`	Product-page URL to look up one specific product. Mutually exclusive with the intent-mode flags and the positional intent.

Orders flags

Flag	What it does
`--limit <n>`	Orders per page. Default 20, max 100; higher values are clamped. A page never splits a multi-item order — when the cut would land mid-order, the page runs past the limit to that order's end.
`--cursor <cursor>`	Continue from a prior response's `next_cursor`.
`--scope <scope>`	`key` (default) lists this key's orders; `operator` lists every order on the account, across all keys and connectors.

Each order row carries its sku and canonical product_url — re-order a past item by running URL discovery on that link for a fresh quote — and a batch_id that is non-null when the item was bought as part of one multi-item purchase (members of the same purchase share it and list adjacently).

Rows also carry estimated_delivery_date, carrier and tracking_id. Each is null until that detail is known: an order typically gets its delivery estimate first and a tracking number only once it ships, so an order in an earlier state legitimately has none. estimated_delivery_date is a plain calendar day such as 2026-08-12 — no time, no timezone — so read it as that date and don't convert it.

--json returns all three exactly as stored, on every order. The human-readable output is narrower: it prints them on a second line under the order, and shows each one only while the order's status still makes it meaningful. The delivery estimate appears on confirmed, placed and shipped orders — once an order is delivered the estimate has been superseded by what actually happened, and on a cancelled or refunded order it is a promise no longer being made. The carrier and tracking number appear on those three and on delivered, cancelled and refunded as well: a tracking number records a real package, stays accurate once issued, and is still what you need to follow a delivered parcel or send back one you cancelled. A running or failed order shows neither, and when nothing survives the CLI prints no extra line at all.

Global flags

Flag	What it does
`--json`	Print machine-readable JSON.
`--api-key <key>`	Override the saved config and `SANGRIA_API_KEY`.
`--base-url <url>`	Override `SANGRIA_URL` or the default API URL.
`--version`	Print the CLI version and exit.
`--verbose`	Print extra diagnostics to stderr.

Amounts and currency

--json responses report money as integer microunits: 1 unit = 1,000,000 microunits, so 6250000 is $6.25. Amounts you pass on the command line are ordinary decimals in your account currency — --max-price 49.99, --amount 25.

Your currency follows your country, and is reported alongside your balance. It's null until you set a country, which is also the point at which discovery starts working — set it with sangria settings update --country <US|SG> --postal-code <code>.

Want the full detail — how to write intent versus --reasoning, order statuses, every error code and its recovery? It's all in SKILL.md, the file your agent loads at runtime.