{"id":51633699,"url":"https://github.com/rnwolfe/rivr","last_synced_at":"2026-07-13T11:31:08.358Z","repository":{"id":367128264,"uuid":"1279382801","full_name":"rnwolfe/rivr","owner":"rnwolfe","description":"A read-only Amazon Shopping CLI built for AI agents — one normalized schema over SerpApi, Rainforest, the official Creators API, or keyless scraping.","archived":false,"fork":false,"pushed_at":"2026-06-24T17:33:03.000Z","size":1019,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T18:14:02.849Z","etag":null,"topics":["affiliate","agent-cli","ai-agents","amazon","cli","go","golang","llm-tools","read-only","web-scraping"],"latest_commit_sha":null,"homepage":"https://rivr.sh","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rnwolfe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-24T16:27:25.000Z","updated_at":"2026-06-24T17:33:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rnwolfe/rivr","commit_stats":null,"previous_names":["rnwolfe/rivr"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rnwolfe/rivr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnwolfe%2Frivr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnwolfe%2Frivr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnwolfe%2Frivr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnwolfe%2Frivr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rnwolfe","download_url":"https://codeload.github.com/rnwolfe/rivr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnwolfe%2Frivr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35421716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["affiliate","agent-cli","ai-agents","amazon","cli","go","golang","llm-tools","read-only","web-scraping"],"created_at":"2026-07-13T11:31:03.752Z","updated_at":"2026-07-13T11:31:08.344Z","avatar_url":"https://github.com/rnwolfe.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# rivr\n\n**A read-only Amazon Shopping CLI built for AI agents.**\n\nAmazon's Product Advertising API was retired in 2026 and no agent-safe replacement existed —\nso `rivr` is one. Search products, fetch detail/offers/reviews/variations through **one\nnormalized schema** over a pluggable backend (SerpApi, Rainforest, the official Amazon\nCreators API, or keyless scraping), with the [Agent CLI Guidelines](https://aclig.dev/) baked\nin: read-only by default, structured errors + stable exit codes, bounded JSON, prompt-injection\nfencing, and stdin/keyring secrets.\n\n[![ci](https://github.com/rnwolfe/rivr/actions/workflows/ci.yml/badge.svg)](https://github.com/rnwolfe/rivr/actions/workflows/ci.yml)\n[![release](https://img.shields.io/github/v/release/rnwolfe/rivr?sort=semver)](https://github.com/rnwolfe/rivr/releases/latest)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Agent CLI Guidelines v0.4.0: Full](https://aclig.dev/badge/agent-cli-guidelines-full.svg)](https://aclig.dev/conformance/)\n\n![rivr demo](./demo/rivr.gif)\n\n\u003c/div\u003e\n\n## Why rivr\n\n- **Read-only by design.** No cart, no checkout, no mutations. Every result is structured data\n  plus a canonical `/dp/\u003cASIN\u003e` deep link — the hand-off point where a human buys in their\n  browser. There's no destructive action for an agent to misfire.\n- **Built for agents, not just humans.** `--json` everywhere, `schema --json`, an embedded\n  `agent` guide, `{error,code,remediation,retryAfterSeconds}` errors, a stable exit-code table,\n  and `--limit`/`--select` so responses stay within an agent's context budget.\n- **Prompt-injection fenced.** Titles, descriptions, and review text are attacker-controllable;\n  rivr wraps them `‹untrusted›…‹/untrusted›` by default.\n- **Pluggable backend, one schema.** Swap SerpApi ↔ Rainforest ↔ Creators ↔ scrape without\n  relearning fields. `rivr provider list --json` describes each backend's capability/cost/risk.\n\n## Install\n\n```bash\n# Homebrew (macOS / Linux) — recommended\nbrew install rnwolfe/tap/rivr\n\n# Go (any platform; static, no CGO)\ngo install github.com/rnwolfe/rivr/cmd/rivr@latest\n\n# Shell script (macOS / Linux) — downloads a release binary, verifies its SHA-256, installs to ~/.local/bin\ncurl -fsSL https://rivr.sh/install.sh | sh\n```\n\nOr grab a prebuilt binary (linux/macOS/windows, amd64/arm64) from\n[Releases](https://github.com/rnwolfe/rivr/releases) — each ships with checksums, an SBOM,\nand build-provenance attestation.\n\n## Quickstart (first success in \u003c60s, no account)\n\n```bash\n# the offline 'stub' backend returns fixtures — no key, no network\nRIVR_PROVIDER=stub rivr search \"usb-c cable\" --json\nRIVR_PROVIDER=stub rivr provider list --json --select name,keyless,hostedSafe,reviewsScope\nrivr schema | jq '{read_only: .safety.read_only, exit_codes}'\n```\n\nThen point it at real data — the lowest-friction path is SerpApi's free tier:\n\n```bash\n# one-time, key read from stdin (never argv)\nprintf %s \"$SERPAPI_KEY\" | rivr auth login --provider serpapi\nrivr search \"mechanical keyboard\" --prime --min-rating 4 --json\nrivr item get B0XXXXXXX --detailed --json\n```\n\nNo key at all? On a **home/residential** connection you can use the keyless scraper\n(opt-in, Amazon-ToS caveats apply — see the backend matrix): `RIVR_SCRAPE_ENABLE=1 rivr\n--provider scrape search \"usb-c cable\" --json`.\n\n## Providers \u0026 authentication\n\n`rivr` normalizes one schema across backends; pick with `--provider` (or `RIVR_PROVIDER`).\nSecrets are read from **stdin** (never argv) and stored in the OS keyring, with a `0600` file\nfallback (`RIVR_KEYRING=file` forces it on headless boxes).\n\n| Provider | Get a credential | Notes |\n|---|---|---|\n| **serpapi** (default) | sign up → [serpapi.com/manage-api-key](https://serpapi.com/manage-api-key) → `printf %s \"$KEY\" \\| rivr auth login --provider serpapi` | renewing free tier (~250/mo); reviews are a page **sample** |\n| **rainforest** | [Traject Data](https://trajectdata.com/) dashboard → `printf %s \"$KEY\" \\| rivr auth login --provider rainforest` | **full** paginated reviews + real offers |\n| **creators** (official) | Associates Central → Tools → Creators API → `printf '%s\\n%s' \"$ID\" \"$SECRET\" \\| rivr auth login --provider creators` | needs an approved Associate w/ ≥10 sales/30d, else `ASSOCIATE_NOT_ELIGIBLE`; no review text |\n| **scrape** (keyless) | `RIVR_SCRAPE_ENABLE=1` (opt-in) | **home/residential only** — modest throttled requests; ToS risk + fragile. Don't run from cloud/hosted IPs (→ use `creators`). |\n\n### Capability / cost / risk at a glance\n\n| backend | keyless | hosted-safe | reviews | cost | headline risk |\n|---|:--:|:--:|:--:|---|---|\n| **serpapi** (default) | ✗ | ✓ | sample | free tier + paid | paid beyond free tier; sample reviews |\n| **rainforest** | ✗ | ✓ | full | paid (~$25/mo+) | paid per request |\n| **creators** (official) | ✗ | ✓ | none | free* | *needs eligible Associate; no review text |\n| **scrape** | ✓ | ✗ residential | none | free | Amazon ToS + blocking; no review text; home use only |\n| **stub** | ✓ | ✓ | fake | free | not real data (testing) |\n\nFull matrix + \"which should I use?\" → **[docs/backends.md](./docs/backends.md)**. Machine-readable\nfor agents: `rivr provider list --json`.\n\n`rivr auth status --json` tests the active provider; `rivr auth logout` removes **local** creds\nonly (revoke at the provider to invalidate server-side); `rivr doctor --json` runs full\ndiagnostics. A missing credential returns `AUTH_REQUIRED` (exit 4) naming the login command.\n\n## Commands\n\n```bash\nrivr search \u003cquery\u003e          # keyword search (--category --prime --min-rating --min/max-price --sort)\nrivr item get \u003cASIN\u003e...      # product detail (--detailed adds bullets/specs)\nrivr item offers \u003cASIN\u003e      # live offers / buybox / availability\nrivr item compare \u003cASIN\u003e...  # side-by-side + best-of summary (cheapest/highest-rated/most-reviewed)\nrivr reviews \u003cASIN\u003e          # customer reviews (scope: full | sample)\nrivr variations \u003cASIN\u003e       # size/color/style variations\nrivr browse \u003cnode-id\u003e        # category (browse-node) tree  [creators only]\nrivr provider list           # backends + capability/cost/risk\nrivr auth login|status|logout|refresh\nrivr doctor                  # diagnostics\nrivr schema                  # machine-readable command tree, flags, exit codes, safety\nrivr agent                   # print the embedded agent guide (SKILL.md)\nrivr version [--check]       # installed version; --check pulls GitHub for the latest release\n```\n\n\u003e rivr never auto-updates. On the human path it prints a once-a-day upgrade hint to stderr\n\u003e (silent for agents; disable with `RIVR_NO_UPDATE_CHECK=1`).\n\nGlobal flags: `--json`/`--format json|plain|tsv`, `--select a,b.c`, `--limit N`, `--detailed`,\n`--provider`, `--associate-tag`/`--no-associate-tag`, `--no-wrap-untrusted`, `--no-input`.\n\n## Exit codes\n\n`0` ok · `2` usage · `3` empty results · `4` auth required · `5` not found ·\n`6` permission / `ASSOCIATE_NOT_ELIGIBLE` · `7` rate limited / blocked · `8` retryable ·\n`9` upstream / schema drift · `10` config · `11` unsupported by provider · `13` input required.\nFull table: `rivr schema`.\n\n## Conformance\n\nrivr conforms to the [Agent CLI Guidelines](https://aclig.dev/) **v0.4.0** at the **Full**\nlevel. The contract version is machine-verifiable from the binary — `rivr schema` emits a\n`conformance` block, so an agent can confirm the standard it was built against without\ntrusting this README:\n\n```json\n{\n  \"conformance\": {\n    \"level\": \"Full\",\n    \"spec\": \"agent-cli-guidelines\",\n    \"version\": \"0.4.0\"\n  }\n}\n```\n\n## Affiliate attribution (how rivr is funded)\n\nProduct deep links are tagged with an Amazon Associates ID by default — if a referred link\nleads to a purchase, Amazon pays the project a small referral fee, **the buyer pays nothing\nextra**. It's fully transparent and in your control: the active tag is in every `url`, in\n`rivr doctor`, and in `rivr schema`. Use your own with `--associate-tag \u003cid\u003e`, or disable with\n`--no-associate-tag`.\n\n_As an Amazon Associate the maintainer earns from qualifying purchases._\n\n## Safety\n\n- **Read-only.** No cart/order/mutation surface; the deep link is the action boundary.\n- **Untrusted text fenced** by default (`--no-wrap-untrusted` to disable).\n- **Secrets** via stdin/env → OS keyring (`0600` file fallback); never argv; redacted in output.\n\nSee [SECURITY.md](./SECURITY.md) for the secret-handling threat model.\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) and [AGENTS.md](./AGENTS.md). Build/test:\n`go build ./... \u0026\u0026 go vet ./... \u0026\u0026 go test ./...`.\n\n## License\n\n[MIT](./LICENSE) © Ryan Wolfe\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnwolfe%2Frivr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frnwolfe%2Frivr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnwolfe%2Frivr/lists"}