Metadata-Version: 2.4
Name: firmhook
Version: 0.2.1
Summary: Forward live webhook events to localhost — instant public tunnel or full dev mode with retries and logs
Project-URL: Homepage, https://firmhook.com
Project-URL: Source, https://github.com/Numostanley/FirmHook
License: MIT
Keywords: developer-tools,localhost,ngrok-alternative,tunnel,webhook
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Requires-Dist: websockets>=13
Description-Content-Type: text/markdown

# firmhook

The official CLI for [FirmHook](https://firmhook.com) — a webhook monitoring and delivery platform.

The CLI gives you two ways to receive webhooks on your local machine:

| | `firmhook listen` | `firmhook start` |
|---|---|---|
| **Account required** | No | Yes |
| **API key required** | No | Yes |
| **Events stored in dashboard** | No | Yes |
| **Retries on failure** | No | Yes |
| **Response returned to provider** | Yes | No |
| **Best for** | Quick testing, demos, no-account situations | Active development against a configured endpoint |

---

## Installation

```bash
# Recommended — isolated install, firmhook available on PATH immediately
uv tool install firmhook

# Or with pipx
pipx install firmhook

# Or with pip
pip install firmhook
```

Verify:

```bash
firmhook --help
firmhook version
```

Requires Python 3.9+.

---

## Instant Tunnel — `firmhook listen`

Get a public URL in one command. No account, no API key, no configuration.

```bash
firmhook listen 3000
```

Output:

```
firmhook 0.2.0  |  Press Ctrl+C to stop

  Tunnel URL:  https://api.firmhook.com/tunnel/a3f2c1d4-...
  Forwarding:  http://localhost:3000

  Ready. Waiting for requests... (Ctrl+C to stop)

→ POST    http://localhost:3000  [application/json]
← 200  (42ms)
```

Paste the **Tunnel URL** into any webhook provider. All incoming requests are forwarded to your local server in real time. The actual response from your server is returned to the provider — webhook providers that validate the response (e.g. Stripe, GitHub) work correctly.

The tunnel lives as long as the CLI is running. Closing it (Ctrl+C) immediately invalidates the URL.

### Options

```
firmhook listen <port> [--forward-to <url>]
```

| Argument | Description |
|---|---|
| `port` | Local port to forward requests to |
| `--forward-to`, `-f` | Override the full forward URL (default: `http://localhost:<port>`) |

### Examples

```bash
# Forward to localhost:3000
firmhook listen 3000

# Forward to a specific path on localhost
firmhook listen 3000 --forward-to http://localhost:3000/webhooks

# Forward to a different local service
firmhook listen 3000 --forward-to http://127.0.0.1:4000/events
```

---

## Dev Mode — `firmhook start`

For active development. Events are stored in the FirmHook dashboard with full history, retries, delivery logs, and AI-assisted error explanations.

### Setup

**1. Create a FirmHook account** at [firmhook.com](https://firmhook.com).

**2. Enable dev mode on an endpoint** — in the dashboard, open an endpoint and toggle Dev Mode on. Set a Dev Forward URL (e.g. `http://localhost:3000/webhooks`).

**3. Save your API key:**

```bash
firmhook config --api-key fhk_your_api_key_here
```

**4. Start forwarding:**

```bash
firmhook start <org-slug> <endpoint-id>
```

For example:

```bash
firmhook start acme-corp b338f02c-e8b1-4dd5-93ad-0cba72f23ffe
```

The CLI fetches the `dev_forward_url` from the endpoint automatically. Events from FirmHook are forwarded to your local server as they arrive.

### Options

```
firmhook start <org-slug> <endpoint-id> [--forward-to <url>] [--api-key <key>] [--detach]
```

| Flag | Description |
|---|---|
| `--forward-to`, `-f` | Override the local URL for this session (does not update the endpoint) |
| `--api-key` | Use a specific API key instead of the saved one |
| `--detach`, `-d` | Run the agent in the background |

### Background mode

```bash
# Start in background
firmhook start acme-corp <endpoint-id> --detach

# Check if it's running
firmhook status

# View recent log output
firmhook logs

# Stream logs in real time
firmhook logs --follow

# Stop the background agent
firmhook stop
```

---

## All commands

```
firmhook listen <port>        Open a public tunnel URL and forward requests to a local port
firmhook start <org> <id>     Connect to a FirmHook endpoint and forward events to localhost
firmhook config               Save your API key
firmhook status               Show whether the background agent is running
firmhook logs                 Print recent agent log output
firmhook stop                 Stop the background agent
firmhook version              Print the firmhook version
```

---

## How it works

### Instant tunnel

```
Webhook provider
      │
      ▼
POST https://api.firmhook.com/tunnel/{session_id}
      │
      ▼  Redis pub/sub
      │
      ▼
WebSocket  wss://api.firmhook.com/ws/tunnel/{session_id}
      │
      ▼
firmhook CLI  →  HTTP  →  localhost:<port>
      │
      ▼  ack (status + body)
      │
      ▼
Response returned to webhook provider
```

### Dev mode

```
Webhook provider  →  FirmHook ingest URL
                           │
                       PostgreSQL (event stored)
                           │
                       Celery worker
                           │  Redis pub/sub
                           ▼
                      firmhook CLI  →  localhost:<port>
                           │
                       Delivery recorded in dashboard
```

---

## Configuration

The CLI stores settings in `~/.firmhook/config.json`.

```bash
# Save your API key
firmhook config --api-key fhk_your_key

# Show the saved API key
firmhook config --show
```

---

## Changelog

### 0.2.1
- Added project URLs (homepage and source) to package metadata

### 0.2.0
- Added `firmhook listen <port>` — instant public tunnel, no account or API key required
- Server URL is now always `api.firmhook.com` and is no longer user-configurable

### 0.1.0
- Initial release — `config`, `start`, `stop`, `status`, `logs`, `version` commands
