Hooklistener CLI

A fast, terminal-based CLI for browsing webhooks, forwarding events, and exposing local servers using Hooklistener. Built with Rust and Ratatui for a smooth, responsive TUI experience.

Features

• 🚀 Fast & Lightweight - Built in Rust for maximum performance
• 🖥️ Terminal UI - Browse requests with a keyboard-driven interface
• 🔄 Real-time Forwarding - Stream webhook requests from existing endpoints to your local server
• 🚇 HTTP Tunneling - Expose your local server to the internet with a public URL (like ngrok)
• 🔍 Search & Filter - Quickly find specific requests
• 📋 Request Details - View headers, body, and metadata
• 🔐 Secure OAuth - Device code authentication flow (no API keys needed)
• 📊 Professional Logging - Structured logging with file rotation and diagnostics

Installation

Homebrew (macOS / Linux)

brew tap hooklistener/tap
brew install hooklistener

npm

npm install -g hooklistener

Cargo

cargo install hooklistener-cli

Quick Install Script

Install with a single command:

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/hooklistener/hooklistener-cli/main/scripts/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/hooklistener/hooklistener-cli/main/scripts/install.ps1 | iex

Manual Installation

Download and extract the binary for your platform from the Releases page.

Install System-Wide (Optional)

After downloading, move the binary to your PATH:

# macOS/Linux
sudo mv hooklistener-cli /usr/local/bin/hooklistener

Now you can run hooklistener from anywhere.

Quick Start

1. Install (see above).

2. Authenticate:

   hooklistener login
   

   Follow the on-screen instructions to authorize the device.

3. Choose your mode:

   • Browse Webhooks: Run hooklistener (or hooklistener tui) to view requests.
   • Forward Webhooks: Run hooklistener listen <endpoint-slug> to forward events from an existing endpoint.
   • Expose Local Server: Run hooklistener tunnel to get a public URL for your local app.

Usage

Authentication

Authenticate securely via the device flow. This is required for all operations.

# Authenticate (opens browser if needed)
hooklistener login

# Force re-authentication
hooklistener login --force

Browsing Webhooks (TUI)

Launch the interactive Terminal User Interface to browse, search, and inspect webhook requests.

# Launch TUI (default command)
hooklistener tui
# or simply
hooklistener

Keyboard Shortcuts:

Forwarding Webhooks (listen)

Use this when you have an existing Hooklistener Endpoint and want to debug webhooks locally. It forwards requests sent to that endpoint to your localhost.

# Forward webhooks from 'my-endpoint' to http://localhost:3000 (default)
hooklistener listen my-endpoint

# Forward to a custom local URL
hooklistener listen my-endpoint --target http://localhost:8080

Exposing Local Server (tunnel)

Use this to create a public URL that tunnels traffic to your local machine. Great for receiving webhooks from third-party services directly to your dev environment.

# Start a tunnel to port 3000 (default)
hooklistener tunnel

# Tunnel to a specific port
hooklistener tunnel --port 8080

# Tunnel to a specific host and port
hooklistener tunnel --host 127.0.0.1 --port 5000

# Use a persistent subdomain (Paid plans)
hooklistener tunnel --slug my-cool-app

Maintenance & Diagnostics

# Generate a diagnostic bundle for support/debugging
hooklistener diagnostics --output ./debug-bundle

# Clean up old log files
hooklistener clean-logs --keep 5

# Show help
hooklistener --help

Configuration

Configuration is stored in ~/.config/hooklistener/config.json. The CLI handles token management automatically.

Environment Variables

For advanced usage or self-hosting:

• HOOKLISTENER_API_URL: Base URL for API requests.
• HOOKLISTENER_WS_URL: Base URL for WebSocket connections.
• HOOKLISTENER_DEVICE_PORTAL_URL: URL for device activation.

Development

Prerequisites

• Rust 1.75+
• Cargo

Building

git clone https://github.com/hooklistener/hooklistener-cli.git
cd hooklistener-cli

# Run locally
cargo run -- tui

# Build release
cargo build --release

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE.