HTTPie Admin & Developer Guide

This guide is the deep reference for administrators, platform engineers, and developers working with or extending HTTPie — the command-line HTTP client (http, https, and the httpie management interface). It covers the codebase architecture, the request/response pipeline, the plugin API, configuration internals, a security analysis, and contribution guidance.

It is the companion to the HTTPie User Guide (which covers day-to-day command usage). Everything here is derived from the HTTPie source tree at version 3.2.4 (commit 5b604c3). HTTPie is licensed BSD-3-Clause and is implemented in Python, requiring Python 3.7 or newer.

Table of contents

• Executive summary
• Architecture overview
• The request/response pipeline
• Repository structure
• Module reference
• Component inventory
• The plugin API
• Configuration and state on disk
• Sessions: format and lifecycle
• The update-check subsystem
• Security analysis
• Requirements and dependencies
• Code quality and conventions
• Testing strategy
• Building and packaging
• Potential improvements
• Contributing
• Quick reference

Executive summary

HTTPie is a single-purpose, user-facing CLI: it turns a concise command line into an HTTP request, sends it via the Requests library, and renders a colorized, formatted response with Pygments. Its defining design choice is that the command-line syntax mirrors the HTTP message — the order and shape of arguments map directly onto the request that goes over the wire.

Architecturally, HTTPie is a thin, well-factored layer over Requests/urllib3:

• A custom argument layer (httpie/cli/) parses both --flags and a small request-item DSL (Header:value, field=value, field:=json, param==value, field@file, …).
• A client layer (httpie/client.py) translates parsed arguments into a requests.Request, mounts HTTPie's own transport adapters, and yields request/response message objects.
• An output layer (httpie/output/) selects a stream class and a chain of formatter plugins to decode, prettify, and write each message.
• A plugin system (httpie/plugins/) exposes four extension points (auth, transport, converter, formatter) loaded from Python entry points.
• A management binary (httpie/manager/) handles plugin install/list/uninstall and session upgrades, distinct from the request commands.

There is no server, no daemon (except a short-lived update fetcher), and no persistent process. State lives in a config directory: config.json, session files, and a cached version-info file.

Architecture overview

                              ┌─────────────────────────────────────────┐
   argv ($ http / https /     │              ENTRY POINTS                │
   httpie ...)  ───────────►  │  __main__.py → core.raw_main()           │
                              │  (program_name basename → default scheme)│
                              └───────────────┬─────────────────────────┘
                                              │
                    ┌─────────────────────────▼──────────────────────────┐
                    │                 CLI / PARSING LAYER                 │
                    │  cli/definition.py  ParserSpec → to_argparse()      │
                    │  cli/argparser.py   HTTPieArgumentParser            │
                    │  cli/requestitems.py  RequestItems.from_args()      │
                    │  cli/argtypes.py    KeyValueArgType, auth, SSL      │
                    │  cli/nested_json/   interpret_nested_json()         │
                    └─────────────────────────┬──────────────────────────┘
                                              │ argparse.Namespace
                    ┌─────────────────────────▼──────────────────────────┐
                    │                   CLIENT LAYER                      │
                    │  client.collect_messages()                          │
                    │   ├─ get_httpie_session()    (sessions.py)          │
                    │   ├─ build_requests_session()                       │
                    │   │     mount HTTPieHTTPAdapter / HTTPieHTTPSAdapter │
                    │   │     + TransportPlugin adapters                  │
                    │   ├─ make_request_kwargs / make_send_kwargs         │
                    │   └─ yields PreparedRequest / Response objects      │
                    └─────────────────────────┬──────────────────────────┘
                                              │ RequestsMessage stream
                    ┌─────────────────────────▼──────────────────────────┐
                    │                   OUTPUT LAYER                      │
                    │  output/writer.py    write_message()                │
                    │  output/streams.py   Raw/Encoded/Pretty/Buffered    │
                    │  output/processing.py  Formatting, Conversion       │
                    │  output/formatters/  Headers/JSON/XML/Colors        │
                    └─────────────────────────┬──────────────────────────┘
                                              │
                                       stdout / stderr / file
                              (Downloader for --download; Rich for progress)

   PLUGINS (entry points)         CONFIG / STATE (~/.config/httpie)
   ├─ httpie.plugins.auth.v1      ├─ config.json
   ├─ httpie.plugins.transport.v1 ├─ sessions/<host>/<name>.json
   ├─ httpie.plugins.converter.v1 ├─ version_info.json
   └─ httpie.plugins.formatter.v1 └─ plugins/  (isolated install dir)

Two request binaries, one codebase

http and https are the same program. The only difference is the basename of argv[0]: core.raw_main() sets env.program_name = os.path.basename(program_name), and argparser._process_url() chooses the default scheme — when invoked as https, the scheme defaults to https://; otherwise it uses --default-scheme (default http). The httpie binary is a separate entry point (httpie/manager/__main__.py) with its own parser.

The request/response pipeline

The full path from command line to printed response, with the responsible functions:

1. Entry — httpie/__main__.py::main() calls core.main(), which calls raw_main(parser, program, args, env).
2. Pre-flight — raw_main() decodes raw byte args, detects daemon mode, loads installed plugins (plugin_manager.load_installed_plugins), prepends config.default_options, and handles --debug/--traceback.
3. Parse — HTTPieArgumentParser.parse_args() runs a sequence of private processors: _process_request_type, _process_download_options, _process_output_options, _process_pretty_options, _process_format_options, _guess_method, _parse_items, _process_url, _process_auth, _process_ssl_cert.
4. Request items — RequestItems.from_args() dispatches each item by its separator to a processor function, populating headers, data, params, files, and multipart_data. JSON nesting is resolved by cli/nested_json/interpret_nested_json().
5. Method inference — _guess_method() defaults to POST if there is input data, else GET.
6. Build & send — client.collect_messages() builds a requests.Session, mounts the HTTPie adapters and any transport plugins, prepares the request, applies --path-as-is/--compress, and yields each PreparedRequest and Response. Redirects are followed manually (response.next) governed by --follow/--max-redirects.
7. Output — core.program() iterates the yielded messages and calls output/writer.write_message(), which picks a stream class (get_stream_type_and_kwargs) and writes it to env.stdout.
8. Download — when --download is set, Downloader (in downloads.py) handles filename resolution, resume (Range/206), and progress display.
9. Exit — core maps outcomes to ExitStatus codes and HTTPie exits.

Output stream selection

output/writer.py::get_stream_type_and_kwargs() chooses one of four stream classes based on whether output is a TTY, whether prettification is enabled, and whether streaming is active:

Auto-streaming kicks in for Content-Type: text/event-stream.

Repository structure

httpie/
├── __init__.py            Package metadata (__version__ = '3.2.4')
├── __main__.py            `http` / `https` entry point
├── core.py                raw_main(), main(), program() — orchestration
├── client.py              Request building, Requests session, redirects
├── models.py              HTTPMessage / HTTPRequest / HTTPResponse, OutputOptions
├── sessions.py            Persistent JSON sessions
├── config.py              Config + BaseConfigDict, config dir resolution
├── context.py             Environment (streams, config, Rich consoles)
├── downloads.py           Download mode (Downloader, DownloadStatus)
├── uploads.py             Streaming uploads, chunked & compressed bodies
├── ssl_.py                HTTPieHTTPSAdapter, TLS version / cipher handling
├── adapters.py            HTTPieHTTPAdapter (multi-value header preservation)
├── cookies.py             HTTPieCookiePolicy (localhost-as-secure)
├── encoding.py            Charset detection / smart decode/encode
├── compat.py              Python version shims, importlib_metadata helpers
├── status.py              ExitStatus IntEnum, http_status_to_exit_status()
├── utils.py               JSON dup-key dict, cookie parsing, lockfiles
├── cli/                   Argument parsing & request-item DSL
│   ├── definition.py      The `http`/`https` parser spec (every flag)
│   ├── argparser.py       HTTPieArgumentParser + processing pipeline
│   ├── argtypes.py        KeyValueArgType, AuthCredentials, SSLCredentials
│   ├── constants.py       Separator constants, output option chars, enums
│   ├── requestitems.py    RequestItems — separator → processor dispatch
│   ├── options.py         ParserSpec / Group / Argument abstraction
│   ├── dicts.py           HTTPHeadersDict (multidict), multi-value dicts
│   ├── exceptions.py      ParseError
│   ├── utils.py           Manual / LazyChoices argparse actions
│   └── nested_json/       Nested JSON path parser (tokens, parse, interpret)
├── output/                Response rendering
│   ├── writer.py          write_message(), stream selection
│   ├── streams.py         Raw/Encoded/Pretty/BufferedPretty streams
│   ├── processing.py      Formatting + Conversion delegates
│   ├── models.py          ProcessingOptions
│   ├── formatters/        colors, headers, json, xml formatter plugins
│   ├── lexers/            Pygments lexers (http, json, metadata)
│   └── ui/                Rich help, palette, progress, man pages
├── plugins/               Plugin system
│   ├── base.py            BasePlugin + Auth/Transport/Converter/Formatter
│   ├── builtin.py         Basic / Digest / Bearer auth
│   ├── manager.py         PluginManager (entry-point loading)
│   └── registry.py        Global plugin_manager + built-in registration
├── manager/               The `httpie` management binary
│   ├── __main__.py        Entry point + http/https confusion detection
│   ├── cli.py             COMMANDS tree (cli, plugins, sessions)
│   ├── core.py            Dispatch to tasks
│   ├── compat.py          pip discovery / subprocess (run_pip)
│   └── tasks/             check_updates, export_args, plugins, sessions
├── internal/              Update-check daemon
│   ├── update_warnings.py Version fetch + warning logic
│   ├── daemons.py         Detached process spawning (double-fork / Windows)
│   └── daemon_runner.py   Daemon task runner
└── legacy/                Session-format back-compat shims (v3.1.0, v3.2.0)

Module reference

Core orchestration — core.py

raw_main() is the universal entry: it is shared by http/https (with the http parser) and httpie (with the manager parser, use_default_options=False). It centralizes error handling, mapping exceptions to exit codes:

program() drives the actual request/response loop, message separation, and the download finalization.

Client — client.py

collect_messages() is the generator at the heart of request execution. Key responsibilities:

• Loads/updates the HTTPie session when --session/--session-read-only is set.
• Builds default headers (make_default_headers): User-Agent: HTTPie/<version>, plus JSON or form Content-Type/Accept based on data and --form.
• Manually preserves repeated headers across Requests' preparation (apply_missing_repeated_headers) — Requests collapses duplicate headers, so HTTPie re-applies them.
• Wraps http.client._MAXHEADERS via the max_headers() context manager for --max-headers.
• Streams the request body through uploads.prepare_request_body() for chunked/compressed/file uploads.

Models — models.py

HTTPMessage/HTTPRequest/HTTPResponse wrap Requests' objects to expose a uniform headers/metadata/iter_body/iter_lines interface for the output layer. OutputOptions is a NamedTuple describing which parts (headers/body/meta) of a given message to print, derived from the --print string.

Headers dict — cli/dicts.py

HTTPHeadersDict (a case-insensitive multidict.CIMultiDict) is central to HTTPie's correct handling of multi-valued headers — a behavior plain Requests does not preserve. Setting a header value to None unsets it; add() supports multiple values per name.

Component inventory

The plugin API

HTTPie's extensibility is built on Python entry points. PluginManager.iter_entry_points() scans four groups and registers each discovered class:

Warning

The plugin API carries an explicit in-source disclaimer: "The plugin API is still work in progress and will probably be completely reworked in the future." Pin HTTPie versions when depending on plugin internals.

Writing an auth plugin

from httpie.plugins import AuthPlugin
import requests

class MyTokenAuth(requests.auth.AuthBase):
    def __init__(self, token):
        self.token = token
    def __call__(self, request):
        request.headers['X-Token'] = self.token
        return request

class MyAuthPlugin(AuthPlugin):
    name = 'My token auth'
    auth_type = 'my-token'      # value passed to --auth-type / -A
    description = 'Sends an X-Token header'
    # Tunable class attributes:
    auth_require = True         # require --auth, -a
    auth_parse = False          # don't split -a as username:password
    netrc_parse = False         # don't fall back to ~/.netrc
    prompt_password = False     # don't prompt when password is missing

    def get_auth(self, username=None, password=None):
        return MyTokenAuth(self.raw_auth)

Register it in your package's setup.cfg/pyproject.toml:

[options.entry_points]
httpie.plugins.auth.v1 =
    my_token = my_package:MyAuthPlugin

The other three extension points

Built-in plugins

Registered in plugins/registry.py:

• Auth: BasicAuthPlugin (basic), DigestAuthPlugin (digest), BearerAuthPlugin (bearer).
• Formatters: HeadersFormatter, JSONFormatter, XMLFormatter, ColorFormatter.

Plugin installation internals

httpie cli plugins install does not use a normal pip install into HTTPie's environment. Instead, manager/compat.py::run_pip() invokes pip (the bundled interpreter's -m pip, or a discovered system pip when running as a frozen binary) to install into an isolated plugins_dir (default: <config_dir>/plugins). At runtime, plugin_manager.load_installed_plugins() temporarily adds that directory to sys.path (enable_plugins) before scanning entry points. This is why plugins installed this way must also be uninstalled this way — see the warning emitted on load failure.

Configuration and state on disk

Config directory resolution

config.py::get_default_config_dir() resolves the directory in this order:

1. $HTTPIE_CONFIG_DIR if set.
2. On Windows: %APPDATA%\httpie.
3. Legacy ~/.httpie if it already exists.
4. $XDG_CONFIG_HOME/httpie (defaulting to ~/.config/httpie).

config.json

A simple JSON file (created on demand). Recognized keys:

default_options is prepended only for the request commands (use_default_options=True); the httpie manager binary ignores it.

On-disk layout

$HTTPIE_CONFIG_DIR/        (default ~/.config/httpie)
├── config.json
├── version_info.json      Cached latest-version data (update checker)
├── plugins/               Isolated plugin install dir
└── sessions/
    └── <host>/
        └── <name>.json     Named session files

Sessions: format and lifecycle

A session (sessions.py::Session, a BaseConfigDict subclass) is a JSON document persisting three things between requests to the same host:

• headers — except names prefixed with Content- or If- (SESSION_IGNORED_HEADER_PREFIXES), which are request-specific.
• auth — {type, raw_auth} (or legacy {type, username, password}).
• cookies — with name/value/domain/path/expires/secure fields.

Session resolution

get_httpie_session() decides between named and anonymous sessions: if the session name contains a path separator it is treated as an anonymous file path; otherwise it is a named session stored at sessions/<host>/<name>.json under the config directory. Session names are validated against ^[a-zA-Z0-9_.-]+$.

Cookie domain binding

Cookies carry a domain field that binds them to a host and its subdomains. A null domain makes a cookie unbound (sent to any host, including across cross-domain redirects). The legacy upgrade path and the --bind-cookies flag exist to remediate previously unbound cookies — see Security analysis.

Format upgrades

When HTTPie detects an obsolete session format it warns and offers upgrade commands:

httpie cli sessions upgrade-all
httpie cli sessions upgrade <host> <session-name-or-path> [--bind-cookies]

The legacy/ package (v3_1_0_session_cookie_format, v3_2_0_session_header_format) implements the format migrations applied during pre_process_data/post_process_data.

The update-check subsystem

HTTPie periodically checks whether a newer release is available (internal/update_warnings.py). Operators should understand its behavior:

• On each request, check_updates() runs (unless disable_update_warnings is set).
• At most every 2 weeks (FETCH_INTERVAL), it spawns a detached background daemon (internal/daemons.py, via double-fork on POSIX or a hidden process on Windows) that fetches https://packages.httpie.io/latest.json.
• Results are cached in version_info.json (written under a lockfile to avoid races between concurrent http processes).
• A warning is shown at most once per week (WARN_INTERVAL), pointing to the install method recorded in BUILD_CHANNEL.

Caution

The update fetch uses requests.get(PACKAGE_INDEX_LINK, verify=False) — TLS certificate verification is disabled for the version-check request. In hardened or air-gapped environments, set disable_update_warnings: true in config.json to stop the network call entirely.

Security analysis

HTTPie is a client tool that runs with the invoking user's privileges. The threat surface is mostly about credential handling, TLS, and untrusted servers.

Credential storage

Caution

Sessions store secrets in plain text. Authentication credentials, prompted passwords, cookies, and custom headers are all written to session JSON files in cleartext. Anyone with read access to the file can recover them. Treat session files like private keys: restrict filesystem permissions and avoid committing them.

• Basic-auth credentials are base64-encoded (not encrypted) into the Authorization header — standard HTTP basic auth.
• .netrc credentials are honored by default; disable per-request with --ignore-netrc.

TLS / SSL

• --verify=no disables certificate verification (cert_reqs=CERT_NONE), enabling man-in-the-middle attacks. Use a CA bundle (--verify=/path or REQUESTS_CA_BUNDLE) instead where possible.
• urllib3 insecure-request warnings are globally disabled (urllib3.disable_warnings() in client.py) — so HTTPie won't nag about --verify=no, which means the operator must self-enforce verification.
• TLS version (--ssl) and ciphers (--ciphers) are configurable; defaults negotiate the highest mutually supported protocol.
• Client certificates with encrypted keys prompt for a passphrase (or accept --cert-key-pass).
• The update check disables verification (see above).

Cookie scoping

• HTTPieCookiePolicy (cookies.py) treats localhost and *.localhost as secure hosts, matching modern browser behavior — secure cookies are returned to localhost over plain HTTP.
• Unbound session cookies (domain: null) are sent across hosts and redirect chains. This was the subject of security advisory GHSA-9w4w-cpc8-h2fq; the --bind-cookies upgrade flag binds such cookies to their session host as mitigation.

Untrusted input handling

• Binary response bodies are suppressed in the terminal (BinarySuppressedError) to prevent terminal-escape injection from hostile servers.
• XML formatting uses defused parsing to avoid XML entity-expansion attacks (the output/formatters/xml.py formatter; the test suite includes XML-bomb fixtures under tests/fixtures/xmldata/invalid/).
• File uploads and large bodies are streamed, bounding memory use against large inputs.

Operational hardening checklist

• [ ] Set restrictive permissions on the config directory and session files (chmod 700 ~/.config/httpie).
• [ ] Prefer --verify=<ca-bundle> over --verify=no; never disable verification against untrusted networks.
• [ ] Set disable_update_warnings: true in locked-down/air-gapped environments.
• [ ] Review and pin community plugins — they execute arbitrary code and are not vetted by the HTTPie project.
• [ ] Run httpie cli sessions upgrade-all --bind-cookies to remediate legacy unbound cookies.
• [ ] In scripts, always use --ignore-stdin and --timeout.

Requirements and dependencies

Runtime dependency stack

HTTPie is a thin layer over a small set of mature libraries, evident from its imports:

Note

On Windows, output streams are wrapped with colorama for ANSI handling. On non-Windows systems, curses (when available) is used to detect terminal color support.

Code quality and conventions

• Layered, single-responsibility modules. Parsing, client, output, and plugins are cleanly separated. The CLI definition (cli/definition.py) is declarative and serializable, which is what powers httpie cli export-args.
• Declarative parser spec. Rather than calling argparse directly, HTTPie builds an abstract ParserSpec of groups and arguments, then renders it to argparse (to_argparse) — and can also serialize it to JSON for external tooling.
• Type hints throughout, with typing.NamedTuple for immutable value objects (OutputOptions, ProcessingOptions, Argument).
• Compatibility shims isolated in compat.py (cached_property backport, importlib_metadata differences across 3.7–3.10).
• Custom exceptions map cleanly to user-facing errors: ParseError, ConfigFileError, ContentRangeError, NestedJSONSyntaxError, PipError.
• Known maintainability notes acknowledged in-source: the parsing pipeline (HTTPieArgumentParser.parse_args) is a long ordered sequence of _process_* methods with TODO markers calling for refactor; core.program() is flagged for simplification of its separator logic.

Testing strategy

The tests/ directory holds a broad suite (40+ test modules) covering each feature area, runnable with pytest:

Test infrastructure (tests/utils/) provides MockEnvironment, an embedded http_server, a plugins-CLI fixture harness, and a response-matching DSL (tests/utils/matching/).

Building and packaging

• PyPI is the canonical distribution (python -m pip install httpie); setup.py delegates to setup.cfg.
• OS packages are maintained for APT, DNF/Yum, pacman, Homebrew, MacPorts, Chocolatey, Snap, and FreshPorts (see docs/installation/methods.yml — the single source of truth for the documented install commands).
• Standalone Linux binaries are built (PyInstaller-style) and published at packages.httpie.io/binaries/. Frozen builds set is_frozen, which changes plugin pip discovery and Python-version site-path handling.
• Man pages for http, https, and httpie are generated at release time (extras/scripts/generate_man_pages.py); the HTTPIE_BUILDING_MAN_PAGES env var suppresses system-specific content (like the default cipher list) so man pages are reproducible.
• __build_channel__.py records the packaging method per build; the update checker uses it to point users at the right upgrade instructions.

Potential improvements

Drawn from in-source TODO/FIXME markers and observed structure:

1. Refactor the argument-processing pipeline. HTTPieArgumentParser.parse_args() runs a long, order-sensitive chain of _process_* methods with several TODOs requesting type-annotated, immutable arg structures.
2. Simplify core.program(). An in-source TODO calls out the message-separator logic as needing extraction.
3. Stabilize the plugin API. The package docstring warns it "will probably be completely reworked" — versioned entry-point groups (.v1) anticipate this, but a documented stability contract would help the plugin ecosystem.
4. Reconsider --chunked opt-in for stdin. A TODO in uploads.py notes that chunked transfer for stdin could become opt-out (a breaking change deferred to a future major version).
5. Verify the update check over TLS. The verify=False fetch in update_warnings.py is a hardening gap worth closing.
6. Resolve open community issues, e.g. JSON Content-Type not being set when a single header is present (#1640 / #1834) and argument-parsing differences on Python 3.13+ (#1838).

Contributing

• Repository: github.com/httpie/cli — see CONTRIBUTING.md.
• Docs are source-controlled: the user manual lives in docs/README.md; the installation section is generated from docs/installation/methods.yml via docs/installation/generate.py (don't edit the generated block by hand).
• Run the tests: pytest from the repo root.
• Security policy: github.com/httpie/cli/security/policy.
• License: BSD-3-Clause. Created by Jakub Roztocil and contributors.

Tip

Because the parser spec is serializable (httpie cli export-args), external tools (shells, editors) can build autocomplete from HTTPie's own definition rather than re-implementing the flag list. If you add a flag in cli/definition.py, it automatically appears in the exported schema.

Quick reference

Entry points

Plugin entry-point groups

Management commands

Exit status codes

Key files on disk