Cookies

Orb supports sending cookies with requests and saving cookies from responses using the Netscape cookie file format (compatible with cURL).

Sending Cookies

Inline Cookies

Use -b or --cookie to send cookies:

orb -b "session=abc123" https://example.com

Multiple cookies:

orb -b "session=abc123; user=alice" https://example.com

From a Cookie File

Prefix with @ to read from a file:

orb -b @cookies.txt https://example.com

The file should be in Netscape cookie format:

# Netscape HTTP Cookie File
.example.com  TRUE  /  FALSE  0  session  abc123
.example.com  TRUE  /api  TRUE  0  auth_token  xyz789

Saving Cookies

Use -c or --cookie-jar to save cookies from responses:

orb -c cookies.txt https://example.com/login -X POST -d "user=alice&pass=secret"

This creates or overwrites cookies.txt with cookies from Set-Cookie headers.

Cookie Jar Workflow

Combine -b and -c for a persistent cookie session:

# Login and save cookies
orb -c cookies.txt \
  https://example.com/login \
  -X POST \
  -d "username=alice&password=secret"

# Use saved cookies for subsequent requests
orb -b @cookies.txt -c cookies.txt \
  https://example.com/dashboard

# Logout and update cookie jar
orb -b @cookies.txt -c cookies.txt \
  https://example.com/logout \
  -X POST

Tip

Using both -b @file and -c file with the same file creates a session that persists cookies across requests.

Netscape Cookie Format

Each line (non-comment) has 7 tab-separated fields:

Field	Description
Domain	Cookie domain (.example.com for all subdomains)
Include Subdomains	TRUE if domain starts with .
Path	Cookie path (/, /api, etc.)
Secure	TRUE for HTTPS-only cookies
Expiry	Unix timestamp (0 = session cookie)
Name	Cookie name
Value	Cookie value

Example file:

# Netscape HTTP Cookie File
# This file was generated by orb
.github.com  TRUE  /  TRUE  0  _gh_sess  abc123...
.github.com  TRUE  /  FALSE  0  logged_in  yes
github.com  FALSE  /  TRUE  0  user_session  xyz789...

Cookie Matching Rules

When sending cookies, orb matches based on:

1. Domain: Cookie domain must match or be a suffix of the request domain

   • Cookie for .example.com matches api.example.com
   • Cookie for example.com only matches example.com

2. Path: Request path must start with cookie path

   • Cookie for /api matches /api/users
   • Cookie for /api does not match /other

3. Secure: Secure cookies only sent over HTTPS

Examples

Session-based API

# Authenticate and get session cookie
orb -c session.txt \
  -X POST \
  --json '{"username": "alice", "password": "secret"}' \
  https://api.example.com/auth/login

# Make authenticated requests
orb -b @session.txt \
  https://api.example.com/users/me

Web Scraping (Simplified)

# Get initial page (may set cookies)
orb -c cookies.txt https://example.com

# Submit form with cookies
orb -b @cookies.txt -c cookies.txt \
  -X POST \
  -d "query=search+term" \
  https://example.com/search

Debug Cookies

Use -v to see cookies being sent and received:

orb -v -b @cookies.txt https://example.com

Output includes:

> Cookie: session=abc123; user=alice
< Set-Cookie: updated_at=1704067200; Path=/