CodeVetter · Repo Unpack · Feature catalog
httpie/cli
The user-facing surface is one request-sending command with roughly fifty flags grouped into ten sections, plus a separate management binary with two command trees. Request construction supports JSON (default), form, multipart, raw body, nested-JSON keys, file embedding, and stdin piping. Output is controlled by a five-letter `--print` alphabet (H/B/h/b/m) with prettification, syntax highlighting, and streaming variants. Persistence features are named and anonymous sessions bound per host. Operational features include resumable downloads with Rich progress bars, offline request rendering, SSL/cipher/client-cert control, proxying, and a background update checker. Extensibility features are the four plugin categories plus a pip-backed plugin installer.
- Request-item syntax is the headline feature: `:` headers, `;` empty header, `:@` header-from-file, `==` query params, `==@` query-from-file, `=` data string, `:=` raw JSON, `@` file upload, `=@` embed file contents, `:=@` embed raw JSON file -- each mapped to a dedicated processor function in `RequestItems.from_args`.
- Nested-JSON keys (`foo[bar][0]=baz`) are a self-contained, dependency-free sub-language with its own tokenizer, recursive-descent `parse()` returning `Path` objects, and `interpret_nested_json()` builder; syntax errors surface as `NestedJSONSyntaxError` handled specially in `raw_main`.
- Content-type modes are mutually exclusive via a `RequestType` enum: `--json/-j`, `--form/-f`, `--multipart` (with `--boundary`), and `--raw` for a literal body; `_process_request_type` expands the enum into the `args.json`/`args.form`/`args.multipart` booleans the rest of the code reads.
- Output selection uses a compact alphabet -- `H` request headers, `B` request body, `h` response headers, `b` response body, `m` response metadata -- exposed via `--print`, with `--verbose` (=HBhb), `-vv` (all, incl. meta), `--headers`, `--body`, `--meta`, `--all`, and `--history-print` as shortcuts.
- `--meta`/`-vv` prints an `Elapsed time` line computed as `response.elapsed` plus `monotonic() - response._httpie_headers_parsed_at`, i.e. header time plus body-read time, and is highlighted by a dedicated `MetadataLexer`.
- Sessions come in two flavours: named sessions stored at `<config>/sessions/<host_port>/<name>.json`, and anonymous sessions triggered when the `--session` value contains a path separator, stored at the user-supplied path; `--session-read-only` loads without persisting back.
- Download mode (`--download/-d`) implies `--follow`, moves normal output to stderr, derives a filename from Content-Disposition or the URL path (with mimetypes extension guessing and uniquifying `-N` suffixes), and supports `--continue` via a `Range: bytes=N-` header validated against the Content-Range response.
- Download progress is rendered through Rich with three interchangeable displays -- `ProgressDisplay` when Content-Length is known, `StatusDisplay` (spinner) when it isn't, and `DummyDisplay` when `env.show_displays` is false (as in tests).
- `--offline` renders the request without sending it: `collect_messages` yields the prepared request and never enters the send branch, and the parser flips default output options to `OUTPUT_OPTIONS_DEFAULT_OFFLINE` (request head + body).
- Authentication ships three builtin plugins -- `basic` (unicode-safe latin1 header re-encoding), `digest`, and `bearer` (which sets `auth_parse = False` so the raw `-a` value becomes the token) -- and `--auth-type` choices are populated from the plugin registry.
- SSL control includes `--verify` (yes/no/CA-bundle path), `--ssl` mapped through `AVAILABLE_SSL_VERSION_ARG_MAPPING` (ssl2.3 through tls1.3, filtered by what the local `ssl` module exposes), `--ciphers`, and client certs via `--cert`/`--cert-key`/`--cert-key-pass`.
- `httpie plugins install/upgrade/uninstall/list` drives `pip install --prefer-binary --prefix=<plugins_dir> --no-warn-script-location` and implements uninstall by hand (unlinking `distribution.files`) because pip cannot uninstall from a custom prefix.
- `httpie cli export-args --format json` serializes the whole ParserSpec (groups, aliases, choices, types, nested options) to JSON through `to_data()` -- the machine-readable contract used to generate docs and completions.
- `--manual` prefers the system man page (`man 1 http`) when available and otherwise renders the Rich-formatted help through a pager; man-page availability can be disabled with the `HTTPIE_NO_MAN_PAGES` env var.
- Prettification is a plugin chain of four builtin `FormatterPlugin`s -- HeadersFormatter (stable sort), JSONFormatter (re-indent/sort via `load_prefixed_json`), XMLFormatter (defusedxml-backed pretty printing), and ColorFormatter (Pygments) -- toggled by `--pretty` and tuned by `--format-options`.