Skip to main content
The Octogen CLI gives people and agents a consistent command-line interface to Octogen. 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
  • An Octogen API key for authenticated commands
The domains, lookup, and search commands also support a limited keyless trial.

​
Run the CLI

You can run the CLI without installing it globally:
To authenticate, set your API key in the environment:
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.

​
Common commands

​
Look up a product

​
Search products

​
Find similar products

​
Check domain coverage

​
Start and monitor a voyage

Other commands include refresh, resolve, and the low-level api escape hatch. See the CLI source and 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.

​
Keyless trial

Without an API key, domains, lookup, and search use the keyless trial. The trial allows 30 requests per IP address per day and returns complete payloads. Other commands require authentication. Shared networks can exhaust the trial before your first request. A keyless limit returns exit code 5, not 6.