0
# Command-Line Interface
1
2
HTTPie's command-line interface provides three main commands for making HTTP requests and managing HTTPie functionality.
3
4
```python
5
from httpie.status import ExitStatus
6
from httpie.cli.constants import *
7
```
8
9
## Capabilities
10
11
### HTTP Command
12
13
The primary `http` command for making HTTP requests with intuitive syntax.
14
15
```bash { .api }
16
http [METHOD] URL [REQUEST_ITEM ...]
17
18
# METHOD: HTTP method (GET, POST, PUT, DELETE, etc.) - defaults to GET
19
# URL: Request URL
20
# REQUEST_ITEM: Request items in key=value, key:=json, key@file formats
21
```
22
23
**Request Items:**
24
- `key=value` - Form fields or query parameters
25
- `key:=value` - JSON data (value is parsed as JSON)
26
- `key:=@file` - JSON data from file
27
- `key@file` - File upload
28
- `Header:value` - Custom HTTP headers
29
30
**Usage Examples:**
31
32
```bash
33
# GET request
34
http httpie.io/hello
35
36
# POST with JSON data
37
http POST pie.dev/post name=John age:=30 active:=true
38
39
# Custom headers
40
http pie.dev/headers X-Custom-Header:value Authorization:"Bearer token"
41
42
# File upload
43
http --form POST pie.dev/post avatar@~/avatar.jpg
44
45
# Query parameters
46
http pie.dev/get search==httpie limit==10
47
```
48
49
### HTTPS Command
50
51
Identical to `http` but defaults to HTTPS protocol.
52
53
```bash { .api }
54
https [METHOD] URL [REQUEST_ITEM ...]
55
```
56
57
### HTTPie Management Command
58
59
The `httpie` command provides package and plugin management functionality.
60
61
```bash { .api }
62
httpie [COMMAND] [OPTIONS]
63
64
# Available commands:
65
# plugins - Plugin management
66
# sessions - Session management
67
# export - Export functionality
68
```
69
70
### Common Options
71
72
#### Output Control
73
74
```bash { .api }
75
--print=WHAT # Control output: H (headers), B (body), h (request headers), b (request body)
76
--headers, -h # Print only response headers
77
--body, -b # Print only response body
78
--verbose, -v # Verbose output
79
--quiet, -q # Quiet output
80
```
81
82
#### Request Configuration
83
84
```bash { .api }
85
--json, -j # Serialize data as JSON (default for non-form)
86
--form, -f # Serialize data as form (default for form data)
87
--pretty=FORMAT # Pretty-print format: all, colors, format, none
88
--style=STYLE # Output style (auto, solarized, etc.)
89
--auth=USER:PASS, -a # Authentication credentials
90
--auth-type=TYPE # Authentication type
91
--session=NAME # Session name for persistent data
92
```
93
94
#### HTTP Options
95
96
```bash { .api }
97
--timeout=SECONDS # Request timeout
98
--max-redirects=NUM # Maximum number of redirects
99
--follow, -F # Follow redirects
100
--check-status # Exit with error status for HTTP error codes
101
--verify=VERIFY # SSL certificate verification
102
--cert=FILE # SSL client certificate
103
--proxy=PROTOCOL:URL # Proxy configuration
104
```
105
106
#### Downloads
107
108
```bash { .api }
109
--download, -d # Download mode
110
--continue, -c # Resume partial download
111
--output=FILE, -o # Output file for download
112
```
113
114
#### Debugging
115
116
```bash { .api }
117
--offline # Build request without sending
118
--debug # Debug mode with detailed information
119
--traceback # Show full exception traceback
120
```
121
122
### Exit Status Codes
123
124
HTTPie returns different exit codes based on the request outcome:
125
126
```python { .api }
127
# Success
128
0 # OK - request completed successfully
129
130
# General errors
131
1 # Error - general error (network, parsing, etc.)
132
2 # Timeout - request timed out
133
6 # Too many redirects
134
135
# HTTP status-based errors (when --check-status is used)
136
3 # HTTP 3xx (redirection)
137
4 # HTTP 4xx (client error)
138
5 # HTTP 5xx (server error)
139
140
# Special cases
141
7 # Plugin error
142
130 # Keyboard interrupt (Ctrl+C)
143
```
144
145
### Configuration Files
146
147
HTTPie reads configuration from:
148
149
- **Config file**: `~/.config/httpie/config.json` (Linux/macOS)
150
- **Sessions directory**: `~/.config/httpie/sessions/`
151
- **Plugins directory**: `~/.config/httpie/plugins/`
152
153
**Example config.json:**
154
155
```json
156
{
157
"default_options": [
158
"--style=solarized",
159
"--timeout=60"
160
]
161
}
162
```
163
164
### Request Examples
165
166
#### Authentication
167
168
```bash
169
# Basic auth
170
http -a username:password httpie.io/basic-auth/username/password
171
172
# Bearer token
173
http pie.dev/bearer Authorization:"Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9"
174
175
# Custom auth plugin
176
http --auth-type=ntlm -a domain\\username:password example.com
177
```
178
179
#### JSON Requests
180
181
```bash
182
# Simple JSON
183
http POST pie.dev/post name=John age:=30
184
185
# Nested JSON
186
http POST pie.dev/post user[name]=John user[age]:=30
187
188
# JSON from file
189
http POST pie.dev/post @data.json
190
191
# Mixed data
192
http POST pie.dev/post name=John age:=30 token:=@token.txt
193
```
194
195
#### File Uploads
196
197
```bash
198
# Single file upload
199
http --form POST pie.dev/post file@document.pdf
200
201
# Multiple files
202
http --form POST pie.dev/post file1@image.jpg file2@document.pdf
203
204
# File with metadata
205
http --form POST pie.dev/post file@image.jpg description="Profile photo"
206
```
207
208
#### Sessions
209
210
```bash
211
# Create session with login
212
http --session=user1 -a john:password pie.dev/basic-auth/john/password
213
214
# Use session for subsequent requests
215
http --session=user1 pie.dev/user/profile
216
217
# Session persists cookies, auth, and custom headers
218
http --session=user1 pie.dev/api/data X-Custom-Header:value
219
```