carapace-sh/carapace-bin / skills/httpie
httpie
UnverifiedUse when working with HTTPie (http/https CLI) — the command-line HTTP client for the API era. Covers request items syntax (headers, params, data fields, file uploads), authentication (basic, digest, bearer, plugins), session management, output formatting and printing, SSL/TLS configuration, download mode, configuration files, environment variables, plugin system, exit codes, scripting, and URL syntax. Triggers on: "httpie", "http command", "https command", "http --json", "http --form", "http --download", "http --session", "http --auth", "http --auth-type", "http --print", "http --verbose", "http --follow", "http --offline", "http --check-status", "http --proxy", "http --ssl", "http --cert", "http --verify", "http --format-options", "http --pretty", "http --style", "http --stream", "http --boundary", "http --multipart", "http --raw", "httpie config", "HTTPIE_CONFIG_DIR", "httpie cli plugins", "request items", "data fields", "URL parameters", "HTTP headers", "raw JSON fields", "file upload fields", "named session", "anonymous session", "read-only session", "Content-Disposition", "httpie-unixsocket", "httpie plugins", "AuthPlugin", "TransportPlugin", "ConverterPlugin", "FormatterPlugin".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.2 KB |
| references/auth.md | markdown | 3.3 KB |
| references/cli.md | markdown | 6.6 KB |
| references/config.md | markdown | 4.0 KB |
| references/downloads.md | markdown | 3.7 KB |
| references/output.md | markdown | 6.1 KB |
| references/plugins.md | markdown | 5.6 KB |
| references/request-items.md | markdown | 4.9 KB |
| references/scripting.md | markdown | 3.7 KB |
| references/sessions.md | markdown | 5.0 KB |
| references/ssl.md | markdown | 2.8 KB |
| references/url-syntax.md | markdown | 3.5 KB |
references/sessions.md
View on GitHub# Session Management
HTTPie's persistent session system — named sessions, anonymous sessions, read-only sessions, cookie persistence, and session upgrades.
## Overview
By default, every HTTPie request is independent. Sessions allow data (headers, auth, cookies) to persist between requests to the same host.
```bash
# Create a session with auth + custom header
$ http --session=user1 -a user1:password pie.dev/get X-Foo:Bar
# Reuse the session — auth + headers are automatically applied
$ http --session=user1 pie.dev/get
```
## What Is Persisted
| Data | Persisted? | Notes |
|------|-----------|-------|
| Custom HTTP headers | Yes | Except headers starting with `Content-` or `If-` |
| Authentication credentials | Yes | Including prompted passwords |
| Cookies (from `Set-Cookie`) | Yes | Server-sent cookies are stored |
| Cookies (from command line) | Yes | Manually specified via `Cookie:name=value` |
All session data is stored in **plain text JSON**. Anyone with file access can read credentials and cookies.
## Named Sessions
Named sessions are identified by a name string and scoped to a host:
```bash
# Create session "user1" for pie.dev
$ http --session=user1 -a user1:password pie.dev/get
# Create a different session for the same host
$ http --session=user2 -a user2:password pie.dev/get
# Reuse session "user1"
$ http --session=user1 pie.dev/get
```
### Storage Location
| Platform | Path |
|----------|------|
| Linux/macOS | `~/.config/httpie/sessions/<host>/<name>.json` |
| Windows | `%APPDATA%\httpie\sessions\<host>\<name>.json` |
## Anonymous Sessions
Instead of a name, specify a file path. This enables cross-host session reuse:
```bash
# Create an anonymous session
$ http --session=/tmp/session.json example.org
# Reuse it for a different host
$ http --session=/tmp/session.json admin.example.org
```
The path must contain at least one `/` (use `--session=./session.json`, not `--session=session.json`), otherwise HTTPie treats it as a named session.
You can also reference a previously created named session by its path:
```bash
$ http --session=~/.config/httpie/sessions/another.example.org/test.json example.org
```
## Read-Only Sessions
`--session-read-only` creates a session if it doesn't exist, but never updates it:
```bash
# Creates the session file
$ http --session-read-only=./ro-session.json pie.dev/headers Custom-Header:orig-value
# Does NOT update the session file
$ http --session-read-only=./ro-session.json pie.dev/headers Custom-Header:new-value
```
## Cookie Persistence
### Cookie Storage Priority
When multiple sources provide the same cookie, priority is:
1. **Response** (highest) — Cookies received via `Set-Cookie` header
2. **Command line** — Cookies specified via `Cookie:name=value`
3. **Session file** (lowest) — Pre-existing cookies in the session JSON
### Host-Based Cookie Policy
Cookies in session files have a `domain` field binding them to a host. A cookie with `"domain": "pie.dev"` is only sent to `pie.dev` and its subdomains.
Set `"domain": null` for unbound cookies that are sent to all hosts (including across redirect chains):
```json
{
"cookies": [
{
"domain": null,
"name": "unbound-cookie",
"value": "send-me-to-any-host"
}
]
}
```
### Cookie Expiration
- When the server expires a cookie, HTTPie removes it from the session file.
- When a cookie in a session file has expired, HTTPie removes it before sending the next request.
### Manual Cookie Format in Session File
```json
{
"cookies": {
"foo": {
"expires": null,
"path": "/",
"secure": false,
"value": "bar"
}
}
}
```
## Session Upgrade
HTTPie may change the session file format between versions. When an obsolete format is detected, HTTPie shows a warning.
### Upgrade All Sessions
```bash
$ httpie cli sessions upgrade-all
Upgraded 'api_auth' @ 'pie.dev' to v3.1.0
Upgraded 'login_cookies' @ 'httpie.io' to v3.1.0
```
### Upgrade a Single Named Session
```bash
$ httpie cli sessions upgrade pie.dev api_auth
Upgraded 'api_auth' @ 'pie.dev' to v3.1.0
```
### Upgrade an Anonymous Session
```bash
$ httpie cli sessions upgrade pie.dev ./session.json
Upgraded 'session.json' @ 'pie.dev' to v3.1.0
```
### `--bind-cookies`
Available for both `upgrade` and `upgrade-all`. Binds previously unbound cookies to the session's host:
```bash
$ httpie cli sessions upgrade pie.dev api_auth --bind-cookies
```
## Carapace Completion
The carapace completer currently completes `--session` and `--session-read-only` with `carapace.ActionFiles()` as a placeholder (session names are not yet dynamically completed). See `completers/common/http_completer/cmd/root.go:87-88`.
## References
- Source of truth: <https://httpie.io/docs/cli/sessions>
- Carapace completer: `completers/common/http_completer/cmd/root.go`
- Session config directory: see [config.md](config.md)
## Related Skills
- [auth.md](auth.md) — how auth credentials interact with sessions
- [config.md](config.md) — session storage directory location
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |