Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install proxy-tuigit clone https://github.com/jedmota/nabu.gitcp -r nabu/ ~/.claude/skills/proxy-tui/# proxy-tui
HTTP/HTTPS debugging proxy with a terminal UI. Intercepts, inspects, and manipulates HTTP traffic via MITM. Supports URL whitelisting, mapping requests to local files, and redirecting requests to different servers.
## Quick Start
```bash
# Build
go build -o proxy-tui ./cmd/proxy-tui
# Run (default port 9090, all interfaces)
./proxy-tui
./proxy-tui --port 8080 --bind 127.0.0.1
# Run without TUI (headless / scripting)
./proxy-tui --headless
# Show CA certificate info
./proxy-tui --show-ca
# Install CA to system trust store
./scripts/install-ca.sh
```
Configure clients to use the proxy:
```bash
export HTTP_PROXY=http://localhost:9090
export HTTPS_PROXY=http://localhost:9090
```
## CLI Flags
| Flag | Default | Description |
|------|---------|-------------|
| `--port` | `9090` | Proxy listening port |
| `--bind` | `0.0.0.0` | Bind address |
| `--verbose` | `false` | Verbose logging |
| `--headless` | `false` | Run without TUI |
| `--show-ca` | `false` | Print CA cert path and fingerprint, then exit |
## Whitelist Management
Whitelist patterns filter which requests are displayed in the UI. Supports glob (`*.example.com`) and regex (`^api\.example\.com$`) patterns.
```bash
# Add patterns (proxy starts normally after adding)
proxy-tui --whitelist "*.example.com"
proxy-tui --whitelist "*.api.io" --whitelist "*.cdn.io"
# List all patterns with their IDs
proxy-tui --list-whitelist
# Output:
# 1: *.example.com (enabled)
# 2: *.api.io (enabled)
# 3: *.cdn.io (disabled)
# Remove by ID
proxy-tui --rm-whitelist 2
```
## Map Local (Mock Responses)
Serve local files instead of forwarding requests to the origin server. Useful for mocking APIs.
```bash
# Add rules (proxy starts normally after adding)
proxy-tui --map-local "https://api.example.com/users=>/tmp/users.json"
proxy-tui --map-local "*/api/data*=>/home/user/mock.json"
# List rules
proxy-tui --list-map-local
# Output:
# 1: https://api.example.com/users => /tmp/users.json (enabled)
# Remove by ID
proxy-tui --rm-map-local 1
```
Mock files can be plain JSON or JSONC with response metadata:
```jsonc
{
"status": 200,
"headers": {
"Content-Type": "application/json"
},
"body": {
"users": [{"id": 1, "name": "Mock User"}]
}
}
```
## Map Remote (Redirect Requests)
Transparently redirect requests to a different server (no HTTP redirect issued to the client).
```bash
# Add rules (proxy starts normally after adding)
proxy-tui --map-remote "https://api.prod.com/*=>http://localhost:3000"
# List rules
proxy-tui --list-map-remote
# Output:
# 1: https://api.prod.com/* => http://localhost:3000 (enabled)
# Remove by ID
proxy-tui --rm-map-remote 1
```
A request to `https://api.prod.com/users?page=1` gets fetched from `http://localhost:3000/users?page=1`. The client sees the response as if it came from the original host.
## Combining Flags
Add flags are repeatable and can be combined. The proxy starts normally after processing them:
```bash
proxy-tui --port 8080 \
--whitelist "*.example.com" \
--map-local "*/mock-endpoint=>/tmp/mock.json" \
--map-remote "https://api.prod.com/*=>http://localhost:3000"
```
List and remove flags are fire-and-exit (they print output or modify config, then the process exits):
```bash
proxy-tui --list-whitelist # prints and exits
proxy-tui --rm-map-local 2 # removes and exits
```
## Pattern Syntax
Patterns are used across whitelist, map-local, and map-remote rules:
| Pattern | Matches |
|---------|---------|
| `*.example.com` | Any subdomain of example.com |
| `api.*` | Any TLD for "api" |
| `*google*` | Any URL containing "google" |
| `example.com` | Exact match |
| `^(api\|www)\.example\.com$` | Regex (if starts with `^` or `(`) |
## Config Files
All configuration is stored in `~/.proxy-tui/`:
| File | Contents |
|------|----------|
| `ca.crt` / `ca.key` | Auto-generated CA certificate and key |
| `whitelist.jsonc` | Whitelist patterns |
| `maplocal.jsonc` | Map-local rules |
| `mapremote.jsonc` | Map-remote rules |
## Multi-Instance
Running `proxy-tui` on a port that already has an instance creates a secondary (view-only) connection via IPC:
```bash
# Terminal 1: primary instance
proxy-tui --port 9090
# Terminal 2: secondary instance (connects to existing)
proxy-tui --port 9090
```
## TUI Keybindings
| Key | Action |
|-----|--------|
| `q` | Quit |
| `Tab` | Toggle focus between list and detail |
| `j`/`k` | Navigate up/down |
| `1` | Show all requests |
| `2` | Show whitelist matches only |
| `/` | Search/filter by URL |
| `c` | Clear all captured flows |
| `w` | Quick-add selected host to whitelist |
| `W` | Open whitelist manager |
| `l` | Quick-create local mock from selected request |
| `L` | Open map-local manager |
| `r` | Quick-add map-remote rule |
| `R` | Open map-remote manager |
| `T` | Toggle raw/pretty JSON in detail view |
| `?` | Show help overlay |