Bristle / Get started

Get started

Start with one collection. You can explore Bristle without creating an account.

1. Install the Mac beta

Open Apple menu → About This Mac. If it lists an Apple M-series chip, choose Apple Silicon. If it lists an Intel processor, choose Intel Mac.

Download for Apple Silicon Download for Intel Mac

macOS · 0.1.11 Beta 1 · Free during beta

Open the downloaded DMG.
Drag Bristle into Applications.
Open Applications in Finder and launch Bristle. Eject the disk image afterward.

The app and disk image are signed and notarized. If macOS reports a damaged app or an unidentified developer, stop and report the message; do not disable Gatekeeper. Checksums and verification records are available.

Early beta: use a copy of your collection and test credentials for your first evaluation. Broader macOS version coverage and migration from earlier unsigned builds have not been established. Signing does not replace your organization’s software approval.

2. Send your first request

Choose Create a collection, enter a name, and select its parent folder. Or choose Explore a sample collection.
Choose New request, name it, and enter a URL you intend to call. Select the method and add parameters, headers, a body, or authentication.
Choose Send or press ⌘ Enter. Inspect the response body, headers, prepared request, timing, tests, and logs.
Choose Save or press ⌘ S to write the request definition to your collection files.

Sending the sample’s requests contacts httpbin.org. To explore without an upstream API, use the sample’s illustrative saved examples with Collection settings → Open mock server; the mock listens on your own machine.

3. Keep drafts and saved work distinct

Selecting a request opens a replaceable preview. Editing or sending does not pin it. Choose Keep open or double-click a request to retain it in that collection.

Draft saved locally means a private checkpoint was written. Save updates your readable collection files. Closing a view preserves its draft; find it under Drafts. Discard is a separate action.

Use ⌘ P to find a request and Open work to see working sets across collections. Settings contains the full keyboard reference.

4. Set up named environments and secrets

Choose Environment → Manage and create profiles such as Development, Staging, and Production.
Add variables such as baseUrl. Use the secret toggle for sensitive values, and mark the production profile clearly.
Select the collection environment. Check Send environment beside the request before sending; a request can override the collection choice in its Settings.
Type {{ in a request field to insert a variable or secret reference. Suggestions show names and scope, never secret values.

Resolved variables explains where values come from. If a secret is missing after import or on another device, bind it locally. Never put a real secret into a public issue or screenshot.

5. Bring existing requests

Use Import / Export to preview files before applying an import. Keep the original export or collection as a backup.

Postman: import v2.1 collection and environment exports. Review conversion warnings, inherited authentication, variables, and scripts; not every Postman feature is supported.
OpenAPI: import 3.0.x and 3.1.x specifications. Preview operations and warnings. Exports can preserve an imported contract or produce a reviewed proposal from saved requests.
cURL: use the cURL dialog to create a draft, then review and save it.
Native Bristle collections: open a folder containing collection.yaml or import a native export. Existing version-1 Request Grove files remain compatible.

Imported scripts require explicit review before execution. Local drafts and vault values are excluded from portable exports. Arbitrary text bodies and saved examples can still contain sensitive data; review them before sharing.

Updates, backups, and removal

Updates are manual. Visit Releases, quit Bristle, and replace the app in Applications with a newer verified download. Back up collection folders and the private profile before evaluating an upgrade. Older unsigned-build Keychain migration is still unverified.

Settings → Open local data folder opens the private profile, which retains the original ~/Library/Application Support/request-workbench identity. The renamed app preserves existing file formats and profile paths.

Removing Bristle from Applications does not delete your collection folders or private profile. Handle those separately according to your retention needs.

Ready for a more structured trial? Follow the 15-minute beta guide.