Jakub Roztocil for HTTPie

Posted on Mar 15, 2022 • Edited on Jun 3, 2022 • Originally published at httpie.io

What’s new in HTTPie for Terminal 3.1

We released HTTPie for Terminal 3.0 about a month ago. Today we’re announcing 3.1.0 that comes with a bunch of enhancements and a security-related fix.

Summary

🍪 Improved cookie management — improved security with host-bound cookies, and more.

⚙️ Session management — automatic upgrades of sessions files.

🧩 CLI parser schema export — a new httpie cli export-args command with machine-readable arguments description.

🌲 Nested JSON enhancements — formalization of the top-level array syntax, and a fix for escaping of multiple backslahses.

✨ Simplified usage — HTTPie now has an intelligent compact help.

🪲 Bug fixes — extinguished and regression-test-covered.

♥️ Community contributions — lots of amazing people who have contributed to this release.

🍪 Improved cookie management

Before 3.1.0, HTTPie didn‘t bind cookies to the host that set them. This behavior resulted in the exposure of some cookies when there are redirects originating from the actual host to a third party website, e.g:

$ http --follow --session=jar \
  pie.dev/redirect-to url==https://httpbin.org/cookies

Prior to 3.1:

{
    "cookies": {
        "x": "y"
    }
}

Starting with 3.1:

{
    "cookies": {}
}

This behavior has been corrected in this release (with taking
RFC 6265 — HTTP State Management Mechanism
into the consideration).

Security advisory

The old host-unbound handling of cookies in sessions represents a low-severity security vulnerability. We’d like to thank @glyph for responsibly disclosing the issue. It has been assigned the CVE ID CVE-2022-24737 (and CVE-2022-0430, which is a duplicate), and you can read more about it in the advisory published on GitHub.

📖 Host-based cookie policy docs →

⚙️ Automated session upgrades

The change in HTTPie’s handling of cookies triggered the need to also change the sessions file format. When you use a session file in the old format, HTTPie will ask you to upgrade it first. There are two new commands to help you upgrade your sessions:

`httpie cli sessions upgrade`

With this command, you can upgrade a single session file.

Upgrade an anonymous session:

$ httpie cli sessions upgrade pie.dev ./jar.json
Upgraded 'jar' @ 'pie.dev' to v3.1.0

Upgrade a named session:

$ httpie cli sessions upgrade --bind-cookies pie.dev api-auth
Upgraded 'api-auth' @ 'pie.dev' to v3.1.0

`httpie cli sessions upgrade-all`

This command allows you to upgrade all your named sessions in one go:

$ httpie cli sessions upgrade-all
Upgraded 'jar' @ 'pie.dev' to v3.1.0.
Upgraded 'api-auth' @ 'pie.dev' to v3.1.0.
Upgraded 'api-auth' @ 'api.myhost.com' to v3.1.0.

📖 Session upgrade docs →

🧩 Exporting CLI’s parser schema

We’ve added a new command called httpie cli export-args. The idea is to improve interoperability by exposing our CLI definition to third-party tools in a machine-readable format (not unlike an API description). This makes it easier for developers to generate auto-completion for different shells and utilities, power playgrounds, cheatsheets, etc.

HTTPie users will also benefit from the internal CLI-definition-as-data refactorings directly as they allow us to implement a more user-friendly and contextual help output, finally generate a proper man page, and more (coming very soon)!

For a very simple example, we can use export-args to list the first ten options:

$ httpie cli export-args --format=json | jq '.spec.groups[].args[].options[0]' | head

"METHOD"
"URL"
"REQUEST_ITEM"
"--json"
"--form"
"--multipart"
"--boundary"
"--raw"
"--compress"
"--pretty"

📖 httpie cli export-args docs →

🌲 Nested JSON enhancements

Top-Level arrays

If you want to use an array (instead of an object) as the top-level encapsulator on your generated JSON data, we have now formalized a syntax for it:

$ http --offline --print=B pie.dev/post \
    []:='httpie.io' \
    []:='pie.dev' \
    []:='pie.co'

[
    "httpie.io",
    "pie.dev",
    "pie.co"
]

📖 Top-level array docs →

Escaping of multiple backslashes

This release has also fixed a bug related to escaping of multiple backslashes inside a single key group.

$ http pie.dev/post 'data[\\key]=value'

{
    "json": {
        "data": {
            "\\key": "value"
        }
    }
}

📖 Nested JSON escaping docs →

✨ Simplified usage

HTTPie for Terminal grew a lot in the past decade, so did the usage section in the help messages:

$ http
usage: http
    [--json] [--form] [--multipart] [--boundary BOUNDARY]
    [--raw RAW] [--compress]
    [--pretty {all,colors,format,none}] [--style STYLE]
    [--unsorted] [--sorted] [--response-charset ENCODING]
    [--response-mime MIME_TYPE]
    [--format-options FORMAT_OPTIONS] [--print WHAT]
    [--headers] [--meta] [--body] [--verbose] [--all]
    [--history-print WHAT] [--stream] [--output FILE]
    [--download] [--continue] [--quiet]
    [--session SESSION_NAME_OR_PATH |
    --session-read-only SESSION_NAME_OR_PATH]
    [--auth USER[:PASS] | TOKEN]
    [--auth-type {basic,bearer,digest,edgegrid}]
    [--ignore-netrc] [--offline]
    [--proxy PROTOCOL:PROXY_URL]
    [--follow] [--max-redirects MAX_REDIRECTS]
    [--max-headers MAX_HEADERS] [--timeout SECONDS]
    [--check-status] [--path-as-is] [--chunked]
    [--verify VERIFY] [--ssl {ssl2.3,tls1,tls1.1,tls1.2}]
    [--ciphers CIPHERS] [--cert CERT] [--cert-key CERT_KEY]
    [--ignore-stdin] [--help] [--version] [--traceback]
    [--default-scheme DEFAULT_SCHEME] [--debug]
    [METHOD] URL [REQUEST_ITEM ...]
http: error: the following arguments are required: URL

We redesigned this output to be more simple, so it reveals what you really care about:

$ http
usage:
    http [METHOD] URL [REQUEST_ITEM ...]

error:
    the following arguments are required: URL

For more information try 'http --help'

It can also contextually highlight the usage of specific options. In the example below, it adds --pretty {all, colors, ...} to the output becuase it’s used incorrectly:

$ http --pretty

usage:
    http [--pretty {all,colors,format,none}] [METHOD] URL [REQUEST_ITEM ...]

error:
    argument --pretty: expected one argument

For more information try 'http --help'

🪲 Bug fixes

Responses without a reason phrase in the Status-Line, e.g. HTTP/1.1 200 as opposed to HTTP/1.1 200 OK, failed to render correctly with the Pie themes. This is now fixed.
Fixed redundant issuance of stdin detection warnings on some rare cases.
-qq or --quiet --quiet now correctly suppresses warnings.

🐙 Full changelog →