Quickstart

1. Tell the CLI who you are

Once. The CLI auto-loads ~/.config/arjia-beam/config, so you never have to pass --token or --server again. (Full details in Config file.)

mkdir -p ~/.config/arjia-beam
printf 'token=YOUR_TOKEN\nserver=https://beam.example.com\n' > ~/.config/arjia-beam/config
chmod 600 ~/.config/arjia-beam/config

2. Listen

Forward everything that arrives on the public name myhook to your local app:

beam webhook listen myhook --forward http://localhost:3000

The CLI connects to the beam server over a WebSocket, claims the name, and prints ✓ connected · listening on /webhook/myhook. Leave it running.

3. Hit the public URL

From anywhere — your provider's dashboard, another terminal, a curl:

curl -X POST https://beam.example.com/webhook/myhook -d '{"hello":"world"}'

Your local server gets POST / with that body. The sender immediately gets a 202 Accepted (beam is fire-and-forget in v1).

Sub-paths and queries carry through

Any request to https://beam.example.com/webhook/myhook is replayed to your forward target — all HTTP methods are accepted and the original verb is preserved. Sub-paths and query strings pass through verbatim:

…/webhook/myhook/github/callback?x=1  →  http://localhost:3000/github/callback?x=1

Just watching?

Swap forwarding for --tail to print each request to stdout instead of replaying it — useful for inspecting payloads before you have a local handler:

beam webhook listen myhook --tail

Next

• Listen & forward — every flag, reconnection, fan-out.
• Send — re-fire a delivery without retyping the URL.
• Security model — what the token guards, and the optional per-webhook key.