Quickstart

From zero to your first API test in under 2 minutes, no account, no config, no cloud.

1. Download & install

Download bolla.dmg, open it, and drag bolla into Applications. No terminal, no package manager.

First launch only: bolla is in beta and not yet code-signed (no Apple Developer account, yet). macOS will show a warning the first time. Right-click bolla.app → Open → confirm, or go to System Settings → Privacy & Security and click "Open Anyway". Prefer the terminal? xattr -cr /Applications/bolla.app does the same thing in one line.

Found a bug during beta? Email info@cikubo.it.

2. Open bolla

Double-click the app in Applications (or Spotlight → "bolla"). A native window opens immediately, bolla starts its own local engine in the background, no server to configure, no port to remember.

By default your requests are saved in ~/bolla. Everything is plain .bolla.yaml files you can move into any git repo whenever you want.

bolla, localhost:3077
bolla my-api No environment No requests yet. ＋ New request Welcome to bolla Select a request from the sidebar, or create a new one ＋ Create first request

Keep bolla running in the background while you work, just close the window or quit the app when you're done. All your requests are saved as plain .bolla.yaml files in your project, you can commit them to git like any other file.

3. Create your first request

Click ＋ New request in the sidebar (or the button on the welcome screen). A modal appears, fill in a name, pick a method, and paste your URL. That's all.

bolla, new request
New request NAME List users METHOD GET URL https://jsonplaceholder.typicode.com/users Create Cancel

Click Create. The request is saved as a .bolla.yaml file in your project and appears in the sidebar immediately.

4. Send the request

Click the request in the sidebar to open it. Add assertions if you want, then press Send (or Cmd/Ctrl + Enter).

bolla, localhost:3077
bolla my-api No environment ROOT GET List users GET https://jsonplaceholder.typicode.com/users Send Body Headers Auth Assertions 200 312ms BODY [ {"id": 1, "name": "Leanne Graham", "email": "... {"id": 2, "name": "Ervin Howell", "email": "... ... ✓status_code = 200 ✓elapsed_ms 312 ≤ max 2000

The response appears at the bottom. Green ticks mean all assertions passed. If something fails you'll see exactly which check failed and what value it got.

5. Use environments to switch between staging and prod

Create an environment file next to your requests. You can have as many as you want, local, staging, production, etc.

# staging.env.yaml
id: staging
name: Staging
vars:
  base_url: https://api-staging.example.com
  TOKEN: ""   # set via env var BOLLA_VAR_TOKEN in CI

Update your request URL to use the variable:

url: "{{base_url}}/users"

Now select the environment from the dropdown in the top bar, bolla substitutes all {"{{vars}}"} automatically.

bolla, environment switcher
ENVIRONMENT staging ✓ production local ACTIVE VARIABLES · staging base_url → https://api-staging.example.com TOKEN → •••••••• (from BOLLA_VAR_TOKEN) URL preview: GET https://api-staging.example.com/users

6. Run a load test

Create a scenario file describing how to ramp up load and what performance gates to enforce:

# smoke.scenario.yaml
id: smoke
name: Smoke, basic latency check

load:
  type: ramp
  start_concurrency: 1
  end_concurrency: 20
  duration_s: 30

steps:
  - request_id: get-users    # references your .bolla.yaml by id

gates:
  p95_ms:    { max: 500 }    # fail if p95 latency exceeds 500ms
  error_pct: { max: 1.0 }    # fail if more than 1% of requests error

Run it from the terminal:

bolla --load --scenario smoke.scenario.yaml --env staging

Or click Run load test in the UI and pick the scenario from the dropdown. Watch the chart update live:

bolla, load test · smoke · running 18s / 30s
p50 latency 74ms p95 latency 198ms requests/sec 287 error rate 0.0% Latency (ms) over time 400 300 200 100 0 gate 500ms p95 latency p50 latency 18s / 30s · 20 VUs active

7. CI/CD gates, coming soon

Load scenarios already support pass/fail gates (latency budgets, error rate limits, throughput minimums) evaluated live in the app's Load tab. A headless, pipeline-friendly build for GitHub Actions / GitLab / Jenkins is planned for a future release, for now bolla is a native macOS app.

Want to be notified when the CI build ships? Email info@cikubo.it.

8. Spin up a mock server for local dev

Add named examples to any request file:

examples:
  - name: success
    status: 200
    body: '[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]'
  - name: empty
    status: 200
    body: '[]'

Open the Mock tab in the app, pick your collection folder and a port, and click Start.

Now http://localhost:3078/users returns your example response. Select a different example with a header: X-Bolla-Example: empty. Your frontend team can develop against it without touching a real backend.

bolla, mock server · localhost:3078
Mock tab → Start (collection: ".", port: 3078) running, 3 routes ready on http://localhost:3078 GET /usersexamples: success, empty | auto-generate: on POST/usersexamples: created, error GET /users/:idauto-generate: on → GET /users 200 [success example] → GET /users X-Bolla-Example: empty 200 [] → GET /users/42 200 [auto-generated: id=42, name="Rhett Buckridge", ...]

You're done. You now know everything you need to use bolla day-to-day. Explore the full reference for OAuth2, OpenAPI import, the AI assist module, and more.

← PreviousOverview Next →Full reference