aurl

To ensure successful requests with aurl, follow these usage patterns:

• Discovery Workflow: When using an unfamiliar API, first run aurl [name] --help to scan endpoints, then use aurl [name] describe METHOD /path to read full documentation before attempting a call.
• Query Parameters: Include query parameters directly in the path: aurl [name] GET '/path?key=value'.
• Shell Safety: Always quote paths that contain a ? character to prevent your shell from attempting globbing.
• Validation: aurl validates enum parameters before sending. If you miss required body fields, the CLI will trigger a warning.
• Error Handling: If a request results in a 4xx error, aurl will suggest the expected request body based on the API specification.

You can register OpenAPI or GraphQL APIs to turn them into CLI commands. For OpenAPI, provide a URL or a local path to the openapi.json file. You can also specify a custom base URL or manual authentication headers during registration.

To register a GraphQL API, use the --graphql flag.

aurl add [name] [openapi.json URL or path]       # register an API
aurl add [name] [spec] --base-url [URL]           # override base URL
aurl add [name] [spec] --header "Key: Value"      # manual auth header
aurl add --graphql [name] [endpoint]              # register a GraphQL API

Execute queries and mutations against registered GraphQL APIs.

Query

aurl <api_name> '<query_string>'

Query with variables

Pass the variables as a JSON string following the query:

aurl <api_name> '<query_with_variables>' '<json_variables>'

Mutation

aurl <api_name> 'mutation { ... }'

aurl linear '{ viewer { name email } }'

To enable AI coding agents (like Claude Code, Cursor, Codex, or Copilot) to use aurl for API interactions, install the skill using npx:

npx skills add ShawnPana/aurl

This allows agents to discover endpoints via --help, understand parameters via describe, and make validated requests.

Use the aurl add command to register an API. aurl will parse the specification (OpenAPI 3.0, 3.1, or Swagger 2.0) to auto-detect authentication, validate requests, and generate documentation.

REST API Registration

Register from a URL:

aurl add <name> <url>

Register from a local file:

aurl add <name> <path_to_file>

Register with a base URL override:

aurl add <name> <path_to_file> --base-url <url>

Register with custom auth headers:

aurl add <name> <url> --header "<Header-String>"

GraphQL API Registration

Use the --graphql flag:

aurl add --graphql <name> <url>

aurl add petstore https://petstore3.swagger.io/api/v3/openapi.json

Once an API is registered, you can explore its capabilities without reading raw documentation.

List all endpoints

Use the --help flag on the API name to see all endpoints grouped by tag, including methods, paths, and required parameters.

aurl <api_name> --help

Get detailed endpoint documentation

Use the describe command to see specific details for a single endpoint, including parameter types and response schemas.

aurl <api_name> describe <METHOD> <path>

Open external documentation

Open the API's official documentation in your browser:

aurl <api_name> docs

aurl petstore describe GET /pet/{petId}

Execute validated requests against registered REST APIs using the following syntax:

aurl <api_name> <METHOD> <path> [body_or_query]

Examples

GET request:

aurl petstore GET /pet/1

GET with query parameters:

aurl petstore GET '/pet/findByStatus?status=available'

POST with JSON body:

aurl petstore POST /pet '{"name":"doggie","photoUrls":["http://example.com"]}'

PUT request:

aurl petstore PUT /pet '{"id":1,"name":"updated","photoUrls":["http://example.com"]}'

DELETE request:

aurl petstore DELETE /pet/1

You can install aurl using Homebrew, Go, or by building from source.

Homebrew:

brew install shawnpana/tap/aurl

Go:

go install github.com/shawnpana/aurl@latest

From source:

git clone https://github.com/ShawnPana/aurl.git
cd aurl
make install

The aurl CLI allows you to turn OpenAPI specifications or GraphQL endpoints into named subcommands. Once an API is registered, you can invoke its operations directly from your terminal as if they were native CLI commands.

Core management commands include:

• add: Register a new API specification.
• list: View all currently registered APIs.
• remove: Delete a registered API.
• auth: Manage authentication credentials for registered APIs.

# Example of the general usage pattern
aurl add ...
aurl list
aurl <api-name> <command> [args]

aurl automatically detects securitySchemes from OpenAPI specs and prompts for credentials during registration. It supports:

• apiKey: Detects header/query param name and prompts for value.
• http + bearer: Prompts for token and sets Authorization: Bearer <token>.
• http + basic: Prompts for username/password and encodes as Basic auth.
• oauth2 / openIdConnect: Prompts for a token manually.

For GraphQL or APIs without defined security schemes, use the --header flag during registration or via the auth command:

aurl add myapi https://api.example.com/openapi.json --header "X-Api-Key: secret"
aurl auth myapi --header "Authorization: Bearer new-token"

Auth credentials are stored securely in ~/.config/aurl/auth/ with 0600 permissions.