Mailman

A Bun-powered terminal HTTP client built with OpenTUI, React, and strict TypeScript.

• Interactive terminal UI — Full-screen HTTP client with keyboard and mouse-friendly controls.
• Multiple request protocols — REST, GraphQL, WebSocket collections, and SSE stream parsing support.
• Request builder — Headers, query params, auth, scripts, and body editors in one terminal workflow.
• Flexible bodies — Raw, URL-encoded, file, and multipart request body modes.
• Response viewer — Status, timing, size, headers, raw output, formatted body, stream events, and copy helpers.
• Collections and history — Save, import/export, reopen, and organize requests under ~/.mailman/.
• CLI mode — Parser-driven command/request prompt with suggestions for REST, GraphQL, and SSE requests.
• Theme system — Built-in themes with live preview via Ctrl+T.

• Bun installed locally.

bun install
bun run dev

You can also use:

bun start

bun run dev:cli

Example CLI requests:

http rest GET https://api.example.com/users
http rest POST https://api.example.com/users --json '{"name":"Mailman"}'
http graphql https://api.example.com/graphql --query 'query { viewer { login } }'
http sse https://api.example.com/events

See docs/cli-input-grammar.md for the full CLI grammar.

The current README uses mailman.png as the hero image. For a stronger project showcase, add a small gallery under docs/assets/showcase/ and keep file names stable so links do not break.

Suggested screenshots/GIFs to capture:

Recommended Markdown/HTML layout once those assets exist:

<p align="center">
  <img src="docs/assets/showcase/main-tui.png" alt="Mailman main TUI" width="49%" />
  <img src="docs/assets/showcase/graphql.png" alt="Mailman GraphQL request" width="49%" />
</p>
<p align="center">
  <img src="docs/assets/showcase/request-editor.gif" alt="Editing requests in Mailman" width="49%" />
  <img src="docs/assets/showcase/cli-mode.gif" alt="Mailman CLI mode" width="49%" />
</p>

Tips:

• Prefer short GIFs for flows and PNG/WebP for static screens.
• Use terminal dimensions around 120x36 for readable screenshots.
• Avoid secrets, private URLs, or personal collection data.
• Compress images before committing so the repository stays lightweight.

1. Select or create a collection.
2. Add a REST, GraphQL, or WebSocket request.
3. Configure the URL, method/protocol, headers, query parameters, auth, body, and scripts.
4. Send the request from the request panel.
5. Inspect the response body, headers, raw view, stats, or stream events.
6. Press Ctrl+S to persist changes to the selected collection.

• Import sample or existing collections from the collection panel.
• Add requests manually or prefill from cURL when creating a request.
• Select a saved request to load it into the request panel.
• Export collections when you need to share or back them up.
• Persistent app data is stored under ~/.mailman/.

bun install          # Install dependencies
bun run dev          # Run the TUI application
bun start            # Run the TUI application
bun run dev:cli      # Run CLI mode
bun run build        # Build executable to dist/mailman
bun run seed         # Load example collections into ~/.mailman/

bun test             # Run all tests
bun test --watch     # Run tests in watch mode
bun test src/core/services/http-client.test.ts
bun test -t "should make GET request"

bun run fmt          # Format code with oxfmt
bun run fmt:check    # Check formatting without modifying
bun run lint         # Lint with oxlint, including type-aware checks
bun run lint:fix     # Auto-fix linting issues

index.tsx                    Entry point; chooses TUI or CLI mode
src/
  core/
    services/                HTTP, GraphQL, WebSocket, SSE, storage, import, history, scripts
    types/                   Request, response, auth, collection, history, and script types
  modes/
    tui/                     Full-screen interactive app
      components/            OpenTUI React components
      hooks/                 TUI keyboard/focus hooks
      utils/                 TUI-specific helpers
    cli/                     Parser-driven CLI mode
      commands/              Slash command registry and handlers
      parser/                Lexer, parser, suggestions
      shell/                 Virtual collection/request filesystem helpers
  shared/
    components/              Cross-mode editors and modals
    theme/                   Theme provider, colors, built-in JSON themes
    utils/                   Formatting, copying, viewport, and highlighting helpers
docs/                        CLI grammar, examples, and planning notes
sample-collection/           Postman/Insomnia import samples
scripts/                     Development utilities

MIT