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 collection run [name] [flags]
Common flags:
| Flag | Short | Default | Description |
|---|---|---|---|
--env | -e | none | Environment to use |
--var | -v | none | Variable as key=value |
--data | -D | none | CSV or JSON data file |
--bail | -b | false | Stop on first failure |
--assert-bail | false | Stop on first assertion failure only | |
--persist | false | Persist extracted/script variables back to the selected environment | |
--dry-run | false | Preview collection execution without sending requests | |
--reporter | -R | none | Reporter to use: junit, json, html, or console |
--reporter-output | -O | none | Output directory for reporter files |
remove
Remove a collection label while keeping its requests.
gurl collection remove [name]
Aliases: rm
delete
Delete a collection and all requests in it. Interactive terminals ask for confirmation. Use --force for non-interactive scripts.
gurl collection delete [name]
gurl collection delete [name] --force
Aliases: del
export
Export a collection with passphrase-encrypted collection secrets.
gurl collection export [name] --passphrase "$TEAM_SECRET" --output collection.gurl
If --passphrase is omitted in an interactive terminal, gurl prompts for it without echoing the value.
import
Import a collection export or collection directory and re-encrypt secrets with the local collection key.
gurl collection import collection.gurl --passphrase "$TEAM_SECRET"
gurl collection import .gurl/collections/payments
If the export contains encrypted secrets and --passphrase is omitted in an interactive terminal, gurl prompts for it. For CI, set GURL_IMPORT_PASSPHRASE instead of passing --passphrase.
Import variables from a .env file into a collection.
gurl collection import payments --file .env.production
This creates the collection if it does not exist. Imported .env values are stored as plain collection variables, not secrets.
unlock
Unlock a passphrase-protected file-backed collection after cloning shared project files. The derived key is cached in the OS keychain, so later commands can use the collection without re-entering the passphrase.
gurl collection unlock [name] --passphrase "$TEAM_SECRET"
If --passphrase is omitted in an interactive terminal, gurl prompts for it without echoing the value.
migrate
Migrate a DB-backed collection into project file storage.
gurl collection migrate [name]
gurl collection migrate [name] --passphrase "$TEAM_SECRET"
With --passphrase, collection secrets are written to collection.json with passphrase-derived encryption and no local collection.key is left behind. Teammates can clone the project files and run gurl collection unlock [name] --passphrase "$TEAM_SECRET" to cache the derived key in the OS keychain.
rename
Rename a collection.
gurl collection rename [old-name] [new-name]
Aliases: mv, ren
Examples
List collections
gurl collection list
Shows all collections and request counts.
Create a collection
gurl collection add "api-v2"
Creates a new collection called “api-v2”.
Rename a collection
gurl collection rename "api" "api-v3"
Renames “api” to “api-v3”.
Show a collection
gurl collection show "api-v2"
Shows each request in the collection with method and URL.
Run a collection dry run
gurl collection run "checkout-flow" --env staging --dry-run
Prints request order, planned variable sources, extraction rules, and unresolved placeholders without sending HTTP requests.
Persist extracted flow variables
gurl collection run "checkout-flow" --env staging --persist
Writes only extracted variables and script-set variables back to the selected environment. --persist and --dry-run cannot be used together.
Stop on assertion failures only
gurl collection run "checkout-flow" --assert-bail
Stops after the first assertion failure. Other request failures are reported, but they do not trigger assertion bail mode.
Delete a collection
gurl collection delete "old-api" --force
Deletes the “old-api” collection and all requests in it.
Share a collection with secrets
gurl collection export "checkout-flow" --passphrase "$TEAM_SECRET" --output checkout-flow.gurl
gurl collection import checkout-flow.gurl --passphrase "$TEAM_SECRET"
gurl collection import .gurl/collections/checkout-flow
The export encrypts collection secrets with the passphrase. Import decrypts those values and stores them with the local .gurl/collections/<collection>/collection.key. Directory import reads collection.json and request JSON files directly; local-key encrypted directories require their collection.key. For passphrase-protected project files, unlock verifies the passphrase and caches the derived key in the OS keychain.