quark

README

Quark

A local-first, keyboard-driven HTTP client. No cloud. No accounts. No data leaves your machine.

Quark is a terminal-native TUI that keeps everything in a local SQLite database, with a scriptable CLI for automation and CI. You get the ergonomics of a GUI without the surveillance.

---

Installation

One-liner

macOS / Linux / Git Bash:

curl -sL https://github.com/crazy-vedic/Quark/releases/latest/download/install.sh | bash

Windows PowerShell (native Windows):

irm https://github.com/crazy-vedic/Quark/releases/latest/download/install.ps1 | iex

Specific version or platform:

curl -sL https://raw.githubusercontent.com/crazy-vedic/Quark/master/install.sh | bash -s -- --version v1.0.0 --platform linux-amd64

Private repos: set GITHUB_TOKEN or GITHUB_ACCESS_TOKEN — auth headers forwarded automatically.

From source

git clone https://github.com/crazy-vedic/Quark.git && cd Quark
make build && make install

On native Windows, the Makefile requires a Unix-compatible shell. With the Go toolchain installed, build directly from PowerShell instead:

git clone https://github.com/crazy-vedic/Quark.git
cd Quark
go build -o quark.exe ./cmd/quark

Run ./quark.exe, or move it to a directory on your PATH.

---

Quick Start

quark                         # Launch TUI
quark collection create "API" # Create collection
quark import curl "curl -X POST https://api.example.com/orders" --collection <id> --name "Create Order"
quark run "API/Create Order"  # Execute saved request
quark collection list         # List all collections

---

Features

• Local SQLite — ~/.quark/quark.db, WAL mode, no network
• Collections & requests — Organise, sort, enable/disable
• Import — cURL and Postman Collection v2.1 from the CLI or TUI
• Response preview — Syntax-highlighted JSON, streaming for large bodies
• Themes — Terminal-aware dark and light palettes, local custom themes, live preview and reload
• Fuzzy search — / to search across everything
• Auto-backup — Last 10 backups in ~/.quark/backup/
• Signal-aware — SIGINT cancels in-flight, restores terminal
• Scheduling — Persist due times with quark schedule add; Quark is not a background daemon. Runs fire when you invoke quark schedule run-due (cron/systemd/CI) or while the TUI is open (in-app timer)

Import a cURL command in the TUI

Press I to open the multiline cURL importer. Ctrl+V reads the complete clipboard, Ctrl+S parses it, and Enter confirms the preview. The importer preserves repeated headers, request bodies, JSON, URL-encoded data, and multipart text fields.

--cert/--cert-type P12, PEM --cert plus --key, and --cacert are saved as host-scoped TLS configuration. File- or stdin-backed bodies, shell expansions, redirections, and multiple URLs are rejected rather than executed.

From the TUI sidebar, press I to import a Postman Collection v2.1 JSON file or bulk export directory; i opens the cURL importer. Existing collection names are imported as numbered copies. The same import is available with quark import-postman <file-or-directory>.

Use quark collection rename <collection> <new-name> and quark collection delete <collection> to manage collections from scripts. quark cert list, quark cert set <host> --file <path>, and quark cert delete <host> manage host-scoped TLS client certificates. For PKCS#12 files, prefer --password-env to keep passwords out of shell history.

quark run <Collection/Request> prints the response body after its status summary. Valid JSON is pretty-printed and syntax-highlighted in a terminal. Add --verbose to print request details and response headers to stderr; this can include credentials from the saved request.

---

Themes

Quark starts with auto, which chooses a dark or light palette from the terminal background while preserving that background. dark and light paint their own backgrounds. transparent also preserves the terminal background and follows its contrast.

In the TUI, press /, then type the > character followed by theme to switch request search into the command palette. Use Up/Down to preview a theme. Press Enter to save it, or Esc to restore the previous theme. You can also use:

quark theme list
quark theme set light
quark theme validate
quark --theme dark tui          # one session only

For a custom theme, create <config-dir>/themes/ocean.toml (the default config directory is ~/.quark):

extends = "dark" # or "light"

[colors]
foreground = "#c0caf5"
background = "#1a1b26" # use "transparent" to inherit the terminal
muted = "#737aa2"
accent = "#7aa2f7"
info = "#7dcfff"
success = "#9ece6a"
warning = "#e0af68"
error = "#f7768e"
active_border = "#ffffff"
match = "#e0af68"
get = "#9ece6a"
post = "#7aa2f7"
put = "#e0af68"
delete = "#f7768e"
syntax = "monokai" # Chroma style for JSON

Every color is optional and inherits from extends. Colors use six-digit hex values. The filename is the theme name: run quark theme validate ocean, then select ocean in the TUI or use quark theme set ocean. Quark checks the active custom theme file every two seconds and reloads valid edits. An invalid edit leaves the last working palette in place and shows an error.

The TUI chooses a theme in this order: --theme, QUARK_THEME, [ui].theme in config.toml, then auto. --config moves both config.toml and themes/ to the selected directory.

---

Migrate From Postman

Quark can import both a single Postman Collection v2.1 JSON file and a full Postman bulk export directory.

1. Export from Postman

You can migrate using either of these:

• Single collection export: export a collection as Collection v2.1 JSON
• Bulk export directory: export your workspace/archive so you get a directory containing collection files and, if present, environment files

2. Import into Quark

Single collection JSON

quark import-postman ./MyCollection.postman_collection.json

Bulk export directory

quark import-postman ./postman-export/

Override the imported collection name

quark import-postman ./MyCollection.postman_collection.json --collection-name "Payments API"

Control duplicate handling

quark import-postman ./postman-export/ --on-duplicate merge

Supported duplicate actions:

• duplicate — keep both, with a new unique collection name
• merge — merge requests into the existing collection
• replace — replace the existing collection
• skip — leave the existing collection untouched

3. What gets migrated

• Collections and requests
• HTTP method, URL, headers, and body
• Common auth styles that can be mapped into Quark requests
• Environment files found in a bulk export directory. Postman environments are preserved by name as selectable environments on each imported root collection; explicit Postman globals are merged into Quark's Global environment.

4. Recommended migration flow

1. Export one Postman collection or a bulk export directory
2. Run quark import-postman ...
3. Open quark and inspect the imported collection in the TUI
4. Verify active environments and request auth on a few important requests
5. Run a smoke request with:

quark run "Collection Name/Request Name"

5. Notes

• Quark is local-first: imported data is stored in ~/.quark/quark.db
• If your Postman requests depend on {{variables}}, importing the bulk export directory is best because Quark can also import environment files from it
• Select the desired imported environment for the root collection with quark env active <collection-id> <environment-name> before running a request; descendants inherit that root selection and can also have their own active environment
• If a request needs cleanup after import, you can edit URL, body, headers, auth, and environments directly in the TUI

---

Development

Agent documentation lives in .agents/INDEX.md — start there when working with AI agents.

make build       # Build
make run         # Run
make ut          # Unit tests (race)
make e2e         # End-to-end
make test        # All tests
make lint        # Lint + format
make clean       # Clean
make install     # Install to GOPATH/bin

CI

Build → lint → unit tests (gotestsum, race) → e2e → security scan.

Releases

Automated on PR merge.

1. Open a PR
2. Add Release: v1.0.0 to the PR body
3. Merge to main
4. GitHub Actions creates the tag and builds the release

To skip: omit the Release: line.

---

Requirements

• Go 1.26+ (for building from source)
• Terminal with 256-color support

License

MIT