Sessions & Cookies

Maintain login state across requests with persistent browser profiles and cookie injection. Scrape authenticated content, remember sessions between CLI calls, and programmatically save and restore cookies via the API.

Persistent Browser Profiles

The --profile flag saves the browser's cookies, storage, and session state under a named profile. Next time you use the same profile, you're already logged in.

Step 1: Log In and Save the Profile

# Open the login page with --headed so you can log in manually
webpeel "https://instagram.com/login" --profile instagram --render --headed

# Log in in the opened browser window, then close it (or press Ctrl+C)
# Cookies are automatically saved to the profile.

Step 2: Reuse the Profile

# Cookies are loaded automatically — no login required
webpeel "https://instagram.com/natgeo" --profile instagram --render

Profile Storage

Named profiles are stored in your home directory. You can also pass an absolute path to use a specific directory:

# Named profile (stored in ~/.webpeel/profiles/mysite/)
webpeel "https://example.com" --profile mysite --render

# Absolute path to an existing profile directory
webpeel "https://example.com" --profile /path/to/profile --render

Cookie Injection

Pass cookies directly on the command line without needing a saved profile. Useful for one-off authenticated requests or when you already have a cookie string.

# Single cookie
webpeel "https://example.com/dashboard" --cookie "session=abc123"

# Multiple cookies
webpeel "https://example.com/dashboard" \
  --cookie "session=abc123" \
  --cookie "auth=xyz789" \
  --cookie "csrf=tok123"

Cookie format: name=value. The same cookie format used in browser DevTools and curl's -b flag.

API: Session Cookie Management

When using stateful browser sessions via /v1/session, you can save and restore cookies programmatically — useful for caching authenticated sessions and avoiding repeated login flows.

Create a Session

curl -X POST "https://api.webpeel.dev/v1/session" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://instagram.com" }'

# Returns:
# { "id": "sess_abc123xyz", "status": "ready", ... }

Navigate and Log In

SESSION=sess_abc123xyz

# Navigate to login page
curl -X POST "https://api.webpeel.dev/v1/session/$SESSION/navigate" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://instagram.com/login" }'

# Fill username
curl -X POST "https://api.webpeel.dev/v1/session/$SESSION/act" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "action": "fill", "selector": "#username", "value": "myuser" }'

# Fill password and submit
curl -X POST "https://api.webpeel.dev/v1/session/$SESSION/act" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "action": "fill", "selector": "#password", "value": "mypass", "submit": true }'

Save Cookies

Export all cookies from the current session to save for later:

curl "https://api.webpeel.dev/v1/session/$SESSION/cookies" \
  -H "Authorization: Bearer wp_live_xxxx"

# Returns:
# {
#   "cookies": [
#     { "name": "sessionid", "value": "abc123", "domain": ".instagram.com", ... },
#     { "name": "csrftoken", "value": "xyz789", "domain": ".instagram.com", ... }
#   ]
# }

Restore Cookies

Inject saved cookies into a new session to skip the login flow:

# Create a new session
NEW_SESSION=$(curl -s -X POST "https://api.webpeel.dev/v1/session" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://instagram.com" }' | jq -r '.id')

# Restore saved cookies
curl -X POST "https://api.webpeel.dev/v1/session/$NEW_SESSION/cookies" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cookies": [
      { "name": "sessionid", "value": "abc123", "domain": ".instagram.com" },
      { "name": "csrftoken", "value": "xyz789", "domain": ".instagram.com" }
    ]
  }'

# Now navigate to authenticated content
curl -X POST "https://api.webpeel.dev/v1/session/$NEW_SESSION/navigate" \
  -H "Authorization: Bearer wp_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://instagram.com/natgeo" }'

CLI Reference

API Reference

Related

• /v1/session — Full browser session API: navigate, act, screenshot, and close
• Proxy Support — Route requests through HTTP, HTTPS, or SOCKS5 proxies
• CLI Reference — All CLI flags and options
• Fetch API — Single-request page fetching