Skip to main content
The StoreRouter CLI gives people and agents a consistent command-line interface to StoreRouter. It prints readable output in an interactive terminal and JSON when stdout is piped, so scripts can consume the same commands without extra flags.
The CLI is currently a pre-release. Install it from the next npm dist-tag while its interface is being finalized.

Requirements

  • Node.js 20 or later
  • A StoreRouter API key

Install or run the CLI

Install the prerelease package globally:
Always specify @next: latest currently points to a reservation package. The package provides two executable names, storerouter and the compatibility alias octogen. When using npm exec or npx, select the executable explicitly:
If you installed @octogen-ai/cli globally, uninstall it before installing the new package in the same npm prefix. Both packages own the octogen executable; do not overwrite that link with --force. See the migration guide for migration, credential precedence, and rollback steps.

Configure credentials

You can run the CLI without installing it globally. Set your API key in the environment before running commands:
The default API is https://api.storerouter.ai/v1; normal commands do not need --base-url. Existing API keys still work. OCTOGEN_PLATFORM_API_KEY remains a compatibility fallback after STOREROUTER_API_KEY; OCTO_API_KEY is deprecated. The CLI also accepts a key from --api-key-stdin, --api-key-file, or a .env file between your current directory and the nearest Git repository root. It does not provide a --api-key argument because command-line arguments can appear in shell history and process listings. After a global install, use storerouter in place of the npm exec prefix below. parse is an exact alias of lookup, including its JSON command name and exit codes.

Common commands

Look up a product

Search products

Find similar products

Use the low-level api command for requests outside these examples. See the complete command reference for every option.

Output for agents

The CLI automatically emits one-line JSON when stdout is not a TTY. Use --json to force JSON or --no-json to force human-readable output.
Diagnostics go to stderr, while stdout contains only the result. Use --quiet to silence diagnostics or --verbose to include timing and allow-listed response headers.

Exit codes

Exit code 6 never represents throttling. This distinction lets an agent tell an empty result apart from an unavailable or exhausted service.

Discover and browse brands

These commands require CLI 0.6.0 or later, which uses TypeScript SDK 0.14.0. Install from @next as shown above.
brands directory returns the complete alphabetical list. brands show returns the profile, typed articles, and navigation; it no longer includes coverage. Use brands coverage explicitly for the independently cached approximate snapshot. Product output includes nextOffset. Pass it to the next brands products --offset request until it is null. An empty page can still have a continuation. Offsets end at 11976, including page 500 at 24 source rows per page. Product rows and source totals respect your catalog scope; metadata and approximate coverage span the corpus. For interactive relevance search, use storerouter search with a brand_name facet. See Discover brands.