CLI

The railhook CLI opens a tunnel from a public URL to a port on your machine, so the code handling a webhook can run locally. It also lists events and starts replays from the terminal.

Install
Terminal window
```
curl -fsSL https://railhook.io/install-cli.sh | bash
```
The CLI needs Java 17 or newer. Add -s -- --with-java to let the script install it through your package manager, which uses sudo. The railhook command is placed in ~/.local/bin.
Log in
Terminal window
```
railhook login --server https://railhook.io   # or your own instance, e.g. http://localhost or https://hooks.example.com
```
This prints a URL and a code. Approve it in the browser, no password goes into the terminal. For scripts there is railhook login --email you@example.com --password, which prompts for the password.
Open a tunnel
Terminal window
```
railhook listen 3000
```
The CLI prints a public URL and forwards each request to http://localhost:3000, then returns your response. A path after the URL is kept: https://<host>/tunnel/<slug>/webhooks/stripe reaches http://localhost:3000/webhooks/stripe.

The body arrives byte for byte, so your own signature check passes for form posts and binary bodies too. If the connection drops, the CLI reconnects to the same URL, and a request in flight at that moment is answered 502 at once instead of after the 30-second timeout. Ctrl+C closes the tunnel.

Commands

Command	Does
`railhook login [--server <url>]`	Logs in with the device code flow
`railhook status`	Shows the server, auth state, health and active tunnels
`railhook listen <port> [--project <id>]`	Opens a tunnel to a local port
`railhook tunnels list`	Lists active tunnel sessions
`railhook tunnels status`	Shows tunnel registry stats
`railhook tunnels close <sessionId>`	Closes one tunnel
`railhook events <projectId>`	Shows recent events. `--count` sets how many (default 20), `--type` filters
`railhook events <projectId> --follow`	Keeps polling for new events
`railhook replay <projectId>`	Replays events, by default from the last 24 hours
`railhook replay <projectId> --dry-run`	Estimates the replay without running it
`railhook config show`	Prints the configuration
`railhook config set <key> <value>`	Sets `backend-url` or `project-id`
`railhook config clear`	Clears the configuration and logs you out
`railhook config profile create <name> --url <url>`	Adds a profile for another server
`railhook config profile use <name>`	Switches profile
`railhook config profile list` / `delete <name>`	Lists or deletes profiles

replay also takes --event-type, --endpoint, and --from / --to as ISO-8601 times. railhook -h or railhook <command> -h shows every option.

Operator commands

On a self-hosted instance with PLATFORM_ADMIN_TOKEN set, railhook admin lists organizations and suspends or reinstates them. The token comes from RAILHOOK_ADMIN_TOKEN or --token and is never saved to the config file.

export RAILHOOK_ADMIN_TOKEN=...
railhook admin orgs --search acme
railhook admin suspend <organizationId> --reason "Confirmed spam reports"
railhook admin reinstate <organizationId>

Configuration file

The CLI stores the server URL, tokens and active project in ~/.config/railhook/config.json, with 600 permissions.

Variable	Effect
`RAILHOOK_CONFIG`	Use another config file path
`XDG_CONFIG_HOME`	Base config directory (default `~/.config`)
`RAILHOOK_DEBUG`	Print stack traces on errors

Troubleshooting

Symptom	Fix
Java not found	Install Java 17+, or re-run the installer with `--with-java`
Connection refused while tunnelling	Nothing is listening on the local port you gave `listen`
A signature check fails only for gzip or other binary bodies through the tunnel	Your CLI predates byte-exact bodies. Re-run the install command to update it
Repeated `401`	Tokens refresh on their own. If it keeps happening, run `railhook login` again