HTTPie Cheatsheet

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`
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