Metadata-Version: 2.4
Name: capstan
Version: 1.0.0
Summary: A webhook inspector for local development
Author: Julien Hadley Jack
Author-email: Julien Hadley Jack <git@jlhj.de>
License-Expression: MIT
License-File: LICENSE.txt
Requires-Dist: aiohttp>=3.13.5
Requires-Dist: cyclopts>=4.10.0
Requires-Dist: textual>=8.1.1
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Capstan: The Webhook Inspector

<!-- [[[cog
from pathlib import Path
from scripts.cog_readme import copy_image
copy_image(
  Path("tests/__snapshots__/test_tui_app/test_snapshot_populated.raw"),
  Path("docs/screenshot.svg"),
)
]]] -->
<!-- file checksum: 7122778bb8772c8540cb272658e2a897cc33e7313bc034f4884beaa1be9bd497 -->
![](docs/screenshot.svg)
<!-- [[[end]]] -->

**Capstan** is a modern, lightweight, and terminal-based webhook inspector for local development. It provides a TUI (
Terminal User Interface) to monitor and inspect incoming HTTP requests, making it the perfect companion for debugging
webhooks and API integrations without leaving your terminal.

## Features

- **Overview**: Quick view of method, path, host, and timestamp.
- **Headers & Cookies**: Complete breakdown of all request headers and cookies.
- **Query Parameters**: Easy-to-read table of all URL parameters.
- **Body Analysis**:
    - **Syntax Highlighting**: Built-in support for JSON, XML, and more.
    - **Hexdump**: Automatic fallback to a polished hexdump for binary or unknown content.

Capstan is designed to be a simple and lightweight tool. As such, it does **not** support:

- **Persistence**: Captured requests are stored in-memory and are lost when the application is closed.
- **HTTPS/SSL**: The local server only supports HTTP. Use a tunnel like `ngrok` if you need to receive webhooks from
  HTTPS sources or from the internet.
- **Dynamic Responses**: It returns a static response (status, body, headers) for all requests.
- **Request Replay**: There is no functionality to "replay" or "resend" captured requests.

[mitmproxy](https://www.mitmproxy.org/) can be used instead should those advanced features be needed.

## Installation

You can install Capstan using `uv` (recommended) :

```bash
uv tool install capstan
```

Alternatively, you could install it with `pipx`:

```bash
pipx install capstan
```

## Quick Start

Simply run `capstan` to start the inspector:

```bash
capstan
```

By default, Capstan will start a server on `http://127.0.0.1:8080`.
You can now send requests to this address (or any path under it),
and they will appear in the TUI.

You can send then HTTP requests to that address with arbitrary paths. Example:

```bash
curl -X POST http://127.0.0.1:8080/test-webhook \
     -H "Content-Type: application/json" \
     -d '{"event": "user_signup", "user_id": 123}'
```

## Usage

See the help documentation for more information:

<!-- [[[cog
from pathlib import Path
from scripts.cog_readme import run_command
run_command("capstan --help")
]]] -->
```bash
$ capstan --help
Usage: capstan COMMAND [OPTIONS]

A webhook inspector for local development.

╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ --help (-h)           Display this message and exit.                         │
│ --install-completion  Install shell completion for this application.         │
│ --version             Display application version.                           │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Parameters ─────────────────────────────────────────────────────────────────╮
│ --host    The listen address for the endpoint [default: 127.0.0.1]           │
│ --port    The port for the endpoint [default: 8080]                          │
│ --status  The response status code for the webhook [default: 201]            │
╰──────────────────────────────────────────────────────────────────────────────╯
```
<!-- [[[end]]] -->
