HTTPie Cheatsheet¶

Installation¶

Platform	Command
Ubuntu/Debian	`sudo apt update && sudo apt install httpie`
Fedora/RHEL	`sudo dnf install httpie`
Arch Linux	`sudo pacman -S httpie`
macOS (Homebrew)	`brew install httpie`
Windows (Chocolatey)	`choco install httpie`
Windows (Scoop)	`scoop install httpie`
Windows (winget)	`winget install httpie`
pip (Universal)	`pip install --upgrade httpie`
pipx (Isolated)	`pipx install httpie`
Docker	`docker run -it --rm alpine/httpie`
Snap	`sudo snap install httpie`

Verify Installation:

http --version

Basic Commands¶

Command	Description
`http GET api.example.com/users`	Basic GET request (explicit method)
`http api.example.com/users`	GET request (implicit, GET is default)
`http api.example.com/users id==123`	GET with query parameter
`http POST api.example.com/users name="John" email="john@example.com"`	POST request with JSON data
`http PUT api.example.com/users/123 name="Jane"`	PUT request to update resource
`http PATCH api.example.com/users/123 email="new@example.com"`	PATCH request for partial update
`http DELETE api.example.com/users/123`	DELETE request to remove resource
`http api.example.com/users User-Agent:MyApp/1.0`	Add custom header (use `:` separator)
`http -a username:password api.example.com/protected`	Basic authentication
`http api.example.com/api Authorization:"Bearer token123"`	Bearer token authentication
`http --download api.example.com/files/report.pdf`	Download file with original filename
`http -d -o report.pdf api.example.com/files/report.pdf`	Download with custom filename
`http -f POST api.example.com/upload file@/path/to/file.txt`	Upload file
`http -f POST api.example.com/login username=john password=secret`	Submit form data
`http --follow api.example.com/redirect`	Follow redirects automatically
`http --timeout=30 api.example.com/slow-endpoint`	Set request timeout (seconds)
`http --verify=no https://self-signed.example.com`	Ignore SSL certificate verification
`http -v api.example.com/users`	Verbose output (show request & response)
`http -o users.json api.example.com/users`	Save response to file
`http api.example.com/search q=="HTTPie tutorial" page==1`	Multiple query parameters

Advanced Usage¶

Command	Description
`http --session=mysession api.example.com/login username=john`	Create named session (persists cookies/headers)
`http --session=mysession api.example.com/profile`	Reuse existing session
`http --session-read-only=mysession api.example.com/data`	Use session without updating it
`http POST api.example.com/users age:=30 active:=true`	Send non-string JSON values (`:=` for raw JSON)
`http POST api.example.com/users profile:='{"age":30,"city":"NYC"}'`	Send nested JSON object
`http POST api.example.com/users tags:='["python","api"]'`	Send JSON array
`http POST api.example.com/users middle_name:=null`	Send null value
`echo '{"name":"John"}' \\| http POST api.example.com/users`	Pipe raw JSON body
`http POST api.example.com/users < data.json`	Send JSON from file
`http POST api.example.com/config settings:=@config.json`	Use file content as JSON value
`http --print=H api.example.com/users`	Print only request headers
`http --print=h api.example.com/users`	Print only response headers
`http --print=Hh api.example.com/users`	Print request and response headers
`http --print=b api.example.com/users`	Print only response body
`http --pretty=none api.example.com/users`	Disable formatting and colors
`http --stream api.example.com/large-dataset`	Stream large response
`http --proxy=http:http://proxy.com:8080 api.example.com/users`	Use HTTP proxy
`http --proxy=http:http://user:pass@proxy.com:8080 api.example.com`	Proxy with authentication
`http --max-redirects=5 --follow api.example.com/redirect`	Limit redirect following
`http -f POST api.example.com/upload file1@file.txt file2@image.jpg`	Upload multiple files
`http OPTIONS api.example.com/users`	Send OPTIONS request
`http --continue api.example.com/large-file.zip`	Resume interrupted download
`http api.example.com/users X-Custom:val1 X-Custom:val2`	Multiple headers with same name
`http --auth-type=digest -a user:pass api.example.com/protected`	Digest authentication

Request Item Types¶

HTTPie uses special operators to distinguish data types:

Operator	Type	Example	Result
`=`	String (JSON)	`name=John`	`{"name": "John"}`
`:=`	Raw JSON	`age:=30`	`{"age": 30}`
`==`	Query parameter	`id==123`	`?id=123`
`:`	Header	`X-API-Key:abc`	`X-API-Key: abc`
`@`	File upload	`file@path.txt`	Multipart file
`=@`	File as value	`data=@file.txt`	File content as string
`:=@`	File as JSON	`config:=@file.json`	File content as JSON

Output Control¶

Flag	Description
`--print=H`	Request headers only
`--print=h`	Response headers only
`--print=b`	Response body only
`--print=Hh`	Request and response headers
`--print=Hhb`	Headers and body (default)
`-v, --verbose`	Print everything (equivalent to `--print=HhBb`)
`-h, --headers`	Print only response headers (shortcut)
`-b, --body`	Print only response body (shortcut)
`--pretty=all`	Format and colorize (default)
`--pretty=none`	No formatting or colors
`--pretty=format`	Format only, no colors
`--pretty=colors`	Colors only, no formatting
`-o, --output=FILE`	Save output to file
`--stream`	Stream response (don't buffer)

Configuration¶

HTTPie stores configuration in platform-specific locations:

Configuration File Locations: - Linux/macOS: ~/.config/httpie/config.json - Windows: %APPDATA%\httpie\config.json

Example Configuration:

{
    "default_options": [
        "--style=monokai",
        "--timeout=30"
    ],
    "implicit_content_type": "json",
    "prettify": true
}

Session Files Location: - Linux/macOS: ~/.config/httpie/sessions/<host>/<session-name>.json - Windows: %APPDATA%\httpie\sessions\<host>\<session-name>.json

Example Session File:

{
    "headers": {
        "Authorization": "Bearer token123",
        "User-Agent": "MyApp/1.0"
    },
    "cookies": {
        "session_id": "abc123"
    }
}

Environment Variables:

# Set default options
export HTTPIE_CONFIG_DIR=~/.config/httpie

# Disable colors
export NO_COLOR=1

# Set default timeout
export HTTPIE_TIMEOUT=60

Common Use Cases¶

Use Case 1: Testing REST API CRUD Operations¶

# Create a new user (POST)
http POST api.example.com/users name="John Doe" email="john@example.com" age:=30

# Read user details (GET)
http GET api.example.com/users/123

# Update user (PUT)
http PUT api.example.com/users/123 name="Jane Doe" email="jane@example.com"

# Partial update (PATCH)
http PATCH api.example.com/users/123 email="newemail@example.com"

# Delete user (DELETE)
http DELETE api.example.com/users/123

Use Case 2: API Authentication Flow¶

# Login and create session
http --session=myapp POST api.example.com/auth/login \
  username="john@example.com" \
  password="secret123"

# Access protected endpoint using session (token/cookies persist)
http --session=myapp GET api.example.com/profile

# Make authenticated requests
http --session=myapp POST api.example.com/posts \
  title="My Post" \
  content="Post content here"

# Logout
http --session=myapp POST api.example.com/auth/logout

Use Case 3: File Upload with Metadata¶

# Upload file with form data
http -f POST api.example.com/documents \
  file@/path/to/document.pdf \
  title="Q4 Report" \
  category="financial" \
  confidential:=true

# Upload multiple files
http -f POST api.example.com/gallery \
  images[]@photo1.jpg \
  images[]@photo2.jpg \
  images[]@photo3.jpg \
  album="Vacation 2024"

Use Case 4: API Testing with Complex JSON¶

# Create user with nested profile data
http POST api.example.com/users \
  name="John Doe" \
  email="john@example.com" \
  profile:='{"age":30,"address":{"city":"NYC","zip":"10001"},"tags":["developer","python"]}' \
  settings:='{"notifications":true,"theme":"dark"}' \
  active:=true

# Alternative: Use file for complex JSON
cat > user_data.json <<EOF
{
  "name": "John Doe",
  "email": "john@example.com",
  "profile": {
    "age": 30,
    "address": {
      "city": "NYC",
      "zip": "10001"
    }
  }
}
EOF

http POST api.example.com/users < user_data.json

Use Case 5: Debugging API with Headers and Verbose Output¶

# View complete request and response
http -v POST api.example.com/debug \
  X-Request-ID:abc-123 \
  X-Debug:true \
  data="test payload"

# Check only headers for troubleshooting
http --print=Hh api.example.com/status

# Test with different user agents
http api.example.com/content \
  User-Agent:"Mozilla/5.0 (Windows NT 10.0; Win64; x64)" \
  Accept:"text/html,application/json"

# Debug redirects
http --follow --all --print=Hh api.example.com/redirect

Best Practices¶

Use sessions for stateful testing: When testing authenticated endpoints or workflows that require cookies, use --session to persist state between requests instead of manually managing tokens
Leverage implicit JSON: HTTPie assumes JSON by default, so you can omit Content-Type headers and quotes around simple values (name=John instead of "name":"John")
Prefer pipx over pip for installation: Installing with pipx isolates HTTPie in its own environment, preventing dependency conflicts with other Python tools
Use named sessions for different environments: Create separate sessions for development, staging, and production (--session=dev, --session=prod) to avoid accidentally hitting wrong environments
Save complex requests as shell scripts: For frequently used complex requests, save them as executable shell scripts with descriptive names for easy reuse and documentation
Use --print flags for CI/CD: In automated testing, use --print=b to output only the response body for easier parsing, or --check-status to fail on HTTP errors
Protect sensitive data: Never include passwords or API keys directly in commands that get logged; use http -a username (prompts for password) or environment variables instead
Use --timeout for production: Always set reasonable timeouts in production scripts to prevent hanging requests (--timeout=30 is a good default)

Troubleshooting¶

Issue	Solution
`http: command not found`	Ensure HTTPie is installed and in PATH. Try `python3 -m httpie` or reinstall with `pip install --user httpie`
SSL certificate verification fails	Use `--verify=no` to bypass (testing only), or `--verify=/path/to/ca-bundle.crt` to provide custom CA bundle
Request hangs indefinitely	Add `--timeout=30` to set timeout. Check if endpoint is responding with `curl` or browser first
JSON parsing error	Ensure proper syntax: use `:=` for raw JSON (`age:=30`), `=` for strings (`name=John`). Check quotes in nested JSON
Session not persisting	Verify session file location with `http --debug`. Ensure you're using same session name. Check file permissions on config directory
Form upload not working	Use `-f` flag for form data (`http -f POST ...`). Use `@` for files (`file@path.txt`), `=` for text fields
Colors not displaying	Check terminal supports colors. Set `--pretty=all` explicitly or check `NO_COLOR` environment variable isn't set
Authentication fails	Verify credentials format: `-a user:pass` for Basic auth. For Bearer tokens use `Authorization:"Bearer token"` header
Proxy connection issues	Check proxy URL format: `--proxy=http:http://proxy:8080`. Test proxy with curl first. Verify proxy credentials if required
Response too large / memory error	Use `--stream` flag to stream response instead of buffering: `http --stream api.example.com/large-file`
Cannot upload large files	Use `--stream` for request streaming: `http --stream POST api.example.com/upload @large-file.zip`
Headers not being sent	Ensure header syntax uses `:` separator (`X-Header:value`). Check for typos. Use `-v` to verify headers in request

Quick Reference: Common Patterns¶

Query Parameters:

http api.example.com/search q=="search term" page==1 limit==20

JSON Data Types:

http POST api.example.com/data \
  string_field="text" \
  number_field:=42 \
  boolean_field:=true \
  null_field:=null \
  array_field:='[1,2,3]' \
  object_field:='{"key":"value"}'

Headers:

http api.example.com/api \
  Authorization:"Bearer token" \
  Content-Type:application/json \
  X-Custom-Header:value

File Operations:

# Upload
http -f POST api.example.com/upload file@document.pdf

# Download
http --download api.example.com/files/document.pdf

# Use file content as JSON
http POST api.example.com/config settings:=@config.json

Output Control:

# Only response body
http -b api.example.com/users

# Only headers
http -h api.example.com/users

# Everything verbose
http -v api.example.com/users

# Save to file
http -o output.json api.example.com/users