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

CODEBLOCK0

Automatic Session Management

If you don't specify --session-id:

1. 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:

CODEBLOCK1

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

Session Management Behavior

The CLI manages Scrapeless sessions with the following behavior:

• - Session Creation: First command creates a new Scrapeless session
• Session Persistence: Sessions remain active only while connection is maintained
• Session Termination: Sessions automatically terminate when connection closes
• Reconnection Limitation: Cannot reconnect to terminated sessions

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

Core Workflow

Every browser automation follows this pattern:

1. 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 INLINECODE4
4. Interact: Use refs to click, fill, select with INLINECODE5
5. Re-snapshot: After navigation or DOM changes, get fresh refs

CODEBLOCK2

Command Chaining

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

CODEBLOCK3

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 <id> parameter.

CODEBLOCK4

Session Creation with Advanced Options

The new-session command supports extensive customization options:

CODEBLOCK5

Available Options:

• - --name <name>: Session name for identification
• INLINECODE11: Session timeout in seconds (default: 180)
• INLINECODE12: Enable session recording
• INLINECODE13: Proxy country code (e.g., AU, US, GB, CN, JP)
• INLINECODE14: Proxy state/region (e.g., NSW, CA, NY, TX)
• INLINECODE15: Proxy city (e.g., sydney, newyork, london, tokyo)
• INLINECODE16: Custom user agent string
• INLINECODE17: Platform (Windows, macOS, Linux, iOS, Android)
• INLINECODE18: Screen width in pixels (default: 1920)
• INLINECODE19: Screen height in pixels (default: 1080)
• INLINECODE20: Timezone (default: America/New_York)
• INLINECODE21: Comma-separated language codes (default: en)

CODEBLOCK6
scrapeless-scraping-browser get url # Get current URL
scrapeless-scraping-browser get title # Get page title
scrapeless-scraping-browser screenshot # Take screenshot
scrapeless-scraping-browser screenshot --full # Full page screenshot

Wait

Cookies & Storage

## 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: