Cookies CLI

A browser-based cookie capture CLI tool for authenticated web sessions. This tool launches a browser window, lets you authenticate interactively, and captures all cookies for later use in automated requests.

Why This Tool?

The Problem with Browser Cookie Extraction

Traditional cookie extraction tools (like barnardb/cookies) work by extracting cookies directly from browser storage files. While this approach can work, it has significant limitations:

Challenges with Extraction-Based Tools:

1. OS Security Constraints: Modern operating systems (macOS, Windows, Linux) have strict security policies that limit access to browser data:

   • macOS Keychain protection prevents reading Chrome/Edge cookies without authorization
   • File permissions and encryption make Safari cookies difficult to access
   • Browser processes lock cookie databases while running

2. Browser-Specific Issues:

   • Chrome/Edge store cookies in SQLite databases that are encrypted
   • Firefox has its own cookie storage format and encryption
   • Safari uses plist files with restricted access
   • Each browser update can change the storage format

3. Unreliable Extraction:

   • Cookies may be encrypted and require OS-level decryption
   • Browser needs to be closed for reliable access
   • Race conditions when browser is running
   • Inconsistent results across different OS versions

Our Solution: Browser-Based Capture

Instead of trying to extract cookies from browser storage, cookies-cli launches a real browser instance and captures cookies during authentication:

Advantages:

1. Always Works: Uses Playwright to launch a real browser - no OS security constraints
2. Interactive Authentication: Handles complex authentication flows (SSO, 2FA, SAML, OAuth)
3. Fresh Cookies: Always gets current, valid session cookies
4. Browser Agnostic: Uses Chromium through Playwright - consistent across all platforms
5. Reliable: No race conditions or encryption issues

How It Works:

1. Launch Browser → 2. You Login → 3. Capture Cookies → 4. Save & Reuse

# Capture cookies by logging in through browser
$ cookies capture "https://example.com"

[1/4] Launching browser...
[2/4] Opening example.com...
[3/4] Waiting for authentication to complete...
      Browser window opened. Please complete SSO authentication.
✓ Captured 15 cookies

# Use captured cookies in automated requests
$ cookies fetch "https://example.com/api/data"
✓ Fetched 2.5 KB

Installation

# Clone the repository
git clone https://github.com/yourusername/cookies-cli.git
cd cookies-cli

# Install dependencies
npm install

# Build
npm run build

# Link for global use (optional)
npm link

Prerequisites

• Node.js 18 or higher
• Playwright (installed automatically with npm install)

Playwright will download Chromium browser automatically on first install. If you need to install browsers manually:

npx playwright install chromium

Usage

Capture Cookies

Launch a browser window and capture cookies after authentication:

cookies capture "https://example.com"

What happens:

1. Browser window opens to the URL
2. You complete authentication (login, SSO, 2FA, etc.)
3. Tool automatically detects when authentication completes
4. Cookies are captured and saved to ~/.cookies/auth-session-example.com.json

Test Cookies

Verify that captured cookies still work:

cookies test "https://example.com/dashboard"

Returns HTTP status code and indicates if authentication is still valid.

Fetch Content

Fetch content using saved cookies (auto-refreshes if expired):

cookies fetch "https://example.com/api/data"

Smart Auto-Refresh:

• Checks if cookies exist
• Tests if cookies still work
• Automatically recaptures if expired
• Fetches content with fresh cookies

Get Cookie Header

Get cookies in HTTP Cookie header format for use in other tools:

cookies get example.com
# Output: sessionid=abc123; token=xyz789

# Use with curl
curl -H "Cookie: $(cookies get example.com)" https://example.com/api/data

# Use with wget
wget --header="Cookie: $(cookies get example.com)" https://example.com/api/data

List Sessions

List all saved cookie sessions:

cookies list

Show Details

Show detailed information about cookies for a domain:

cookies show example.com

Delete Session

Delete saved cookies for a domain:

cookies delete example.com

Use Cases

API Testing

Capture cookies from web login and use in API testing:

# 1. Login through browser
cookies capture "https://api.example.com"

# 2. Test API endpoints with captured cookies
curl -H "Cookie: $(cookies get api.example.com)" \
  https://api.example.com/v1/users

# 3. Use in scripts
API_COOKIES=$(cookies get api.example.com)
for endpoint in users posts comments; do
  curl -H "Cookie: $API_COOKIES" \
    "https://api.example.com/v1/$endpoint"
done

Web Scraping

Authenticate once and reuse cookies for scraping:

# Capture authentication
cookies capture "https://members.example.com"

# Fetch multiple pages
for page in $(seq 1 10); do
  cookies fetch "https://members.example.com/content?page=$page" \
    > "page_$page.html"
done

CI/CD Integration

Use in continuous integration for testing authenticated endpoints:

#!/bin/bash
# ci-test.sh

# Capture cookies (if not exists or expired)
if ! cookies test "https://staging.example.com"; then
  cookies capture "https://staging.example.com"
fi

# Run tests with authenticated session
COOKIES=$(cookies get staging.example.com)
curl -H "Cookie: $COOKIES" https://staging.example.com/health | jq .

SSO/SAML/OAuth Applications

Perfect for applications with complex authentication flows:

# Works with:
# - SSO (Okta, Azure AD, Google Workspace)
# - SAML authentication
# - OAuth flows
# - 2FA/MFA
# - Any interactive browser authentication

cookies capture "https://sso-protected-app.example.com"

How Authentication Detection Works

The tool automatically detects when authentication completes by:

1. Monitoring URL changes
2. Detecting when you leave authentication pages (pages with /login, /auth, /sso, /oauth, /saml)
3. Waiting for page to stabilize (no redirects for 5 seconds)
4. Timeout after 90 seconds if no stable page detected

You can always proceed manually if auto-detection doesn't work - just complete authentication and the cookies will be captured.

Cookie Storage

Cookies are stored in ~/.cookies/ as JSON files:

~/.cookies/
  ├── auth-session-example.com.json
  ├── auth-session-api.example.com.json
  └── auth-session-app.example.com.json

Each file contains:

• URL and hostname
• All captured cookies
• Timestamp of capture
• Optional expiration info

Comparison: cookies-cli vs barnardb/cookies

Feature	cookies-cli (this tool)	barnardb/cookies
Method	Browser-based capture	Browser storage extraction
Reliability	✅ Always works	⚠️ OS/browser dependent
OS Security	✅ No constraints	❌ Keychain/permission issues
Browser Support	✅ Chromium (via Playwright)	⚠️ Chrome, Firefox, Safari (when unlocked)
Authentication	✅ Interactive (SSO, 2FA)	❌ Must login in actual browser first
Cookie Freshness	✅ Fresh on every capture	⚠️ May be stale/expired
Setup	✅ npm install	✅ Single binary
Platform	✅ Cross-platform (Node.js)	✅ macOS, Linux
Use Case	API testing, automation	Quick cookie export

When to use cookies-cli:

• You need reliable cookie capture across all platforms
• Your application uses SSO/SAML/OAuth authentication
• You want interactive authentication with 2FA/MFA support
• You need fresh cookies for automated testing
• You're building CI/CD pipelines requiring authentication

When to use barnardb/cookies:

• You need a quick one-time cookie export
• You're already logged in your browser
• You don't have Node.js installed
• You need a simple, single-binary tool

Security Considerations

• Cookie Storage: Cookies are stored unencrypted in ~/.cookies/. Ensure proper file system permissions.
• Cookie Lifetime: Captured cookies may have expiration times set by the server
• Session Security: Treat captured cookies like passwords - they provide full access to your account
• Auto-Cleanup: Consider deleting old sessions: cookies delete <domain>

Troubleshooting

Browser doesn't launch

Ensure Playwright browsers are installed:

npx playwright install chromium

Authentication timeout

If auto-detection fails after 90 seconds, the tool will proceed anyway. You can:

1. Check if cookies were still captured successfully with cookies list
2. Try again with a simpler URL (e.g., homepage instead of deep link)
3. Use cookies test to verify if cookies work

Cookies don't work after capture

Some possible reasons:

• Cookies expired (capture new ones)
• Session tied to IP address (capture from same network)
• Additional headers required (User-Agent, etc.)
• CSRF tokens needed (capture from the page that sets them)

Try:

# Recapture with fresh authentication
cookies capture "https://example.com"

# Test with full headers
curl -H "Cookie: $(cookies get example.com)" \
     -H "User-Agent: Mozilla/5.0" \
     https://example.com

Permission denied errors

Ensure ~/.cookies/ directory is writable:

mkdir -p ~/.cookies
chmod 700 ~/.cookies

Development

# Watch mode (auto-rebuild on changes)
npm run watch

# Build
npm run build

# Run without installing
node build/cookies-cli.js capture "https://example.com"

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT

Acknowledgments

• Inspired by barnardb/cookies for the problem space
• Built with Playwright for reliable browser automation