🔥 Forge

The .http-native desktop API client for developers who live in their editor.

Plain text. Git-native. No proprietary format. No account. No cloud.

Install · Features · Why Forge · Directives · Roadmap · Contributing

Beta. Forge is actively used daily for real API development. All core features (parse, run, capture, history, scripting, collection runner, auth) are complete. The roadmap focuses on polish, distribution, and growing the .http-native story. See Roadmap for what's left.

---

🔥 Why Forge

Every API client invents its own format and locks you into it:

• Postman → proprietary JSON collections, account required, cloud-sync friction
• Bruno → .bru files, only Bruno reads them natively
• Insomnia → was open-source, then went subscription + cloud-sync

Meanwhile the .http / .rest format used by VS Code REST Client, JetBrains, and httpYac is plain text, sits in git alongside your code, and is editable in any IDE — but no standalone desktop app treats it as the source of truth.

Forge does. It reads your .http files directly and adds the things IDE extensions can't:

	Forge	Postman	Bruno	Insomnia
Open source (MIT)	✅	❌	✅	partial
File format	.http (universal)	proprietary JSON	.bru	proprietary JSON
Works with VS Code REST Client files	✅	❌	❌	❌
Works with JetBrains HTTP files	✅	❌	❌	❌
Git-native (plain text)	✅	❌	✅	❌
No account / sign-in	✅	❌	✅	❌
Zero telemetry · fully offline	✅	❌	✅	❌
Desktop app (not web-only)	✅	✅	✅	✅
Native binary (not Electron)	✅ Tauri/Rust	❌ Electron	❌ Electron	❌ Electron
Capture response → write to file	✅	❌	❌	❌
Per-endpoint response history	✅	✅	❌	✅
Pre/post-request JS scripting	✅ Bruno-compat	✅	✅	✅
Collection runner (CI-ready)	✅	✅	✅	✅
OpenAPI 3.0 export	✅	✅	❌	✅
Static HTML docs generation	✅	❌	❌	❌
Postman / Bruno / OpenAPI import	✅	✅	partial	✅

Trademarks: Postman, Bruno, and Insomnia are trademarks of their respective owners. This comparison is independent and unaffiliated.

The wedge: run a request → capture the real response → write it back into the .http file as a documented example — in plain text, in git. The feedback loop closes without touching the format that VS Code REST Client and JetBrains already understand. .http stays the single source of truth.

---

✨ Features

📂 Tree that speaks your file system

• Folder tree mirrors your directories — no import step, no sync, no re-import after edits
• Inline filter with fuzzy match across request names, methods, and URLs
• Collapsible groups, keyboard navigation (VS Code-style arrow keys through any collection)
• Method badges color-coded per verb (GET, POST, PUT, PATCH, DELETE)

⚡️ Run, capture, repeat

• Send + Save — fires the request and captures the response body, status, headers, and timing directly into the .http file as a documented example block
• Response history per endpoint — scroll back through every response you've seen, diff two runs side by side
• run-all mode — chains all requests in a file or directory, passing @captured variables forward; exits non-zero on any failed @assert (CI-ready API test suite, zero config)

✏️ Edit in the UI, save to the file

• Method, URL, headers, body, auth, form fields, query params, scripts — all editable inline; dirty-state indicator shows unsaved changes
• Environments — multiple .env-style files per collection; switch the active one from the toolbar; {{variable}} interpolation everywhere (URL, headers, body, scripts)
• Bulk edit mode for headers and query params — paste a block of key: value pairs

🔒 All auth schemes, no cloud

• Bearer token · Basic · API key
• Digest · NTLM · WSSE
• AWS Signature v4 · OAuth 1.0a
• OAuth 2.0: Client Credentials · Password Grant · Auth Code (+ PKCE) · Implicit

🧩 Bruno-compatible scripting

Pre- and post-request JavaScript sandboxed via the Boa engine. The API is intentionally Bruno-compatible so scripts from Bruno collections port over without changes:

// @script:pre
req.setUrl(`${bru.getVar("baseUrl")}/search`);
req.setHeader("X-Trace", bru.getVar("traceId"));
bru.setVar("startedAt", Date.now());
// @end

// @script:post
test("status is 200", () => {
  expect(res.status).to.equal(200);
});
bru.setVar("userId", res.json.data.id);
// @end

📊 Response panel

• JSON tree with collapse / expand, animated chevron carets, line numbers, and copy-value buttons
• Raw, Preview (HTML iframe), and Headers tabs with live count badges
• Status · timing · size as prominent mono stat chips
• Script test results inline (pass / fail per test() block)
• Assertion results with actual vs. expected values
• Visual captures — bru.visualize() renders arbitrary HTML in the response pane

📤 Export & docs

• OpenAPI 3.0 export — convert any collection to a full spec with paths, methods, and request/response schemas derived from captured examples
• Static HTML docs — one-click self-contained documentation page from your .http collection; drop the output into any static host

---

⌨️ Keyboard Shortcuts

Action	Shortcut		Action	Shortcut
Filter / search collection	⌘K		Send request	⌘↩
Navigate tree items	↑ / ↓		Save to file	⌘S
Expand / collapse folder	→ / ←		Open environment picker	⌘E
Focus URL bar	⌘L		Switch response view	⌘1 – ⌘9

---

📝 .http Directives

Forge extends the standard .http format with # comment directives. They are intentionally # comments — invisible to VS Code REST Client, JetBrains, and httpYac — so your files stay fully compatible with any tool that already reads them.

### Create user
POST {{host}}/users
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "name": "Sara",
  "role": "admin"
}

# @tag       smoke auth-flow                ← label requests; searchable in tree
# @auth      bearer {{token}}               ← auth: bearer|basic|apikey|oauth2|digest|ntlm|aws4|oauth1|wsse
# @capture   userId = body.data.id          ← extract value → {{userId}} for later requests
# @assert    status == 201                  ← pass/fail; CLI exits non-zero on any failure
# @assert    body.data.role == admin        ←   ops: == != > < >= <= contains matches exists empty
# @assert    timingMs < 500
# @form      key = value                    ← form field (urlencoded; multipart if any @file)
# @file      attachment = /path/to.pdf      ← file upload part (→ multipart/form-data)
# @body-file /path/to/payload.bin           ← raw binary body
# @graphql                                  ← sends body as GraphQL query (trailing {…} = variables)
# @script:pre
#   req.setBody(JSON.stringify({ ts: Date.now() }));
#   bru.setVar("startedAt", Date.now());
# @end
# @script:post
#   test("created", () => expect(res.status).to.equal(201));
#   bru.setVar("userId", res.json.data.id);
# @end

run-all exits non-zero if any assertion fails, so a .http file doubles as an API test suite in CI with no extra tooling. Directives are plain # comments — other .http tools silently ignore them.

---

🏗️ Architecture

forge/
├── crates/
│   ├── forge-core/        # Pure parser + model + import/export — no I/O, fully headless-testable
│   │   ├── src/model.rs          # HttpFile, HttpRequest, Auth, Capture, Assertion…
│   │   ├── src/parser.rs         # .http parser
│   │   ├── src/capture.rs        # Write response back into .http file
│   │   ├── src/import_collection.rs  # Postman / Bruno collection import
│   │   ├── src/import_openapi.rs     # OpenAPI / Swagger import
│   │   ├── src/export_openapi.rs     # .http → OpenAPI 3.0 JSON
│   │   ├── src/docs.rs               # Static HTML docs generator
│   │   └── tests/                    # Integration tests
│   ├── forge-engine/      # Async HTTP execution + scripting + variable interpolation
│   │   ├── src/exec.rs        # reqwest client, proxy, TLS, streaming
│   │   ├── src/script.rs      # Boa JS sandbox (req / res / bru / expect / test)
│   │   ├── src/runner.rs      # Collection runner (chaining, assertion gate, exit code)
│   │   ├── src/interpolate.rs # {{var}} resolution
│   │   ├── src/auth.rs        # All 12 auth scheme implementations
│   │   └── src/assert.rs      # Assertion evaluation
│   ├── forge-history/     # SQLite history store (per-endpoint response timeline)
│   └── forge-cli/         # CLI front-end (parse / run / run-all / import / history / curl)
└── app/
    ├── src-tauri/         # Tauri backend — bridges Rust engine to the frontend via commands
    └── src/               # Vanilla TypeScript + Vite frontend (no framework)
        ├── main.ts        # All UI logic, DOM rendering, event wiring
        ├── pure.ts        # Pure utility functions (unit tested)
        └── styles.css     # CSS custom properties, full theme system, density modes

A Cargo workspace: forge-core is fully decoupled from I/O, so it stays unit-testable headless. The desktop app is a thin Tauri layer — the same forge-engine that powers the CLI also powers every "Send" button click in the GUI.

---

🚀 Build & Run

Prerequisites

• Rust stable toolchain
• Node.js 18+ and npm
• Platform build tools: Xcode Command Line Tools (macOS) · Visual Studio C++ build tools (Windows) · build-essential + libwebkit2gtk-4.1-dev (Linux)

Desktop app

git clone https://github.com/quietkit/Forge.git
cd Forge/app
npm install
npm run tauri dev        # launch with hot-reload
npm run tauri build      # produce a signed native bundle
                         # → .dmg / .app        (macOS)
                         # → .msi               (Windows)
                         # → .deb / .AppImage   (Linux)

CLI

cargo build --release
# or: cargo install --path crates/forge-cli

forge parse   <file.http>                          # parse → JSON model
forge run     <file.http> -r <n>                   # execute request n
forge run     <file.http> -r 1 -e token=abc --save # interpolate + capture response into file
forge run-all <file|dir>                           # collection runner (assertions → exit code)
forge curl    <file.http> -r <n>                   # print as cURL command
forge import  <collection.json> -o <dir>           # import Postman / OpenAPI / Bruno → .http
forge history <file.http> [-r <n>]                 # show recorded response timeline

Tests

cargo test               # Rust test suite across all crates
cd app && npm test       # TypeScript unit tests (pure.ts helpers)

---

📦 Install

Pre-built binaries

Grab the latest release for your platform from Releases:

Platform	File
macOS (Apple Silicon)	Forge_x.y.z_aarch64.dmg
macOS (Intel)	Forge_x.y.z_x64.dmg
Windows	Forge_x.y.z_x64-setup.exe
Linux (Debian/Ubuntu)	forge_x.y.z_amd64.deb
Linux (AppImage)	forge_x.y.z_amd64.AppImage

Homebrew (macOS)

brew tap quietkit/forge https://github.com/quietkit/Forge.git
brew install --cask quietkit/forge/forge

The app is not yet notarized; if macOS blocks the first launch, run xattr -cr /Applications/Forge.app.

---

🗺️ Roadmap

Phase	Scope	State
0	Project setup, icon, license	✅
1	forge-core: .http parser + model + CLI + tests	✅
2	forge-engine: HTTP execution + {{var}} interpolation	✅
3	forge-history: SQLite history + capture-response-into-file	✅
4	Desktop app (Tauri): tree + run + response pane	✅
5	UI variables, Send+Save capture, history diff, themes	✅
6	Cross-platform CI + release packaging	✅
7	Environments, request chaining, JSON viewer, copy-as-cURL	✅
8	Assertions + collection runner	✅
9–10	Auth: bearer / basic / API key / OAuth 2	✅
11	Collection search & filter, collapsible groups	✅
12	GraphQL body mode	✅
13	Cookie jar · cURL import · multipart/binary · capture button	✅
14	Postman import · request tags · expanded auth (digest/ntlm/aws4/oauth1/wsse)	✅
15	Pre/post-request scripting (req, res, bru.*, expect, test)	✅
16	Editable auth/form/scripts in UI · dirty-state save workflow	✅
17	OpenAPI export · HTML docs generation	✅
18	Bruno-parity UI polish (typography, params table, response panel)	✅
19	Homebrew cask · code-signed macOS release	🔜
20	gRPC / WebSocket body modes	🔜
21	Plugin system (custom auth schemes, body renderers)	🔜

Pull requests welcome on any item marked 🔜.

---

🤝 Contributing

Forge is MIT — fork it, use it commercially, and contribute back what you find useful.

High-impact contributions:

1. Bug reports — attach a minimal .http file + steps to reproduce
2. Engine integration tests — test HTTP execution paths against a local mock server
3. New body modes — gRPC, WebSocket, Server-Sent Events
4. UX feedback — if something feels off, open an issue; screenshots welcome

Please open an issue before a large PR to align on approach.

---

💛 Credits

Forge is designed, built, and maintained by Gamal Anwar — creator and lead developer.
🐙 @GamalAnwar

Published under Quietkit, an indie studio crafting fast, private, native desktop tools.

---

📄 License

MIT License.

Forge is free and open-source. Use it, fork it, build on it — commercially or otherwise — with minimal restrictions. See LICENSE for details.