httpie

HTTPie

HTTPie provides an intuitive CLI and desktop client for testing, debugging, and interacting with HTTP APIs, featuring human-readable syntax and formatted JSON output.

When to Use

• Human-Friendly CLI API Testing: Intuitive, colorized HTTP client alternative to curl with concise JSON syntax.
• Session & Authentication Management: Persisting auth headers, cookies, and tokens across requests using --session.
• Form Data & File Uploads: Uploading multi-part forms and files with progress bars and MIME type detection.
• API Prototyping & Scripting: Testing GraphQL, REST, and streaming SSE endpoints from the terminal.

Quick Start

# Intuitive JSON POST request with automatic formatting and colorization
http POST api.example.com/users \
  Authorization:"Bearer $TOKEN" \
  name="Alice" \
  email="alice@example.com" \
  age:=30 \
  active:=true

Core Concepts

Intuitive JSON Request & Header Syntax

Sending structured JSON payloads without escaping quotes:

# POST request with JSON body (string vs number vs boolean syntax)
http POST https://api.example.com/v1/orders \
  Authorization:"Bearer $API_TOKEN" \
  customer_id="cust_1029" \
  amount:=149.50 \
  is_gift:=true \
  items:='["item_1", "item_2"]'

# GET request with query parameters (using ==)
http GET https://api.example.com/v1/orders \
  status==active \
  limit==10 \
  sort==desc

Persistent Sessions for Authenticated Workflows

Saving authentication tokens and session cookies:

# 1. Log in and save session cookies/tokens to 'staging' session
http --session=staging POST https://api.example.com/auth/login \
  username="admin@example.com" \
  password="SecretPassword2026"

# 2. Subsequent requests automatically reuse session state
http --session=staging GET https://api.example.com/dashboard/kpi

Form Submissions & File Uploads

Uploading files with multi-part encoding:

# Upload document with progress bar
http --form POST https://api.example.com/upload \
  title="Financial Report" \
  document@./annual_report.pdf

Common Patterns

Session Persistence for Authenticated API Testing

Problem: Re-specifying headers, tokens, and cookies across repeated curl requests during debugging.

Solution: Use HTTPie named sessions:

# Log in and automatically persist session cookies and headers
http --session=admin-session POST api.example.com/login username=admin password=secret

# Subsequent requests automatically use saved authentication state
http --session=admin-session GET api.example.com/dashboard/stats

Best Practices

Do:

• Use := for non-string JSON values (numbers, booleans, arrays) and = for string values.
• Use --session to avoid repeating authentication headers across sequential CLI requests.
• Use --print=HhBb to control which headers and body elements are printed to terminal output.
• Pipe output to jq using --json flag when combining with shell scripts.

Don't:

• Include plain text passwords in shell history; supply via environment variables or prompt.
• Forget == when specifying URL query parameters (single = defines request body properties).
• Use HTTPie in resource-constrained container images if minimal /bin/sh with curl suffices.

Troubleshooting

Error	Cause	Solution
http: error: ConnectionError: Connection refused	Target local server port down or firewall blocking connection.	Verify local service is listening on targeted port.
Invalid JSON type: string passed instead of number	Used = instead of := for non-string JSON values.	Use := for numbers/booleans: count:=10 (vs name="string").
SSL: CERTIFICATE_VERIFY_FAILED	Local dev server using self-signed SSL certificate.	Add --verify=no flag for development testing.

References

• HTTPie Documentation