gurl is a CLI API workbench. Save, organize, and execute HTTP requests from the terminal — with built-in auth handling, scripting, collection runner, and code generation.
Status: early (v0.4.x). The CLI works. The TUI exists in code but is not functional yet.
CLI API workbench.#
Save any request, run it by name, manage auth and environments, and generate client code — all from the terminal. Works well for humans and AI agents alike.
Features#
21 CLI Commands#
Every command you need for API workflows: save, run, list, edit, delete, duplicate, export, import, and more.
8 Auth Handlers#
Programmatic credential injection for every auth scheme:
| Auth Type | Use Case |
|---|
| Basic | Username/password |
| Bearer | Token-based |
| Digest | Challenge-response |
| API Key | Header or query |
| OAuth 1.0 | Signature-based |
| OAuth 2.0 | Token flow |
| AWS SigV4 | AWS API Gateway |
| NTLM | Windows integrated |
5 Protocol Clients#
Support for modern API protocols:
- HTTP - Full request/response with multipart support
- GraphQL - Query, mutation, subscription
- gRPC - Proto-based RPC with reflection
- WebSocket - Real-time bidirectional
- SSE - Server-sent events
Scripting Engine#
Extend requests with JavaScript using the goja runtime. Modify headers, transform responses, or chain dependent requests with full access to the request and response objects.
Collection Runner#
Run collections with data-driven testing. Feed CSV or JSON test data, assert on response status, body, and headers.
Plugin System#
Extend gurl with middleware for request/response transformation, custom output formatters, and additional CLI commands. Plugins hook into the request lifecycle.
Interactive TUI (not functional yet)#
A TUI built with bubbletea exists in the codebase but is not functional. The gurl tui command is present but the interface is not usable. This is planned for a future release.
Multi-language Code Generation#
Generate idiomatic client code from saved requests:
gurl codegen "my-request" --lang python
gurl codegen "my-request" --lang javascript
gurl codegen "my-request" --lang go
gurl codegen "my-request" --lang curl
Quick Start#
brew tap bsreeram08/gurl https://github.com/bsreeram08/gurl
brew install gurl
gurl save "my-api" https://api.example.com/users -H "Authorization: Bearer $TOKEN"
gurl run "my-api"
Save any request, run it instantly, generate code, and share with your team.
Built for AI Agents#
They never touch your credentials.
Gurl is designed for AI agent workflows where security matters. Credentials never appear in logs, never leak into prompts, and never get exposed to model providers.
Security model:
- Environment secrets encrypted at rest with AES-256-GCM
- Auth handlers inject credentials programmatically
- Header redaction in all log output
- No credentials in generated code without explicit flags
See the AI integration page for how Gurl works with AI agents.
Why Gurl#
- Local-first — no account, no cloud sync, no lock-in
- Git-friendly — collections are just data, export and version them
- Scriptable — JavaScript pre/post-request hooks, chain requests, CI-ready exit codes
- Open source — inspect and extend everything
CLI API workbench. Save, run, and manage HTTP requests from the terminal.
8 auth handlers, 5 protocol clients, JavaScript scripting, collection runner, code generation, and a plugin system.
Status: early (v0.4.x). The CLI works. The TUI exists in code but is not functional yet.
gurl auth Discover the auth handlers built into gurl and see the parameters each handler accepts.
Usage gurl auth list gurl auth info <type> Description Use gurl auth when you need the exact value for --auth or the supported --auth-param key=value pairs for a handler. --auth-param can be repeated on gurl save and gurl edit.
gurl run uses the auth config already saved on the request. Auth parameters are template-substituted during execution, after the request URL, headers, and body are prepared and before the auth handler updates the outgoing request.
...
gurl codegen Generate code in various programming languages from a saved request.
Usage gurl codegen [name] [flags] Description The codegen command converts a saved request into code for various languages. This helps you integrate API calls into your codebase without manual translation.
Flags Flag Short Default Description --lang -l none Target language: go, python, javascript, or curl --clipboard -c false Copy output to clipboard instead of printing Aliases cg Examples Generate Go code gurl codegen "my-request" --lang go Generates Go code for the request.
...
gurl collection Manage collections for organizing saved requests.
Usage gurl collection [subcommand] [flags] Description Collections group related requests together. Use collections to organize requests by project, API, or any other logical grouping.
Subcommands list List all collections.
gurl collection list Aliases: ls, l
add Create a new collection.
gurl collection add [name] Aliases: create, new
show Show requests in a collection.
gurl collection show [name] Aliases: view, info
run Run every request in a collection.
...
gurl delete Remove a saved request from gurl’s storage.
Usage gurl delete [name] Description The delete command permanently removes a saved request. This action cannot be undone.
Flags None.
Aliases rm del d Examples Delete a request gurl delete "old-request" Removes the request named “old-request”.
See also gurl save - Save a new request gurl list - List saved requests gurl rename - Rename a request
gurl detect Parse curl command syntax from stdin or a file and convert it to a saved request.
Usage gurl detect [flags] Description The detect command reads a curl command from stdin or a file and parses it into a saved request. This is useful when you have curl commands from other sources and want to save them in gurl.
Flags Flag Short Default Description --file -f none Path to file containing curl command --name -n none Name for the saved request --collection -c none Collection to assign the request to Aliases parse d Examples Parse from stdin curl -s https://api.example.com/users | gurl detect Parses curl output from stdin and prompts for a name.
...
gurl diff Compare responses from different executions of the same request.
Usage gurl diff [name] [flags] Description The diff command shows the differences between multiple executions of a request. This helps identify changes in API responses over time or across different environments.
Flags Flag Short Default Description --limit -n 2 Number of executions to compare --limit -l 2 Number of executions to compare Aliases d Examples Compare last two executions gurl diff "users" Compares the two most recent executions of the “users” request.
...
gurl edit Edit a saved request using your default editor or command-line flags.
Usage gurl edit [name] [flags] Description The edit command modifies a saved request. Without flags, it opens the request in your default editor. With flags, it updates specific fields directly.
Flags Flag Short Default Description --method -X none HTTP method --url -u none Request URL --header -H none Add HTTP header --remove-header none Remove a header by name --body -d none Request body --collection -c none Move to collection --tag -t none Add a tag --pre-script none Script to run before request --post-script none Script to run after request --run-if none Conditional expression for running this request --extract none Add or replace extraction rule as VAR_NAME=METHOD:EXPRESSION --remove-extract none Remove extraction rule by variable name --assert -a none Add an assertion --auth none Authentication type: basic, bearer, apikey, oauth1, oauth2, awsv4, digest, ntlm, or none --auth-param none Authentication parameter as key=value (can be specified multiple times) Aliases e Examples Edit in default editor gurl edit "my-request" Opens “my-request” in your default editor.
...
gurl env Manage environment variables for use in requests.
Usage gurl env [subcommand] [flags] Description The env command group manages environments and variables. Environments allow you to define different variable sets for development, staging, production, etc.
Subcommands create Create a new environment.
gurl env create [name] [flags] Flag Short Default Description --var -v none Variable as KEY=VALUE --secret -s none Secret variable (value prompted) list List all environments.
gurl env list Aliases: ls, l
...
gurl export Export saved requests to a file in various formats.
Usage gurl export [flags] Description The export command writes one or more requests to a file. You can export individual requests, entire collections, or all requests.
Flags Flag Short Default Description --name -n none Export a specific request by name --collection -c none Export an entire collection --all -a false Export all requests --output -o stdout Output file path --passphrase none Encrypt collection secrets when exporting a collection Aliases exp Examples Export a single request gurl export --name "my-request" --output my-request.gurl Exports the “my-request” to a file.
...
gurl graphql Execute a GraphQL query against an endpoint.
Usage gurl graphql [flags] Description The graphql command sends GraphQL queries to an endpoint. You can provide the query inline, from a file, with variables, and control output formatting.
Flags Flag Short Default Description --query -q none GraphQL query string --query-file -f none Path to file containing GraphQL query --vars -v none Variables as JSON --operation-name none GraphQL operation name --format auto Output format: auto, json, or table --color -c true Enable colored output Aliases gql Examples Simple query gurl graphql --query "{ users { id name } }" https://api.example.com/graphql Sends a simple GraphQL query.
...