Guides

Environments Environments let you manage variables and secrets for different deployment stages. Each environment contains a set of key-value pairs that are substituted into requests at runtime. Creating Environments Create an environment with gurl env create: gurl env create dev --var "BASE_URL=https://dev.api.com" --var "TIMEOUT=30" gurl env create staging --var "BASE_URL=https://staging.api.com" --var "TIMEOUT=60" gurl env create prod --var "BASE_URL=https://api.example.com" --var "TIMEOUT=120" For secrets, use --secret to encrypt the value: gurl env create prod --secret "API_KEY=sk-live-xxxxx" --secret "WEBHOOK_SECRET=whsec_xxxxx" Switching Environments Set the active environment with gurl env switch: ...

Scripting Gurl supports JavaScript pre-request and post-response scripts powered by the goja runtime (ECMAScript 5.1+). Scripts let you implement dynamic behavior that would be difficult or impossible with static configuration. Script Types Pre-Request Scripts Execute before the request is sent. Use to: Modify headers dynamically Generate authentication tokens Set request body based on conditions Skip the request entirely Post-Response Scripts Execute after the response is received. Use to: Extract data from responses Validate response content Set variables for subsequent requests Chain requests together Script API Request Object The request object provides access to the outgoing request: ...

Assertions Assertions let you validate API responses without writing scripts. Gurl evaluates assertions after receiving a response and before displaying output. Failed assertions cause a non-zero exit code. Syntax Each assertion follows the format field operator value: gurl run "api" --assert "status=200" --assert "body.path(\"$.name\") contains John" Supported Operators Operator Description = Equal (exact match) != Not equal < Less than (numeric comparison) > Greater than (numeric comparison) <= Less than or equal >= Greater than or equal contains Substring match not_contains No substring match matches Regex match exists Field exists (no value needed) Assertable Fields Field Description Examples status HTTP status code status=200, status>=200 header.NAME Response header header.Content-Type contains json body Response body as text body contains "success" body.path(X) JSONPath expression body.path($.data.id) exists JSONPath Examples // Assert a nested value equals expected body.path($.data.users[0].name) = "Alice" // Assert array length body.path($.data.users.length()) > 0 // Assert object exists body.path($.data) exists CLI Usage Pass assertions with --assert: ...

Collection Runner The collection runner executes multiple requests in sequence, supporting data-driven testing and various output formats for CI integration. Running a Collection Run all requests in a collection: gurl collection run "my-api" Run a specific request from a collection: gurl collection run "my-api" --request "get-users" Sequencing Requests By default, requests run in the order they were saved. Control execution order explicitly: gurl sequence set "login" 1 gurl sequence set "get-users" 2 gurl sequence set "update-user" 3 gurl sequence set "logout" 4 View the current sequence: ...