0
# Configuration
1

2
HTTPie's configuration system allows you to customize default behavior, set persistent options, and manage plugin settings through configuration files and environment variables.
3

4
```python
5
from httpie.config import Config, get_default_config_dir, DEFAULT_CONFIG_DIR, ConfigFileError
6
from pathlib import Path
7
from typing import Union, List
8
```
9

10
## Capabilities
11

12
### Configuration Class
13

14
The main configuration management interface for HTTPie settings.
15

16
```python { .api }
17
class Config:
18
    """HTTPie configuration management."""
19
    
20
    def __init__(self, directory: Union[str, Path] = DEFAULT_CONFIG_DIR):
21
        """
22
        Initialize configuration.
23
        
24
        Args:
25
            directory: Configuration directory path (uses default if None)
26
        """
27
    
28
    @property
29
    def default_options(self) -> list:
30
        """Default command-line options applied to all requests."""
31
    
32
    @property  
33
    def plugins_dir(self) -> Path:
34
        """Directory path for HTTPie plugins."""
35
    
36
    def load(self) -> None:
37
        """Load configuration from config file."""
38
    
39
    def save(self) -> None:
40
        """Save current configuration to file."""
41
    
42
    def is_new(self) -> bool:
43
        """True if configuration file doesn't exist yet."""
44
```
45

46
### Configuration Directory Functions
47

48
```python { .api }
49
def get_default_config_dir() -> str:
50
    """
51
    Get the default HTTPie configuration directory.
52
    
53
    Returns:
54
        str: Platform-specific configuration directory path
55
    """
56

57
DEFAULT_CONFIG_DIR: str = get_default_config_dir()
58
"""Default configuration directory constant."""
59
```
60

61
### Configuration File Location
62

63
HTTPie stores configuration in platform-specific locations:
64

65
- **Linux/macOS**: `~/.config/httpie/config.json`
66
- **Windows**: `%APPDATA%\httpie\config.json`
67

68
### Configuration File Format
69

70
The configuration file uses JSON format:
71

72
```json
73
{
74
  "default_options": [
75
    "--style=solarized", 
76
    "--timeout=30",
77
    "--follow"
78
  ],
79
  "implicit_content_type": "json",
80
  "__meta__": {
81
    "about": "HTTPie configuration file",
82
    "help": "https://httpie.io/docs#config",
83
    "httpie": "3.2.4"
84
  }
85
}
86
```
87

88
### Default Options
89

90
Set command-line options that apply to all HTTPie requests:
91

92
```json
93
{
94
  "default_options": [
95
    "--style=monokai",        // Color scheme
96
    "--timeout=60",           // Request timeout
97
    "--follow",               // Follow redirects
98
    "--check-status",         // Exit with error for HTTP errors
99
    "--print=HhBb",          // Print headers and body for request/response
100
    "--pretty=all",          // Pretty-print everything
101
    "--verify=yes"           // SSL verification
102
  ]
103
}
104
```
105

106
### Programmatic Configuration
107

108
```python { .api }
109
from httpie.config import Config
110
from httpie.context import Environment
111

112
# Load configuration
113
env = Environment()
114
config = env.config
115

116
# Check if configuration exists
117
if config.is_new():
118
    print("No configuration file found, using defaults")
119

120
# Access default options
121
print(f"Default options: {config.default_options}")
122

123
# Get plugins directory
124
print(f"Plugins directory: {config.plugins_dir}")
125

126
# Modify and save configuration
127
config.default_options.append("--timeout=120")
128
config.save()
129
```
130

131
### Environment Variables
132

133
HTTPie respects several environment variables:
134

135
```bash { .api }
136
# Configuration directory override
137
export HTTPIE_CONFIG_DIR="/custom/config/path"
138

139
# Disable configuration file
140
export HTTPIE_CONFIG_DIR=""
141

142
# Default options (space-separated)
143
export HTTPIE_DEFAULT_OPTIONS="--style=solarized --timeout=30"
144

145
# Plugin directory override
146
export HTTPIE_PLUGINS_DIR="/custom/plugins/path"
147
```
148

149
### Configuration Precedence
150

151
HTTPie applies options in the following order (later options override earlier ones):
152

153
1. **Built-in defaults**
154
2. **Configuration file** (`config.json`)
155
3. **Environment variables** (`HTTPIE_DEFAULT_OPTIONS`)
156
4. **Command-line arguments**
157

158
### Advanced Configuration Options
159

160
#### SSL/TLS Configuration
161

162
```json
163
{
164
  "default_options": [
165
    "--verify=ca-bundle.pem",     // Custom CA bundle
166
    "--cert=client.pem",          // Client certificate
167
    "--cert-key=client-key.pem"   // Client certificate key
168
  ]
169
}
170
```
171

172
#### Proxy Configuration
173

174
```json
175
{
176
  "default_options": [
177
    "--proxy=http:http://proxy.example.com:8080",
178
    "--proxy=https:https://proxy.example.com:8080"
179
  ]
180
}
181
```
182

183
#### Output Configuration
184

185
```json
186
{
187
  "default_options": [
188
    "--style=native",           // Syntax highlighting style
189
    "--format-options=json.indent:4",  // JSON formatting
190
    "--format-options=headers.sort:true"  // Sort headers
191
  ]
192
}
193
```
194

195
### Configuration Validation
196

197
```python { .api }
198
class ConfigFileError(Exception):
199
    """Configuration file parsing or validation error."""
200
    pass
201
```
202

203
Configuration errors are handled gracefully:
204

205
```python
206
from httpie.config import Config, ConfigFileError
207

208
try:
209
    config = Config()
210
    config.load()
211
except ConfigFileError as e:
212
    print(f"Configuration error: {e}")
213
    # HTTPie continues with default settings
214
```
215

216
### Configuration Management Commands
217

218
The `httpie` command provides configuration management:
219

220
```bash { .api }
221
# Show current configuration
222
httpie config
223

224
# Edit configuration file
225
httpie config --edit
226

227
# Reset to defaults
228
httpie config --reset
229

230
# Show configuration directory
231
httpie config --dir
232
```
233

234
### Session-Specific Configuration
235

236
Some configuration applies only to specific sessions:
237

238
```bash
239
# Session-specific defaults
240
http --session=api --style=monokai api.example.com/login
241

242
# Configuration is saved with the session
243
http --session=api api.example.com/data  # Uses monokai style
244
```
245

246
### Plugin Configuration
247

248
Plugins can access configuration through the environment:
249

250
```python
251
class MyPlugin(AuthPlugin):
252
    def get_auth(self, username=None, password=None):
253
        # Access global configuration
254
        config = self.env.config
255
        
256
        # Check for plugin-specific settings
257
        plugin_options = getattr(config, 'my_plugin_options', {})
258
        
259
        return MyAuth(plugin_options)
260
```
261

262
### Configuration Examples
263

264
#### Development Configuration
265

266
```json
267
{
268
  "default_options": [
269
    "--debug",
270
    "--traceback", 
271
    "--timeout=120",
272
    "--style=fruity",
273
    "--format-options=json.indent:2"
274
  ]
275
}
276
```
277

278
#### Production Configuration
279

280
```json
281
{
282
  "default_options": [
283
    "--timeout=30",
284
    "--check-status",
285
    "--follow",
286
    "--verify=yes",
287
    "--style=none"
288
  ]
289
}
290
```
291

292
#### API Testing Configuration
293

294
```json
295
{
296
  "default_options": [
297
    "--json",
298
    "--print=HhBb",
299
    "--style=solarized",
300
    "--format-options=json.indent:2",
301
    "--format-options=headers.sort:true"
302
  ]
303
}
304
```
305

306
### Migration and Backup
307

308
Configuration files can be copied between systems:
309

310
```bash
311
# Backup configuration
312
cp ~/.config/httpie/config.json ~/httpie-config-backup.json
313

314
# Restore configuration  
315
cp ~/httpie-config-backup.json ~/.config/httpie/config.json
316

317
# Copy to another system
318
scp ~/.config/httpie/config.json user@remote:~/.config/httpie/
319
```