curlz

a curl wrapper with placeholder, bookmark and environment powers just like postman but for the terminal

Features

• variables from .env and .yaml environment files
• ️placeholder evaluation using the minijinja template engine, which can be used in URLs, HTTP headers, the HTTP body, and other passed curl parameters
• ability to save and execute requests as bookmarks with a shortname
• support any curl argument after a --, that makes a drop-in-replacement for curl
• special placeholders to interact with the user
  • prompt for a password as {{ prompt_password() }} curlz r https://api.github.com/user -- -u "{{ username }}:{{ prompt_password() }}"
  • prompt for interactive input with a label as {{ prompt_for("Username") }} or {{ prompt_for("Birthdate") }} curlz -- -u "{{ prompt_for("Username") }}:{{ prompt_password() }}" https://api.github.com/user
• ️evaluate placeholders at the beginning of an url like: curlz r --define 'host=https://httpbin.org' '{{host}}/get'
• ️special placeholder for developers, like for Json Web Tokens (JWT) {{ jwt(claims, jwt_signing_key) }}, where claims and jwt_signing_key are looked up at the environment file or can be directly provided map and string curlz r -H 'Authorization: Bearer {{ jwt({"uid": "1234"}, "000") }}' https://httpbin.org/bearer -- -vvv
• send a http body via -d | --data curlz r -d 'Hello World' -X POST https://httpbin.org/anything
• send a json payload and headers with the --json argument curlz r --json '{ "foo": "bar" }' -X POST 'https://httpbin.org/anything'

WIP

• support rest client template language see #5

Example #1

In this example we're going to download a pre-configured .gitignore for a given language from GitHub via curl

• curl https://api.github.com/gitignore/templates/Rust
• the same with curlz: curlz r https://api.github.com/gitignore/templates/Rust
• Add a placeholder that is interactively requested curlz r 'https://api.github.com/gitignore/templates/{{ prompt_for("Language") | title }}'
• Now let's bookmark this request:

  curlz r --bookmark 'https://api.github.com/gitignore/templates/{{ prompt_for("Language") | title }}'
  Language: rust
  Please enter a bookmark name: gitignore
  

• Finally, we can keep using the bookmark from now on: curlz r gitignore

Template function documentation

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 can be provided at the environment file with a variable named jwt_signing_key
• 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 time is set to in 15min by default, but can be overwritten
  • the claim iat issued at timestamp is set automatically and cannot be overwritten