Compact help

[ThiefMaster]

It would be nice if httpie had a compact help.

I tend to forget the various request item delimiters, but http --help spams the terminal scrollback with lots of unrelated information (I know, I can use less, but meh, I'm lazy). Why not include this in the compact "usage" printed when just running http?

[rozuur]

wouldn't it be better to have a tldr page for http instead of usage?

[ThiefMaster]

You can't install this kind of documentation using pip like you can with httpie... just like you can't install a manpage with pip

[rozuur]

I am not referring to installing a tldr page with pip, just providing another alternative for your problem. Will also help others who are using tldr pages.

[jkbrzt]

@rozuur there's now a tl;dr page: http://www.ostera.io/tldr.jsx/#/http

Better help system is planned.

[giuscri]

What about writing a man page with the current content of http --help, and making http --help just print

usage: http [--json] [--form] [--pretty {all,colors,format,none}]
            [--style STYLE] [--print WHAT] [--verbose] [--headers] [--body]
...

?

[ducaale]

Most rust-based CLI tools, including ripgrep, show a compact or a detailed help page depending on whether -h or --help flag has been used.

Httpie currently uses -h as a short form for --headers, but is there a chance to change that before the 3.0 release as a breaking change?

[ThiefMaster]

changing switches in a cli is a terrible idea, even in a major release. you just don't do something like that.

[ThiefMaster]

maybe it could do things like git and display a man page instead of dumping so much to stdout directly?

[ducaale]

changing switches in a cli is a terrible idea, even in a major release. you just don't do something like that.

To maintain backward compatibility, what if -h stood for --headers only when the URL is available? Of course, the docs wouldn't mention this behavior to steer away users from using -h as --headers.

$ http -h
usage: http [--json] [--form] [--pretty {all,colors,format,none}]
            [--style STYLE] [--print WHAT] [--verbose] [--headers] [--body]
...

$ http httpbin.org/json -h
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 429
Content-Type: application/json
Date: Thu, 23 Dec 2021 10:45:19 GMT
Server: gunicorn/19.9.0

[ducaale]

The current output of http -h is

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] [--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]] [--auth-type {basic,digest}]
            [--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 [REQUEST_ITEM ...]]
http: error: the following arguments are required: URL

If you remove the last line and change the exit code to 0, you would end up with a behaviour similar to ripgrep

$ http -h
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] [--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]] [--auth-type {basic,digest}]
            [--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 [REQUEST_ITEM ...]]

$ http --help
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] [--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]] [--auth-type {basic,digest}]
            [--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 [REQUEST_ITEM ...]]

HTTPie: command-line HTTP client for the API era. <https://httpie.io>

Positional Arguments:

  These arguments come after any flags and in the order they are listed here.
  Only URL is required.
...

[ducaale]

What if the --help flag displayed a compact help while a help subcommand is was used for more complete documentation?

$ http --help
HTTPie v0.3.0

HTTPie: modern, user-friendly command-line HTTP client for the API era. <https://httpie.io>

USAGE:
    http [OPTIONS] [METHOD] URL [REQUEST_ITEM ...]

OPTIONS:
    -j, --json       (default) Serialize data items from the command line as a JSON object
    -f, --form       Serialize data items from the command line as form fields
    -m, --multipart  Like --form, but force a multipart/form-data request even without files

Run `http help` or visit https://httpie.io/docs/cli for more complete documentation.

$ http help
HTTPie v0.3.0

HTTPie: modern, user-friendly command-line HTTP client for the API era. <https://httpie.io>

USAGE:
    http [OPTIONS] [METHOD] URL [REQUEST_ITEM ...]

OPTIONS:
  --json, -j
      (default) Data items from the command line are serialized as a JSON object.
      The Content-Type and Accept headers are set to application/json
      (if not specified).

  --form, -f
      Data items from the command line are serialized as form fields.

      The Content-Type is set to application/x-www-form-urlencoded (if not
      specified). The presence of any file fields results in a
      multipart/form-data request.

  --multipart
      Similar to --form, but always sends a multipart/form-data
      request (i.e., even without files).

[isidentical]

@ducaale that is the plan. Here is a sneek peek of the planned --help (and we'll add a --manual for the full help):

[ducaale]

Besides the --manual flag, are there any plans to support http help, or is that not possible because of the current argparse setup?

[isidentical]

We could support it, but honestly I find a bit confusing (currently http help means http ://help). Perhaps we might add a httpie cli help someday (cc: @jakubroztocil).