Introduction

Features

Placeholders everywhere

️placeholders at the beginning of an url e.g.

curlz r --define 'host=https://httpbin.org' '{{host}}/get'

placeholders in HTTP Headers, e.g.

curlz r -H 'Username: {{ env.USER }}' https://httpbin.org/headers

JSON Payload | --json

This is a shortcut for setting 2 HTTP Headers and sending data as with -d | --data

Example

curlz r --json '{ "foo": "bar" }' -X POST 'https://httpbin.org/anything'

Template function documentation

Prompt User Input - prompt_for(name: string)

  • arguments:

    • name: a name that is printed before the user would input data
  • output: string

  • notes:

    • don't use this for passwords, consider prompt_password() for this
  • examples:

    • let the user enter an arbitrary username
    curlz r https://api.github.com/user -- \
      -u '{{ prompt_for("GitHub Username") }}:{{ prompt_password() }}'
    

Prompt User for Password - prompt_password()

  • arguments: None
  • output: string

Example: Username

let the user enter an arbitrary username:

curlz r -u '{{ prompt_for("GitHub Username") }}:{{ prompt_password() }}' https://api.github.com/user

Json Web Token - jwt(claims: map, [jwt_signing_key: string])

  • arguments:
    • claims: to be a map of key value pairs like {"uid": "1234"} that are the payload of the JWT
    • jwt_signing_key: to be a string, this is optional and when omitted a variable named jwt_signing_key will be taken from the .env file, if that variable is missing an error is raised
    • Note: also key value arguments are possible: jwt(uid="1234", jwt_signing_key="999")
  • output: string is a Json Web Token (JWT)
  • notes:
    • the hash algorithm is HS256 and the JWT header is {"alg": "HS256", "typ": "JWT"}
    • the claim exp expiry timestamp (UNIX-Timestamp) is set to expire in 15min by default
      • can be overwritten by a UNIX-Timestamp or a duration string like "15min" or "1h"
    • the claim iat issued at timestamp is set automatically, can't be overwritten
    • you can find a full list of commonly used claims at iana.org

Example: Simple Claims

This example illustrates how a JWT Signing Key will be used from a .env file implicitly. Given an .env file like this:

# .env
jwt_signing_key=123Secret123

The usage of jwt would look like this:

curlz r -H 'Authorization: Bearer {{ jwt({"email": "john@dow.com", "sub": "some subject"}) }}' https://httpbin.org/headers

Alternatively, you can provide the claims as named arguments like:

curlz r -H 'Authorization: Bearer {{ jwt(email="john@dow.com", sub="some subject") }}' https://httpbin.org/headers

{
  "headers": {
    "Accept": "*/*",
    "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2Nzk1MjQ2ODAsInN1YiI6InNvbWUgc3ViamVjdCIsImVtYWlsIjoiam9obkBkb3cuY29tIiwiaWF0IjoxNjc5NTIzNzgwfQ.bt6taB1YGyMc_43mZeq77dgS_teyglUWtr1dsObyXTg",
    "Host": "httpbin.org",
    "User-Agent": "curl/7.86.0",
    "X-Amzn-Trace-Id": "Root=1-641b7fd7-65e24681239a404d6a143187"
  }
}

Basic Auth Token - basic(username: string, password: string)

  • arguments:
    • username: the username as string
    • password: the password as string
  • output: string is a base64 encoded credential username:password

Example

send a basic auth header with username joe and password secret:

curlz r -H 'Authorization: Basic {{ basic("joe", "secret") }}' https://httpbin.org/headers

{
  "headers": {
    "Accept": "*/*",
    "Authorization": "Basic am9lOnNlY3JldA==",
    "Host": "httpbin.org",
    "User-Agent": "curl/7.86.0",
    "X-Amzn-Trace-Id": "Root=1-641b7fc0-1228f6242d06665a515e5cf9"
  }
}