bonk is a local-first desktop API client for HTTP and gRPC, built with Tauri, Svelte and Rust. You open a folder, send requests, and save them as readable *.bonk.json files. Review them in Git like any other source file.
Download the Windows installer (x64) from GitHub Releases and run the setup wizard.
Linux
Download an .AppImage, .deb or .rpm (x64) from GitHub Releases.
# AppImage, from the download directory
chmod +x bonk_*.AppImage
./bonk_*.AppImage
# Debian / Ubuntu
sudo apt install ./bonk_*.deb
Updates
Use Settings → General → Check for updates for signed in-app updates. When an update is available, the update pill lists what's new. Homebrew installs can also use:
brew upgrade --cask bonk
Command line
The bonk CLI is a separate binary for terminals and CI:
brew install nekidaz/tap/bonk
Send and save
Open a folder. An empty directory is enough.
Create an HTTP request. Enter your API URL, for example http://localhost:8080/health.
Send it. Read the status, body, headers and timing in the response pane.
Save it. Press ⌘S on macOS or Ctrl+S on Windows and Linux, then choose a collection folder.
Already have a cURL command? Paste it into the URL bar. Have a collection? Use the import window.
Reuse it with an environment
Add an environment with baseUrl = http://localhost:8080, then change the URL to:
{{baseUrl}}/health
See Variables for globals, secrets and protected environments.
Turn the response into a check
Open Scripts → Tests and add:
pm.test("Service is healthy", () => {
pm.expect(pm.response).to.have.status(200);
});
Send again and open the Tests response tab. To check a whole collection, open the Runner, choose requests and an environment, and start a run.
Layout
The directory is the source of truth. A folder is a directory, and a request is a <name>.bonk.json file.
Collection-level auth lives in .folder.bonk.json. Requests set to inherit use the nearest folder that sets auth. Manual order after drag and drop is saved in the same file. Portable Runner setups go to .bonk/scenarios.json, see Runner.
Git-friendly
Keep requests in the same repository as the API, review changes in a pull request and share the directory with your team. Preferences, history and session state live separately in the platform application-data directory.
Build a request
Set the method and URL, then add query parameters, headers, auth and a body. Supported bodies are JSON, text, form, multipart, binary and GraphQL. The JSON body editor flags syntax errors as you type. Per-request timeout, redirect and TLS overrides are available from the request's actions menu.
Paste a cURL command into the URL bar to turn it into a request. Press ⌘↵ (Ctrl+Enter) to send.
Read the response
The response view shows status, size and timing, formatted JSON, headers and cookies. Search a JSON body or filter it with JSONPath. Large responses open in a read-only viewer with search, folding, line count and Save to file. 4xx and 5xx responses show a hint with quick actions.
Defaults
Settings → Requests applies to every request in the workspace: request timeout, follow redirects, verify SSL certificates (turn off only for local self-signed servers), JSON formatting and response preview size. Proxy and client certificates have their own pages, see Settings.
Code snippets
Generate the request as code in cURL, HTTPie, raw HTTP, C, C#, Go, Java, JavaScript, Node.js, Kotlin, PHP, Python, Ruby, Swift or PowerShell. Open the code panel with ⌘⌥E (Ctrl+Alt+E).
Find the schema
Connect to a server and use reflection, or load local .proto files. In Settings → gRPC you can turn automatic reflection on or off and add .proto import paths (-I). Pick a service and method, and bonk fills in a message template for you to edit.
Make a call
Unary, server-streaming, client-streaming and bidirectional calls are supported. Streams from all four kinds appear in one feed. Set metadata and a deadline per request. The default deadline, maximum message size and default-field display live in Settings → gRPC.
TLS and mTLS
gRPC supports TLS and client certificates, including PKCS#12 (.p12) bundles. Errors are shown in readable form.
Scripts, Runner, CLI, MCP
gRPC requests accept the same scripts as HTTP, and run in the Runner with a gRPC deadline. The CLI and MCP server execute unary calls; streaming keeps its interactive controls in the desktop app.
Auth types
Type
What bonk sends
None
No auth is added.
Bearer
Authorization: Bearer <token>
Basic
Authorization: Basic with base64 of username:password.
API key
A named key, sent as a header or as a query parameter.
Sign in once through a Runner scenario; a token per environment, renewed by itself.
An Authorization header you set yourself on the request is not overwritten.
Folder auth and inheritance
A request set to inherit uses the nearest ancestor folder that sets auth, saved in .folder.bonk.json. With no auth anywhere, nothing is sent.
Variables in auth
{{vars}} are resolved before auth is applied, so tokens can come from an environment:
Bearer token: {{token}}
Grants
Choose OAuth 2.0 as the auth type, then one of three grants:
Authorization code, with PKCE (S256) on by default.
Client credentials.
Password.
Settings
Field
Notes
Auth URL, token URL, revoke URL
The auth URL is used by the code grant.
Client ID and secret
Sent in a Basic header by default, or in the form body.
Scope, audience
Scope is space-separated.
Redirect URI
Empty means http://127.0.0.1:<free port>/callback.
Username, password
For the password grant.
Auto refresh
On by default.
Every field accepts {{vars}}, so one request can work across environments.
Tokens
Tokens live in the OS keychain, never in workspace files. The token key is a hash of the resolved settings (grant, token URL, client, scope, audience, user), so an environment with its own client gets its own token. bonk renews an expired token before sending and retries once on a 401. The same applies in the app, the Runner, the CLI and MCP.
Set it up
Open a collection's authorization and choose Session. Pick the Runner scenario that signs in (for example Auth · OTP: Login → Send OTP → Verify OTP, where the code is an «ask on send» variable), say which response holds the access token and which the refresh token, and pick the saved request that trades a refresh token for a new access token. Its body reads {{session.refresh}}. Requests of the collection then send Authorization: Bearer {{session.access}}, except the sign-in folder and the renewal request.
How it is kept alive
The access token is renewed by itself a minute before it expires (a JWT's exp, or a field like expires_in), and once on a 401.
When the refresh token is dead too, the sign-in scenario runs again on its own; only the step that needs a code asks you, in a small form by Send.
After you run the sign-in scenario in the Runner, bonk offers Запомнить вход? to keep what it caught.
One session per environment
Signing in to Staging does not touch Production. All sessions lists every environment: who signed in, when the tokens end, renew, sign out. Sessions live in the OS keychain, not in workspace files, git or exports. In the CLI, --env picks the session; a sign-in step needs --input otp=123456.
Using variables
Write {{name}} anywhere in a request:
{{baseUrl}}/v1/payments/{{paymentId}}
Globals and environments
Variables come from globals and from named environments. Edit values inline in the environments sheet (⌘E / Ctrl+E). Mark a variable as secret to keep its value in the OS keychain. Environment names are unique.
A protected environment asks for confirmation before a request is sent to it.
Other sources
Dynamic variables such as {{$guid}} give a fresh value on every send.
Scripts read and write variables with pm.environment, pm.globals and pm.variables.
The Runner turns CSV or JSON rows into variables, one iteration per row.
The CLI reads BONK_VAR_<NAME> and --var NAME=VALUE.
CLI precedence
In the CLI, later wins: the app's globals, scenario globals, scenario environment, the --env environment, BONK_VAR_<NAME>, --var, then the data row.
Using them
Type {{$ in a URL, header, body or script editor to get completion, or open the reference dialog and click Insert. The values are generated in Rust at send time.
$randomPrice, $randomCurrencyCode, $randomBankAccountIban, $randomCity, $randomCountry, $randomLatitude, $randomFileName, $randomMimeType and more
The full list is in the reference dialog. $uuid is a synonym of $guid.
Settings → Variables
Test data language: English (US) or Russian (KZ) names, addresses and phones.
One value per request: {{$guid}} in a header and in the body match. Off gives a new value at every occurrence.
Keep substituted values: shown in the response Timeline tab.
Repeatable values (seed): the same seed gives the same data on every send and Runner run.
The jar
Set-Cookie headers from responses go into the jar automatically. On the next request, cookies matching the domain and path are added to the Cookie header. Open the jar from the cookie window or the footer chip, and see each response's cookies in the response Cookies tab.
Settings → Cookies
Setting
Effect
Store cookies from responses
Put Set-Cookie into the jar.
Send cookies with requests
Add matching cookies to the Cookie header.
Keep across restarts
On: session cookies survive a restart. Off: they live until bonk closes.
Whose jar
Per workspace (a file for each) or shared by the whole app.
Never store for domains
Cookies of these domains and their subdomains are neither stored nor sent.
In scripts
Scripts can read cookies with pm.cookies.get(), has() and toObject(), and clear a URL's cookies with pm.cookies.jar().clear(url).
The Scripts tab
Each HTTP or gRPC request has a Scripts tab with two parts: Pre-request runs before sending, Post-response runs after the response. The editor has completion, an outline, Find, folding and Format. Results appear in a Tests / Console panel. Scripts run in an embedded JavaScript sandbox (QuickJS) in the Rust engine, so they behave the same in the app, Runner, CLI and MCP.
API
Object
Members
pm.environment, pm.globals
get, set, unset, has, toObject
pm.variables
get, set, has, replaceIn, toObject
pm.iterationData
get, has, toObject (Runner data rows)
pm.cookies
get, has, toObject, jar().clear(url)
pm.request
url, method, body, headers.add/upsert/get/remove
pm.response
json(), text(), code, responseTime, headers.get
pm.test(name, fn), pm.expect(value)
chai-style matchers: equal, eql, ok, above, below, include, match, property, lengthOf, status and more
console.log, JSON
Output goes to the Console panel.
Examples
// Pre-request: add a header
pm.request.headers.add('X-Request-Id', pm.variables.get('requestId'));
// Tests: check and save a field for the next request
pm.test('created', () => pm.expect(pm.response).to.have.status(201));
pm.environment.set('paymentId', pm.response.json().id);
Start a run
Open Runner, pick a collection or folder (or right-click one in the tree and choose Run in Runner), and set up the run. You can select and drag to reorder requests, choose an environment and set the delay between requests. Pause, resume or stop a run in progress.
Data-driven runs
Attach a CSV or JSON file: each row is an iteration and each column is a variable, readable with {{column}} or pm.iterationData. A JSON file must be an array of objects. The row count sets the number of iterations.
Steps that ask for input
Right-click any {{variable}} in a request and choose Ask on send: an SMS code, an amount, a currency, a confirmation. Pick a type (text, number, code, secret, choice, yes/no, JSON, file), a label and checks. Send opens a small form by the button; the Runner stops at that step, shows the form in the run log and goes on after the answer. A 4xx on a step with typed input opens the form again (three tries). A file field goes as a path where a request takes a file and as base64 where it sits in a text body (up to 10 MB). Give a code a lifetime and the card counts it down; Resend runs the step before again (the one that sent the code) and asks once more. The value lives only in that run: it is not saved to environments, history or run records, and a code is shown as ••••13 in the log. The field definitions are stored in .bonk/inputs.json, so commit it. In the CLI nobody can type: pass the value with --input otp=123456 or BONK_INPUT_otp, or the step fails.
Run settings
Stop on first failure.
Save responses: for the report and for comparing runs.
A gRPC deadline for gRPC requests.
Results
Results show per-iteration status, timing, a waterfall and test details. Rerun only the failed requests, reopen past runs from history and export a JSON report.
Scenarios
Choose Save to workspace to store the setup in .bonk/scenarios.json: relative request paths, public variable defaults, iterations, delay and stop-on-failure. Secret values and secret-named data columns are omitted, only the required names are kept. Commit the file, then repeat the same run in the CLI or from MCP:
BONK_VAR_TOKEN="$TOKEN" bonk run --workspace ./api --scenario smoke
Install
Homebrew on macOS and Linux, or a single binary from GitHub Releases on any platform.
brew install nekidaz/tap/bonk
# or a release archive (bonk.exe on Windows)
curl -L https://github.com/nekidaz/.bonk/releases/latest/download/bonk-aarch64-apple-darwin.tar.gz | tar -xz
Run a collection
Point it at the whole workspace, a folder or a single request. Environments are the ones saved in the app.
# the whole workspace (run from its root)
bonk run
# a folder and one request, with an environment
bonk run api/users api/health.bonk.json --env Staging
# CI: stop at the first failure, write a JUnit report
BONK_VAR_TOKEN=$TOKEN bonk run api --bail --junit report.xml
Exit codes
Code
Meaning
0
Every request passed
1
Something failed: status, test or script
2
The run couldn’t start: bad path, unknown environment, invalid data file
Secrets
Data, scenarios and network
--data users.csv runs one iteration per CSV or JSON row.
--var NAME=VALUE sets a variable. --json report.json writes a JSON report.
--workspace DIR --scenario NAME repeats a scenario saved in the workspace from any directory.
--app-state FILE reads the app's globals and environments from another state.json.
Proxy and TLS: --proxy, --no-proxy, --cacert, --cert / --key, --p12 and -k.
Run bonk run --help for every flag.
One-click setup
Open the workspace the AI should use, then Settings → AI / MCP.
Choose whether to allow workspace edits and API calls, an environment, and an optional host allowlist.
Click Install for all clients and restart the configured apps.
bonk configures Claude Desktop, Claude Code and ChatGPT/Codex. Existing client settings are preserved, and a *.bonk-backup is made before the first change. Remove from clients removes only the bonk entry. The desktop app does not need to stay open.
What the agent can do
List, read, create, update, rename, move, duplicate and delete requests and folders.
Validate, send or run saved HTTP requests, with scripts and tests.
Reflect gRPC schemas, compile local .proto files, generate examples and make unary calls.
Run a saved scenario with run_scenario.
Steps that ask for input: list_inputs shows the fields, inputs carries values the user gave the agent, and a missing one is asked from the user through MCP elicitation (a confirmation always is).
A non-loopback bind needs a token, at least one --mcp-host, and either --target-host or --allow-all-targets. Terminate TLS at a reverse proxy. Run bonk-mcp --help for every option.
Everyday work
Open the Source Control tab to see changed requests. Stage and commit, view diffs inline or side by side, stage or discard individual lines, and use stashes. Branches show ahead and behind counts, and Pull, Push and publish are available. Auto-fetch keeps the status current. Remotes are managed in settings.
History and graph
A commit graph supports cherry-pick, revert, reset, tags, compare and Undo. You can also see the Git history of a single request, use interactive rebase and the reflog, and clone a repository.
Conflicts
Conflicts open in a three-way merge that can merge a request field by field.
Import
One import window handles everything. Bring a source from a file, a link, a paste or a drop, and the format is detected from the content.
Format
Notes
OpenAPI 3.x, Swagger 2.0
Group by tags, paths or flat. Servers become environments, body examples come from the schema.
Postman v2.1
Collections and variables.
Insomnia v4
Export files.
HAR
Choose which request types to take.
cURL
One or more commands, also pasteable into the URL bar.
A preview with warnings comes before anything is written. Re-importing a source offers update from spec, which updates the collection and keeps your edits. For gRPC, load .proto files in the gRPC editor.
Export
In Settings → Data and import, export the workspace as Bonk JSON or Postman Collection v2.1. Keychain secret values are not exported unless you turn on Include secrets.
The CLI can import a version-1 Bonk JSON export:
bonk import export.json --workspace ./api
Code snippets
Any request can be copied as cURL or generated as code. See HTTP.
Request
Action
macOS
Windows/Linux
Send request
⌘↵
Ctrl+Enter
Save
⌘S
Ctrl+S
Save As
⇧⌘S
Ctrl+Shift+S
Request code
⌥⌘E
Ctrl+Alt+E
New request
⌘N
Ctrl+N
New gRPC request
⌥⌘N
Ctrl+Alt+N
New collection
⇧⌘N
Ctrl+Shift+N
New folder
⇧⌘F
Ctrl+Shift+F
Expand editor or response
⌥⌘F
Ctrl+Alt+F
Show / collapse response
⇧⌘R
Ctrl+Shift+R
Show / collapse request body
⇧⌘E
Ctrl+Shift+E
Navigation
Action
macOS
Windows/Linux
Command palette
⌘K
Ctrl+K
Environment
⌘E
Ctrl+E
Show / hide sidebar
⌘\ or ⌘B
Ctrl+\ or Ctrl+B
Collections
⌘1
Ctrl+1
History
⌘2
Ctrl+2
Bottom panel
⌘J
Ctrl+J
Terminal
⌃`
Ctrl+`
Issues
⇧⌘M
Ctrl+Shift+M
Issues full height
⇧⌘J
Ctrl+Shift+J
Switch workspace
⇧⌘O
Ctrl+Shift+O
Open workspace folder
⌘O
Ctrl+O
Settings
⌘,
Ctrl+,
Tabs
Action
macOS
Windows/Linux
New tab
⌘T
Ctrl+T
Close tab
⌘W
Ctrl+W
Close all tabs
⌥⌘W
Ctrl+Alt+W
Reopen closed tab
⇧⌘T
Ctrl+Shift+T
Next tab
⌃Tab
Ctrl+Tab
Previous tab
⌃⇧Tab
Ctrl+Shift+Tab
Pages
Page
What it controls
General
Interface language (English or Russian), what opens on startup (empty window or last tabs), tab behavior, confirm closing unsaved tabs, check for updates.
Requests
Request timeout, follow redirects, verify SSL certificates, format JSON, response preview size, wrap long lines.
Variables
Dynamic variable language, one value per request, keep values, seed.
Import, export, history retention and the data folder.
Themes
Bonk Dark, Bonk Light, Gruvbox Dark, Catppuccin Mocha, Nord and Solarized Light ship with the app. You can follow the system appearance, pick a theme with ⌘K, and import Zed or VS Code themes.
Where data lives
Requests are in the workspace folder. Preferences, history and session state are in the platform application-data directory, shown under Data and import. Secret variables use the OS keychain.
0.2.0
Released 2026-10-11.
Git: a Source Control tab with staging, diffs, branches, a commit graph and three-way merge.
OAuth 2.0 auth: authorization code with PKCE, client credentials and password.
A Scripts tab with a results panel, dynamic variables, and a per-workspace cookie jar.
The bonk CLI with JUnit and JSON reports, and portable workspace scenarios.
New themes, a Console, terminal and Issues panel, and one import window with preview.
HTTP Send and unary gRPC use the same execution pipeline as collections, CLI and MCP. The Flows canvas was removed.
0.1.9
Released 2026-10-10.
The window adapts down to 720×520, and large workspaces open with folders collapsed.
{{vars}} resolve before auth, and MCP sends HTTP requests like the app does.
0.1.8
Released 2026-10-09.
Drag and drop in the sidebar tree, a large-response viewer, Save As, and PKCS#12 client certificates.
Runner presets, Postman export, and folder-level auth.