<div align="center">
    <img alt="logo" src="./.github/assets/logo.png" width="120px" />
</div>

<br>

# Spilltea

> A minimal, terminal-based HTTP(S) proxy for pentesters and CTF players.  
> Think Burp Suite or Caido, but entirely in your terminal.

![GitHub Stars](https://www.shieldcn.dev/github/stars/anotherhadi/spilltea.svg?variant=outline&theme=violet)
![Release](https://www.shieldcn.dev/github/release/anotherhadi/spilltea.svg?variant=outline&theme=violet)
![CI](https://www.shieldcn.dev/github/ci/anotherhadi/spilltea.svg?variant=outline&theme=violet)
[![Ko-fi](https://www.shieldcn.dev/badge/Ko--fi-sponsor-FF5E5B.svg?logo=kofi&variant=secondary&theme=violet)](https://ko-fi.com/anotherhadi)

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [What is Spilltea?](#what-is-spilltea)
- [Legal Disclaimer](#legal-disclaimer)
- [Features](#features)
- [Installation](#installation)
- [Project Management](#project-management)
- [Configuration](#configuration)
  - [Per-project configuration](#per-project-configuration)
- [CLI Flags](#cli-flags)
- [Plugin System](#plugin-system)
- [Vim / Neovim Integration](#vim--neovim-integration)
- [Deployment](#deployment)
- [Tech Stack](#tech-stack)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## What is Spilltea?

Spilltea is a **terminal-native HTTP(S) interception proxy**. It sits between your browser and the internet, letting you inspect, modify, and replay traffic without ever leaving your terminal.

It is intentionally minimal. No Electron, no browser, no bloat. Just a fast, keyboard-driven tool that gets out of your way.

<img alt="demo" src="./.github/assets/demo.gif" width="700" />

 <!-- exec: cat ./docs/legal-disclaimer.md -->
## Legal Disclaimer

**This tool is provided for educational purposes and authorized security testing only.**

Use Spilltea only on systems and networks you own or have explicit written permission to test. Intercepting network traffic without authorization may violate local laws (such as the Computer Fraud and Abuse Act, GDPR, or equivalent legislation in your jurisdiction).

The author(s) and contributors are not responsible for any misuse, damage, or legal consequences resulting from the use of this software. By using Spilltea, you agree that you are solely responsible for ensuring your usage is lawful and authorized.
<!-- endexec -->

## Features

- **Intercept**: Pause requests and responses in-flight. Inspect and modify them (even with your favorite editor) before forwarding.
- **HTTP History**: Every request that passes through the proxy is stored. Browse, search and filter your full session history.
- **Replay**: Pick any request from the history, modify it if needed, and send it again. Useful for manual testing and quick iteration
- **HTTPS Support** (using go-mitmproxy under the hood)
- **Vim-like Navigation**: The entire interface is keyboard-driven with Vim-inspired shortcuts. Use `h/j/k/l` to move, `gg`/`G` to jump to the top/bottom, `/` to search, `q` to close panels, and more. All keybindings are fully customizable via the config file.
- Built-in Integrations:
  - **FFuf Export**: Generate a ffuf command or configuration directly from a request to start fuzzing instantly.
  - **cURL / HTTPie**: Copy any request as a curl or httpie command to your clipboard.
  - **Markdown Export**: Export any request and its response as a clean Markdown snippet, ready to drop into a report.

## Installation

<details>
<summary>Go install</summary>

```sh
go install github.com/anotherhadi/spilltea/cmd/spilltea@latest
```

Requires Go 1.22+. The binary will be placed in `$GOPATH/bin` (or `~/go/bin`).

</details>

<details>
<summary>Nix (temporary run, no install)</summary>

```sh
nix run github:anotherhadi/spilltea
```

</details>

<details>
<summary>NixOS (flake)</summary>

Add spilltea to your flake inputs:

```nix
inputs.spilltea.url = "github:anotherhadi/spilltea";
```

Then add the package to your system or home-manager packages:

```nix
environment.systemPackages = [ inputs.spilltea.packages.${pkgs.system}.default ];
```

</details>

 <!-- exec: cat ./docs/basics.md -->
## Project Management

Spilltea organizes work into **projects**. Each project maps to a SQLite database file that stores all intercepted traffic for that session & a log files.

On startup, you choose:

- **New project**: enter a name, stored in `~/.local/share/spilltea/<name>/` by default
- **Existing project**: pick from a list of previous projects
- **Temporary**: no name needed, stored in `/tmp/spilltea/<random-id>/` and will be deleted on your next reboot!

## Configuration

Spilltea is fully configured via a YAML file at `~/.config/spilltea/config.yaml`.
Check the default configuration with all the options [here](./internal/config/default_config.yaml)

Colors and styles can be customized using [ilovetui](https://github.com/anotherhadi/ilovetui), which applies theme changes across all compatible TUI applications at once.

### Per-project configuration

You can override any config value on a per-project basis by placing a `config.yaml` file inside the project directory (e.g. `~/.local/share/spilltea/projects/my-project/config.yaml`).

Only the keys present in that file are overridden; everything else falls back to the global config.

The priority order is:

1. Global config (`~/.config/spilltea/config.yaml`)
2. Project config (`<project-dir>/config.yaml`)
3. CLI flags (always win)

## CLI Flags

```
A minimal, terminal-based HTTP(S) proxy for pentesters and CTF players.

Usage:
  spilltea [flags]

Flags:
      --add-default-config      copy the default config file to the config path and exit
      --add-default-plugins     copy built-in example plugins into the plugins dir and exit
  -c, --config string           path to config file
  -h, --help                    help for spilltea
      --host string             proxy host (overrides config)
      --plugins-dir string      path to plugins dir (overrides config)
  -p, --port int                proxy port (overrides config)
  -P, --project string          project name to open directly, or "tmp" for a temporary session
      --ssl-insecure            skip TLS certificate verification (overrides config)
      --upstream-proxy string   upstream proxy URL, e.g. http://user:pass@host:8888 (overrides config)
  -v, --version                 version for spilltea
```
<!-- endexec -->

## Plugin System

Spilltea supports plugins written in **Lua**. Plugins are loaded from `~/.config/spilltea/plugins/` by default and do not require recompilation or access to the source code.
For a full reference and examples, see the [plugin documentation](./docs/plugins.md) or [plugin examples](./plugins/).

## Vim / Neovim Integration

Spilltea pairs naturally with Neovim. If you live in your editor, these plugins let you inspect and transform captured traffic without switching context:

- **[sttr.nvim](https://github.com/anotherhadi/sttr.nvim)**: Run string transformations (base64, URL encode/decode, hex, hashing, and more) on any selected text directly from Neovim. Handy for decoding values spotted in the proxy history.
- **[jwt-tui.nvim](https://github.com/anotherhadi/jwt-tui.nvim)**: Decode and inspect JWT tokens in a floating TUI window. Great for quickly reading tokens intercepted through the proxy.

Both plugins are built to feel native in a terminal workflow, just like Spilltea.

## Deployment

spilltea runs **locally** on the machine used for pentesting or CTF. There is no separate server component.

If you need to run spilltea on a remote machine (e.g., a VPS or pivot host), use SSH port forwarding:

```sh
ssh -L 8080:127.0.0.1:8080 user@remote-host
```

Then point your browser at `127.0.0.1:8080` as usual.

## Tech Stack

| Component          | Library                                                   |
| ------------------ | --------------------------------------------------------- |
| TUI                | [bubbletea](https://github.com/charmbracelet/bubbletea)   |
| Styles             | [lipgloss](https://github.com/charmbracelet/lipgloss)     |
| Proxy / MITM / TLS | [go-mitmproxy](https://github.com/lqqyt2423/go-mitmproxy) |
| Storage            | [modernc.org/sqlite](https://gitlab.com/cznic/sqlite)     |
| Config             | [viper](https://github.com/spf13/viper)                   |
| Plugins            | [gopher-lua](https://github.com/yuin/gopher-lua)          |

---

<div align="center">
  <a href="https://github.com/anotherhadi/spilltea">github</a> |
  <a href="https://gitlab.com/anotherhadi_mirror/spilltea">gitlab (mirror)</a> |
  <a href="https://git.hadi.icu/anotherhadi/spilltea">gitea (mirror)</a>
</div
