Quickstart¶
Install the CLI, set it up, and price out a real product without spending anything. About five minutes. At the end you can hand the same flow to Claude or another agent.
1. Install the CLI¶
Installs portage-cli and every adapter gem on Homebrew's own Ruby, so it doesn't
touch any Ruby you use for other work.
Check it worked:
Upgrading, two installs on one PATH, and the Linux keychain (secret-tool):
CLI reference § Installation.
2. Set up¶
The wizard walks through your shipping address, optional search keys, spending caps and
hand-off preferences, one skippable step at a time. It never echoes a secret back, and it
saves to ~/.portage/.env with chmod 600. Run portage doctor any time to see what's
still missing.
Prefer editing the file yourself? Set at least the country, since some stores report
in-stock items as out of stock without it. .env.example
lists every variable.
# ~/.portage/.env
PORTAGE_SHIP_STREET="1 Main St"
PORTAGE_SHIP_CITY="Erie"
PORTAGE_SHIP_COUNTRY="US"
PORTAGE_SHIP_POSTAL_CODE="16501"
Only ~/.portage/.env loads automatically
A .env in the current directory is never loaded. A cloned repo's .env could
otherwise route your traffic through its proxy or point purchases at another store
without you noticing. Use a project file on purpose with PORTAGE_ENV_FILE=.env.
Why.
3. Search and price it out¶
find works with no keys. Its default search, DuckDuckGo's keyless API, resolves brand
and store names ("burton snowboards") but not open-ended queries ("waterproof hiking
boots"). For those, add a Brave (BRAVE_SEARCH_API_KEY) or Google (GOOGLE_CSE_KEY +
GOOGLE_CSE_CX) key. Each offer comes back with its store, title, price in minor units
(52995 is $529.95) and whether the store supports automated checkout.
Now price one out. --dry-run shows the real total, shipping and tax, and never charges:
With no store URL, buy lists the offers and, in a terminal, lets you pick one. Piped or
run by an agent, it prints the offers and stops: a search ranker never chooses the store.
Have a store URL already? buy goes straight to its /.well-known/ucp manifest:
4. Buy for real¶
Before the first real purchase:
portage payment enroll https://some-ucp-store.example # stores a token, never a card number
portage policy set --per-transaction-cap 20000 --currency USD # $200.00 cap, in minor units
Then drop --dry-run and add --yes:
Most stores don't let a third party complete payment, so expect a hand-off: Portage opens
the checkout in your browser and you pay. Only "outcome": "purchased" means money moved;
every other outcome is listed in the CLI JSON reference. Hand-off
tiers and hand-off-only retailers such as Amazon: CLI reference § Tiers.
5. Let an agent do it¶
In Claude Code:
Then ask: /buy a burton snowboard under $600. Claude runs the same steps you just ran,
shows you the offers and the dry-run total, and waits for your yes. Update, removal, and
setup for Codex, Cursor, OpenCode and other agents: buy plugin.
Next steps¶
- Agentic flow tutorial: build your own agent loop around
portage. - CLI usage tutorial: store allowlists, the local store index, browser import, and what to do when search comes back empty.
- CLI reference: every command, flag and environment variable.
- Library usage and the API reference: embed Portage in a Ruby app instead of shelling out.
- Running behind a proxy.