#curl #bookmark #environment #header #http #yaml #jwt

bin+lib curlz

curl wrapper with placeholder, bookmark and environment powers just like postman

12 releases

0.1.0-alpha.12 Mar 24, 2023
0.1.0-alpha.11 Mar 16, 2023
0.1.0-alpha.5 Feb 28, 2023
0.1.0-alpha.4 Jan 17, 2023
0.1.0-alpha.2 Aug 16, 2022

#12 in #bookmark

GPL-3.0-only

90KB
2.5K SLoC

curlz

License: GPL v3 Build Status crates.io dependency status

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

Dependencies

~15–27MB
~490K SLoC