Scrapeless Scraping Browser Skill

Cloud Browser Automation with scrapeless-browser

Important: Session Management with --session-id

All browser operation commands support the --session-id parameter to specify which Scrapeless session to use.

Recommended Workflow

# Step 1: Create a session and save the session ID
SESSION_ID=$(scrapeless-scraping-browser new-session --name "workflow" --ttl 1800 --json | jq -r '.taskId')
Step 2: Use the session ID for all operations
scrapeless-scraping-browser --session-id $SESSION_ID open https://example.com
scrapeless-scraping-browser --session-id $SESSION_ID snapshot -i
scrapeless-scraping-browser --session-id $SESSION_ID click @e1
Step 3: Close when done
scrapeless-scraping-browser --session-id $SESSION_ID close

Automatic Session Management

If you don't specify --session-id: 1. The CLI will query for running sessions 2. If a running session exists, it will use the latest one 3. If no running session exists, it will create a new one automatically

For production workflows, always use --session-id to ensure consistency.

Authentication Setup

Before using scrapeless-browser, you MUST set up authentication:

# Method 1: Config file (recommended, persistent)
scrapeless-scraping-browser config set apiKey your_api_token_here
Method 2: Environment variable
export SCRAPELESS_API_KEY=your_api_token_here
Verify it's set
scrapeless-scraping-browser config get apiKey

Get your API token from https://app.scrapeless.com

Session Management Behavior

The CLI manages Scrapeless sessions with the following behavior:

Important: For multi-step workflows, consider using the TypeScript API to maintain persistent connections.

Core Workflow

Every browser automation follows this pattern:

1. Create Session: Create a session and save the session ID 2. Navigate: Use --session-id to navigate to URL 3. Snapshot: Get element refs with --session-id 4. Interact: Use refs to click, fill, select with --session-id 5. Re-snapshot: After navigation or DOM changes, get fresh refs

# Set API token first
scrapeless-scraping-browser config set apiKey your_token
Create session
SESSION_ID=$(scrapeless-scraping-browser new-session --name "form-fill" --ttl 600 --json | jq -r '.taskId')
Start automation with session ID
scrapeless-scraping-browser --session-id $SESSION_ID open https://example.com/form
scrapeless-scraping-browser --session-id $SESSION_ID snapshot -i
Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
scrapeless-scraping-browser --session-id $SESSION_ID fill @e1 "user@example.com"
scrapeless-scraping-browser --session-id $SESSION_ID fill @e2 "password123"
scrapeless-scraping-browser --session-id $SESSION_ID click @e3
scrapeless-scraping-browser --session-id $SESSION_ID wait --load networkidle
scrapeless-scraping-browser --session-id $SESSION_ID snapshot -i  # Check result

Command Chaining

Commands can be chained with && in a single shell invocation:

# Chain open + wait + snapshot
scrapeless-scraping-browser open https://example.com && scrapeless-scraping-browser wait --load networkidle && scrapeless-scraping-browser snapshot -i
Chain multiple interactions
scrapeless-scraping-browser fill @e1 "user@example.com" && scrapeless-scraping-browser fill @e2 "password123" && scrapeless-scraping-browser click @e3

When to chain: Use && when you don't need to read intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs, then interact).

Essential Commands

Note: All commands below support the optional --session-id parameter.

# Navigation & Session
scrapeless-scraping-browser new-session [options]              # Create new browser session
scrapeless-scraping-browser [--session-id ] open       # Navigate to URL
scrapeless-scraping-browser [--session-id ] close           # Close browser session
scrapeless-scraping-browser sessions                           # List running sessions
scrapeless-scraping-browser stop                       # Stop specific session
scrapeless-scraping-browser stop-all                           # Stop all sessions

Session Creation with Advanced Options

The new-session command supports extensive customization options:

# Basic session creation
scrapeless-scraping-browser new-session --name "my-session" --ttl 1800
Session with proxy settings
scrapeless-scraping-browser new-session \
  --name "proxy-session" \
  --proxy-country US \
  --proxy-state CA \
  --proxy-city "Los Angeles" \
  --ttl 3600
Session with custom browser configuration
scrapeless-scraping-browser new-session \
  --name "mobile-session" \
  --platform iOS \
  --screen-width 375 \
  --screen-height 812 \
  --user-agent "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)" \
  --timezone "America/Los_Angeles" \
  --languages "en,es"
Session with recording enabled
scrapeless-scraping-browser new-session \
  --name "recorded-session" \
  --recording true \
  --ttl 7200

Available Options:

Snapshot
scrapeless-scraping-browser [--session-id ] snapshot -i             # Interactive elements with refs (recommended)
scrapeless-scraping-browser [--session-id ] snapshot -i -C          # Include cursor-interactive elements
scrapeless-scraping-browser [--session-id ] snapshot -s "#selector" # Scope to CSS selector
Interaction (use @refs from snapshot)
scrapeless-scraping-browser [--session-id ] click @e1               # Click element
scrapeless-scraping-browser [--session-id ] fill @e2 "text"         # Clear and type text
scrapeless-scraping-browser [--session-id ] type @e2 "text"         # Type without clearing
scrapeless-scraping-browser [--session-id ] press Enter             # Press key
scrapeless-scraping-browser [--session-id ] scroll down 500         # Scroll page
scrapeless-scraping-browser [--session-id ] scroll down 500 --selector "div.content"  # Scroll within element
Get information
scrapeless-scraping-browser [--session-id ] get text @e1            # Get element text
scrapeless-scraping-browser [--session-id ] get url                 # Get current URL
scrapeless-scraping-browser [--session-id ] get title               # Get page title
scrapeless-scraping-browser [--session-id ] screenshot              # Take screenshot
scrapeless-scraping-browser [--session-id ] screenshot --full       # Full page screenshot
Wait
scrapeless-scraping-browser [--session-id ] wait @e1                # Wait for element
scrapeless-scraping-browser [--session-id ] wait --load networkidle # Wait for network idle
scrapeless-scraping-browser [--session-id ] wait --url "**/page"    # Wait for URL pattern
scrapeless-scraping-browser [--session-id ] wait 2000               # Wait milliseconds
Cookies & Storage
scrapeless-scraping-browser [--session-id ] cookies                 # Get all cookies
scrapeless-scraping-browser [--session-id ] cookies set   # Set cookie
scrapeless-scraping-browser [--session-id ] cookies clear           # Clear cookies
scrapeless-scraping-browser [--session-id ] storage local           # Get localStorage
scrapeless-scraping-browser [--session-id ] storage local set    # Set localStorage
Multi-page
scrapeless-scraping-browser [--session-id ] pages                   # List all pages/tabs
scrapeless-scraping-browser [--session-id ] page            # Switch to page
scrapeless-scraping-browser [--session-id ] tab new [url]           # Open new tab
scrapeless-scraping-browser [--session-id ] tab close [n]           # Close tab
Live preview
scrapeless-scraping-browser live [taskId]                              # Get live preview URL

Common Patterns
Form Submission

Data Extraction

Common Session Configuration Scenarios
#### Mobile Device Simulation

#### Geographic Content Testing

#### High-Resolution Desktop Testing

#### Session Recording for Debugging

Session Persistence
Important: Scrapeless sessions terminate when connections close. For persistent workflows, use the TypeScript API:

Better Alternative: Use TypeScript API for multi-step workflows:

Using Proxies

Browser Fingerprinting

Session Recording

Multiple Sessions
Note: Due to session termination behavior, the --session-id parameter has limitations. For reliable multi-session workflows, create separate sessions for each task:

Alternative: For complex multi-session workflows, use the TypeScript API which supports persistent connections.
Configuration File
Configuration is managed via the config command. All settings are stored in ~/.scrapeless/config.json.
Priority: Config file > Environment variable (only SCRAPELESS_API_KEY supports env var)
Available configuration options:
apiKey - Your Scrapeless API token (required)
apiVersion - API version (v1 or v2, default: v2)
sessionTtl - Session timeout in seconds
sessionName - Session name for identification
sessionRecording - Enable session recording (true/false)
proxyUrl - Custom proxy URL
proxyCountry - Proxy country code
proxyState - Proxy state/province
proxyCity - Proxy city
fingerprint - Browser fingerprint
debug - Enable debug logging
Agent Mode (JSON Output)
Use --json for machine-readable output:

Ref Lifecycle (Important)
Refs (@e1, @e2, etc.) are invalidated when the page changes. Always re-snapshot after:
Clicking links or buttons that navigate
Form submissions
Dynamic content loading

Session Management
Important Session Behavior
Critical: Scrapeless sessions have specific connection requirements:
✅ Sessions work perfectly with persistent connections
❌ Sessions automatically terminate when the connection is closed
❌ Reconnecting to a terminated session will fail
Recommended Usage Patterns
#### For Single Operations

#### For Multi-Step Operations
For complex workflows requiring multiple steps, use the TypeScript API instead of CLI:

Session ID Parameter Limitations
The --session-id parameter has limitations due to Scrapeless session behavior:

Workaround: Create new sessions for each workflow instead of reusing session IDs.
Session Management Commands
Always close sessions when done to avoid leaked resources:

Check running sessions:

Live Preview
Get a real-time preview of your browser session via WebSocket:

Timeouts and Slow Pages
For slow websites, use explicit waits:

Error Handling
Common errors and solutions:
Authentication Error:

Session Not Found:

Element Not Found:

Timeout:

Debugging
Enable debug mode for detailed logs:

Or use --debug flag:

Configuration Options
| Configuration | Description |
|---------------|-------------|
| apiKey | Your API token (required) |
| apiVersion | API version (v1 or v2, default: v2) |
| sessionTtl | Session timeout in seconds |
| sessionName | Session name for identification |
| sessionRecording | Enable session recording (true/false) |
| proxyUrl | Custom proxy URL |
| proxyCountry | Proxy country code |
| proxyState | Proxy state/province |
| proxyCity | Proxy city |
| fingerprint | Browser fingerprint |
| userAgent | Custom user agent string |
| platform | Platform type (Windows, Linux, macOS, iOS, Android) |
| screenWidth | Screen width in pixels |
| screenHeight | Screen height in pixels |
| timezone | Timezone (e.g., America/New_York, Asia/Shanghai) |
| languages | Comma-separated language codes (e.g., en,zh-CN) |
| debug | Enable debug logging |
Set configuration using:

Or use environment variable for API key only:

Key Differences from Local Browsers
1. Cloud-based: Runs on Scrapeless infrastructure, not locally
2. Residential Proxies: Built-in support for residential proxy rotation
3. Anti-detection: Automatic browser fingerprinting and stealth features
4. Session Recording: Optional recording of browser sessions
5. No Installation: No need to install Chrome/Chromium locally
6. Scalable: Run multiple sessions in parallel
Limitations
Profile management is not currently supported
Browser extensions are not currently supported
Requires active internet connection
Requires valid Scrapeless API token
Best Practices
1. Always set API token before running commands (via config or env var)
2. Let automatic session management work - the CLI will reuse sessions intelligently
3. Use --session-id only when you need parallel workflows
4. Close sessions when done to avoid charges
5. Use config file for persistent settings instead of environment variables
6. Enable recording for debugging complex flows
7. Re-snapshot after page changes
8. Use --json for programmatic access
9. Set session timeout appropriately for your use case (in seconds)
Updates
Check for and install updates:

1. Always set API token before running commands (via config or env var) 2. Let automatic session management work - the CLI will reuse sessions intelligently 3. Use --session-id only when you need parallel workflows 4. Close sessions when done to avoid charges 5. Use config file for persistent settings instead of environment variables 6. Enable recording for debugging complex flows 7. Re-snapshot after page changes 8. Use --json for programmatic access 9. Set session timeout appropriately for your use case (in seconds)