Documentation

Using Tuma

Everything from your first request to load tests in CI and coding agents. New here? Start with Install and Your first request.

Quick startSend and save a request in a minute. The tuma commandTests, runs and load tests in CI. Coding agentsConnect Claude Code or Cursor over MCP.

Nothing in the docs matches that. Try another word, or ask on GitHub.

Install

Download the installer for your system from the download section or the GitHub releases.

System	File	How
Windows	`-setup.exe` or `.msi`	Run it. Your workspaces are kept when you install a newer version.
macOS	`.dmg`	Coming soon. Until then, build from source below.
Debian, Ubuntu	`.deb`	`sudo apt install ./Tuma_1.0.1_amd64.deb`
Fedora, openSUSE	`.rpm`	`sudo dnf install ./Tuma-1.0.1-1.x86_64.rpm`
Any Linux	`.AppImage`	`chmod +x Tuma_*.AppImage`, then run it.

With apt, write ./ in front of the file name. Without it, apt looks for a package of that name in its repositories and fails with "Unsupported file given on commandline".

Homebrew and winget packages are coming.

Every package includes the tuma command.

Build from source

You need Rust (stable), Node.js 20+, pnpm and the Tauri system dependencies.

git clone https://github.com/MorrisKM/Tuma.git cd Tuma/app pnpm install pnpm tauri dev # run with hot reload pnpm tauri build # build installers for your system

Your first request

Open Tuma and create a workspace, or open a folder that already has one.
Press Ctrl T for a new tab, pick a method and type a URL, such as https://httpbin.org/get.
Press Ctrl Enter to send it. The response shows its status, time, size, headers, cookies and body.
Press Ctrl S to save it into a collection. It's now a file in your workspace.

On macOS, use ⌘ wherever these docs say Ctrl.

A workspace is a folder of plain YAML files. Put it next to your code (tuma init creates .tuma/ at the root of a project) and commit it to git, so requests are reviewed and versioned like the code they test.

.tuma/ ├─ workspace.yaml # name and id ├─ environments/ │ ├─ local.yaml │ └─ staging.yaml └─ Users API/ # a collection ├─ _folder.yaml # auth, variables and scripts shared by everything inside ├─ create user.yaml └─ Admin/ # folders nest └─ delete user.yaml

A request file:

method: POST url: "{{baseUrl}}/users" description: Creates a user. headers: - { name: X-Request-Id, value: "{{$guid}}" } body: type: json content: | { "name": "Wanjiru", "role": "admin" } expect: status: 201 maxTimeMs: 500 body: - { path: $.id, exists: true }

JSON Schemas for every file are in schemas/, so editors such as VS Code can autocomplete and validate them. tuma check finds typos and checks that can't work.

You can keep several workspaces and switch between them from the workspace menu. Duplicate any request, folder or collection, and click a name to rename it. Drag requests, folders and collections in the sidebar to arrange them: drop on the top or bottom edge of a row to put it before or after, or on a folder or collection to move it inside. The order is saved in _folder.yaml, and for collections in workspace.yaml.

Environments and variables

Write {{name}} anywhere: URL, headers, body, auth, scripts and crypto keys. Typing {{ suggests the variables in scope.

# environments/staging.yaml variables: - { name: baseUrl, value: https://staging.example.com } - { name: apiKey, secret: true } # the value is in the OS keychain, not the file

Variables come from the environment, the collection and its folders; the closest one wins. Values set by scripts with pm.environment.set are kept on this computer, in Tuma's data folder, so a login token never ends up in git.

Dynamic variables

Variable	Becomes
`{{$guid}}`, `{{$randomUUID}}`	A new UUID
`{{$timestamp}}`	The current Unix time in seconds
`{{$isoTimestamp}}`	The current time, ISO 8601
`{{$randomInt}}`	A random number from 0 to 1000

Bodies and protocols

Bodies can be JSON (comments allowed while you edit), XML, HTML, text, form fields, multipart with files, or a binary file. A file path that isn't absolute is read from the workspace folder, so a request committed with ../fixtures/avatar.png sends the same file on every computer; files you pick inside the project are saved that way. Beyond HTTP, Tuma speaks:

GraphQL: queries and variables, with introspection and a schema explorer.
WebSocket: connect, send saved messages, and watch the conversation.
Server-sent events: watch an event stream as it arrives.
gRPC: methods from server reflection or your .proto files, including streaming.

The response pane shows the body (pretty, raw or preview), headers, cookies, timings, and the request exactly as it was sent, after variables, scripts and encryption. Press Ctrl F to find, or replace, in a response.

Authentication

Set auth on a request, or on a folder or collection for everything inside it. Requests inherit it unless they choose their own, or None.

Type	Notes
Bearer, Basic, API key	In a header or the query string.
OAuth 2.0	Authorization code (with PKCE), client credentials, password and implicit. Tokens are kept in the keychain and refreshed.
JWT	Signs a token from claims you write.
Digest, OAuth 1.0, AWS Signature v4	Signed for every send.

Proxies, client certificates, extra CA certificates and the cookie jar are machine settings (Settings), shared with the CLI. The cookie manager lets you view, edit and delete cookies per domain.

Scripts

Pre-request and test scripts are JavaScript with Postman's pm API, so scripts you import from Postman keep working. They run in a sandbox: no files, and no network except pm.sendRequest, which follows the same host rules as the request.

// Pre-request: log in once and reuse the token if (!pm.environment.get("token")) { pm.sendRequest({ url: pm.variables.get("baseUrl") + "/login", method: "POST", body: { mode: "raw", raw: JSON.stringify({ user: "ann", pass: pm.variables.get("password") }) } }, (err, res) => pm.environment.set("token", res.json().token)); } // Test pm.test("creates the user", () => { pm.response.to.have.status(201); pm.expect(pm.response.json().name).to.eql("Wanjiru"); });

Collections and folders can have scripts too; they run before and after every request inside. The script editor's help lists the whole API, and its output appears in the console (Ctrl `).

Checks

Checks are tests without code, saved in the request's expect block. They are applied by the app, tuma test and tuma run.

Check	Example (CLI form)
Status	`status=201`, `status=2xx`
Time	`time<500`
Headers	`header content-type~json`, `header !x-debug`
Body	`$.id exists`, `$.name == "Ann"`, `$.email ~ @`, `$.items length 3`, `$.id type integer`
Contract	`schema`: the response must match the OpenAPI spec the collection came from

Collection runner

Run every request in a collection or folder, in order, with their checks and scripts. Feed it a CSV or JSON data file to run once per row, with each column as a variable. Results show what passed, what failed and why, and can be exported as JUnit XML for CI.

tuma run "Users API" --data users.csv --junit results.xml

Performance and security tests

Virtual users send a request, folder or collection over and over. Tuma reports throughput, error rate and p50 / p95 / p99 latency per request, and runs passive security checks on the responses: security headers, cookie flags, CORS, HTTPS and leaked details such as stack traces. Export the result as an HTML or JSON report.

tuma perf "Users API" -u 20 -d 60 --max-p95 300 --report perf.html

Flag	Meaning
`-u`	Virtual users at the same time (at most 200)
`-d`	Duration in seconds (0 runs a fixed number of iterations)
`--max-p95`, `--max-errors`	Exit with 1 when latency or the error percentage is too high, to fail CI
`--report`	Write the report, `.html` or `.json`

Only load-test servers you own or have permission to test.

Encrypted fields

For APIs that exchange encrypted values, the request's Crypto tab encrypts chosen body fields just before sending and decrypts chosen response fields when they arrive, so checks and scripts see plain values.

Algorithm	Use
AES-256/128-GCM, AES-256/128-CBC	A shared key (base64, hex or text) and a random or fixed IV.
RSA-OAEP SHA-1 or SHA-256	Encrypt with the server's public key (PEM; one line, as in a `.env` file, works too).
Hybrid RSA + AES	Responses holding an RSA-encrypted AES key and IV with the AES-encrypted data, decrypted with your private key.

Fields are JSON paths, one per line, such as $.pin or $.items[*].ssn; $ is the whole body. Keep keys in secret variables such as {{rsaPrivateKey}}.

Examples and mock servers

Save any response as an example of its request. A mock server then answers with those examples, so a frontend can be built before the backend exists.

tuma mock "Users API" --port 4010

Requests are matched by method and path ({{name}} and :name segments match anything). Pick an example with an x-mock-response-code or x-mock-response-name header; otherwise the first successful one is sent. Edits to examples apply at once.

API documentation

Generate docs for a request, folder, collection or the whole workspace as OpenAPI 3.1 (YAML or JSON), Markdown or a standalone HTML page. Descriptions and saved examples make them complete; secret values are never included.

tuma docs "Users API" -o openapi.yaml # the format comes from the extension tuma docs "Users API" -o api.html

Import and export

Import	Where
Postman collections and environments	Import button, or `tuma import`
Insomnia, Bruno, plain JSON environments	Import button; environments also from the Environments section
OpenAPI 3 / Swagger 2	File or URL; `tuma openapi discover --server http://localhost:8000 --import` finds a running API's spec
HAR recordings, cURL commands	Import button; paste cURL straight into the URL bar

Export a collection as Postman Collection v2.1 (which Postman, Insomnia and Bruno import), or a whole workspace as a .zip. Collections imported from a spec can be synced when the spec changes.

The tuma command

The CLI uses the same workspace files as the app. Run it from anywhere inside a project with a .tuma/ folder.

Command	Does
`tuma init`	Create a workspace in the current project
`tuma send`	Send a request and check the response; `--save` keeps it as a test when the checks pass
`tuma test`	Rerun every saved request that has checks; exit code 1 if one fails
`tuma run`	Run a collection or folder, optionally once per data row; JUnit output
`tuma perf`	Load-test with latency limits and an HTML report
`tuma mock`	Serve the saved examples
`tuma docs`	Generate OpenAPI, Markdown or HTML docs
`tuma import` / `tuma export`	Bring collections in, or export as Postman v2.1
`tuma openapi`	Import, discover or sync an OpenAPI spec
`tuma grpc`, `tuma ws`	Call gRPC methods; talk to a WebSocket
`tuma auth`	Log in for OAuth 2.0, list or forget tokens
`tuma check`	Validate the workspace files
`tuma mcp`	The MCP server for coding agents

tuma send POST /users -d '{"name":"Ann"}' --var baseUrl=http://localhost:3000 \ -x status=201 -x '$.id exists' --save "Users/create user" tuma test --env staging

In CI

Secrets come from TUMA_SECRET_<NAME> environment variables when there is no keychain:

# .github/workflows/api.yml - run: tuma test --env staging env: TUMA_SECRET_APIKEY: ${{ secrets.API_KEY }}

Coding agents (MCP)

Tuma's MCP server lets coding agents test the API they are building, and save what works as tests in your workspace.

claude mcp add tuma -- tuma mcp

For other agents, add a stdio server that runs tuma mcp. The tools agents get:

Tool	Does
`send_request`	Send a request, with checks
`list_requests`, `read_request`, `describe_request`	Explore the workspace
`save_request`, `save_example`, `set_scripts`, `set_variables`	Save tests, examples, scripts and variables
`run_saved`	Run saved tests
`run_performance_test`	A small load test (capped at 50 users and 60 seconds by default)
`import_openapi`, `sync_openapi`, `generate_docs`, `check_workspace`	Specs, docs and validation

What agents can't do

Reach hosts other than localhost and the selected environment's, unless you add --allow-host api.example.com.
See secret values: they are sent, never shown.
Change files, with --read-only.

Keyboard shortcuts

Keys	Action
`Ctrl` `K`	Find any request or command
`Ctrl` `Enter`	Send
`Ctrl` `S`	Save
`Ctrl` `T` / `Ctrl` `N`	New tab
`Ctrl` `W`	Close the tab
`Ctrl` `Tab`	Next tab (with `Shift`, previous)
`Ctrl` `B`	Show or hide the sidebar
`Ctrl` `F`	Find in the response
`Ctrl` `	Show or hide the console
`F2`	Rename the request

FAQ

Is Tuma really free?

Yes. It's open source under Apache-2.0, with no paid tier and no account. If it saves you time, consider donating.

Does Tuma send my data anywhere?

No. There's no telemetry and no cloud. It only connects to the APIs you send requests to.

Will updating delete my work?

No. Workspaces are folders on your disk, and settings are in your user profile; installers never touch them.

How do I move from Postman?

Export your collections and environments from Postman as JSON, then use Import. Scripts keep working.

Can I contribute?

Please do. Open an issue or a pull request on GitHub.

Something missing or wrong? These docs live in the repo, too.

Edit this page Donate