Quickstart

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

1. Install bolla

One command. Detects your OS and chip, downloads the right binary, places it in /usr/local/bin.

curl -fsSL https://bolla.cikubo.it/install.sh | sh

Works on macOS (Apple Silicon & Intel) and Linux (x86_64 & ARM64). Verify:

bolla --version

No runtime needed. bolla is a single binary with zero dependencies โ€” no Node.js, no Python, no Docker. Install once, run anywhere.

2. Open your project

Go to any folder you're working in โ€” your API repo, a new empty folder, anything โ€” and run:

bolla --server --collection .

Your browser opens automatically at http://localhost:3077 with the full bolla app. No extra steps.

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. Press Ctrl+C to stop it. 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. Add bolla to your CI pipeline

Use --ci mode for pipelines. It runs headless and exits 0 (pass) or 1 (fail) โ€” exactly what CI expects.

GitHub Actions โ€” CI run
โ–ถ Install bolla $ curl -fsSL https://bolla.cikubo.it/install.sh | sh โœ“ bolla installed โ†’ /usr/local/bin/bolla โ–ถ API smoke test $ bolla --ci --scenario smoke --env staging bolla ci โ€” scenario: smoke ยท 20 VUs ramp ยท 30s โœ“ p95 latency 198ms โ‰ค gate 500ms โœ“ error rate 0.0% โ‰ค gate 1% โœ“ throughput 287/s โ‰ฅ gate (none) All gates passed. Reports โ†’ .bolla/runs/run_abc123/junit.xml ยท result.json

GitHub Actions example:

- name: Install bolla
  run: curl -fsSL https://bolla.cikubo.it/install.sh | sh

- name: API smoke test
  run: bolla --ci --scenario smoke --env staging
  env:
    BOLLA_VAR_TOKEN: ${{ secrets.API_TOKEN }}

Publish JUnit results as inline PR annotations: add EnricoMi/publish-unit-test-result-action@v2 pointing at .bolla/runs/**/junit.xml. Gate failures will show up as failed checks on your PR.

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: '[]'

Start the mock server:

bolla --mock --collection . --mock-port 3078

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
$ bolla --mock --collection . --mock-port 3078 bolla mock โ€” 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