Installation

The hookstream CLI ships as a single ESM binary on npm. It runs on Node.js 18+ and works on macOS, Linux, and Windows.

Install

The binary installs as hookstream. Run hookstream --help to see all command groups.

Run without installing

Use npx (or the pnpm/bun equivalent) for one-off commands — handy in CI:

bash
npx @hookstream/cli sources list
npx @hookstream/cli listen --forward http://localhost:3000/webhook

Verify

Configuration

Config file

The CLI stores its config in an XDG-compliant location:

• macOS / Linux: ~/.config/hookstream/config.json
• Windows: %APPDATA%\hookstream\config.json

The file is created automatically on hookstream login and looks like:

json
{
  "api_key": "hs_live_...",
  "base_url": "https://hookstream.io"
}

Environment variables

All config can be overridden by environment variables, which is what you'll want in CI:

bash
export HOOKSTREAM_API_KEY=hs_live_abc123...
hookstream sources list

Precedence

API key resolution order, highest to lowest:

1. --api-key CLI flag — per-command override
2. HOOKSTREAM_API_KEY environment variable — session or CI
3. config.json — persistent default from hookstream login

This lets you keep a default key in config while overriding per-command for ad-hoc work.

Build from source

Clone the monorepo and build the CLI locally — useful for contributing or running against a local Worker:

bash
git clone https://github.com/seangeng/hookstream
cd hookstream
pnpm install
pnpm build:cli

# Run the local build
node cli/dist/index.js --help

Point it at a local Worker with --base-url http://localhost:8787 or HOOKSTREAM_BASE_URL=http://localhost:8787.

Next