Getting StartedMarch 10, 2026

Browser Automation CLI Recipes: Practical Command Examples

Copy-paste-ready CLI recipes for browser automation, from basic launches to multi-instance production setups with fingerprint profiles.

Introduction

BotBrowser's CLI flags provide fine-grained control over fingerprint profiles, proxy routing, locale settings, rendering configuration, and automation behavior. With dozens of flags available, knowing which ones to combine for specific scenarios saves significant setup time.

This article collects ready-to-use recipes for common use cases. Each recipe includes the exact command, an explanation of why each flag is included, and notes on when to use or modify it. All recipes assume you have a BotBrowser binary and .enc profile files from the GitHub releases.

Why CLI Recipes Matter

BotBrowser's configuration system is flexible by design. You can override almost any profile setting at runtime, route traffic through proxies with embedded credentials, control rendering behavior, and manage multiple instances from the command line. This flexibility means there are many valid configurations, and finding the right combination for your scenario can involve reading through the full CLI Flags Reference.

Recipes bridge the gap between understanding individual flags and putting them together effectively. They encode tested configurations that handle common edge cases, like ensuring each concurrent instance has its own user data directory, or pairing proxy settings with the correct locale overrides.

The configuration priority system makes CLI recipes especially powerful. CLI --bot-config-* flags have the highest priority, overriding profile settings without modifying the encrypted profile file. This means you can maintain a small set of base profiles and customize them at launch time for different scenarios.

Technical Background

Flag Categories

BotBrowser flags fall into several categories:

Core flags (--bot-profile, --bot-profile-dir) control which fingerprint profile to load. Every BotBrowser session starts with one of these.

Proxy flags (--proxy-server, --proxy-ip, --proxy-bypass-rgx) control network routing. BotBrowser extends the standard Chromium proxy flag to support embedded credentials in the URL.

Config override flags (--bot-config-*) override specific values from the loaded profile. Timezone, locale, languages, browser brand, screen dimensions, and rendering settings are all configurable.

Behavior toggles (--bot-disable-debugger, --bot-always-active, --bot-inject-random-history, etc.) control runtime behavior that is not tied to a specific profile value.

Customization flags (--bot-title, --bot-cookies, --bot-bookmarks, --bot-script) add session-specific data or automation scripts.

Auto-Detection

BotBrowser automatically derives timezone, locale, and language settings from your proxy IP. In most recipes, you do not need to specify these values manually. Override only when you need a configuration that differs from what the IP suggests.

Standard Chromium Flags

BotBrowser also supports all standard Chromium flags. Common ones include --headless, ``--user-data-dir, --remote-debugging-port, and --window-size`. These are documented in the Chromium command line reference.

Recipes

Recipe 1: Minimal Launch

The simplest possible BotBrowser configuration:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --headless

This loads the profile and runs headless. Timezone, locale, and languages are auto-detected from your machine's IP. Use this for local testing and development.

Recipe 2: Production Launch with Proxy

chromium-browser \
  --bot-profile="/opt/profiles/windows-chrome-131.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --user-data-dir="/tmp/bb-session-$(date +%s)" \
  --remote-debugging-port=9222 \
  --headless

The proxy handles geo-routing while BotBrowser auto-derives timezone and locale from the proxy's egress IP. A unique --user-data-dir prevents conflicts with other instances. The debugging port enables programmatic control via CDP.

Recipe 3: Explicit Locale and Timezone

When you need specific regional settings regardless of your proxy location:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-config-timezone="Europe/Berlin" \
  --bot-config-locale="de-DE" \
  --bot-config-languages="de-DE,de,en-US" \
  --bot-config-location="52.5200,13.4050" \
  --headless

This overrides the auto-detected values with explicit German configuration. Useful when your proxy IP does not accurately reflect the desired region.

Recipe 4: Multi-Instance Deployment

#!/bin/bash
PROFILES_DIR="/opt/profiles/windows-chrome"
BASE_PORT=9222

for i in $(seq 1 5); do
  chromium-browser \
    --bot-profile-dir="${PROFILES_DIR}" \
    --bot-title="Worker ${i}" \
    --user-data-dir="/tmp/bb-worker-${i}" \
    --remote-debugging-port=$((BASE_PORT + i)) \
    --proxy-server=socks5://user:pass@proxy.example.com:1080 \
    --headless &
done

Each instance gets a random profile from the directory, its own user data directory, a unique debugging port, and a descriptive title for identification. The --bot-title appears in the window title and taskbar, making it easy to identify specific instances.

Recipe 5: Browser Brand Switching

Present as Microsoft Edge instead of Chrome:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-config-browser-brand="edge" \
  --headless

Available brand values: chrome, chromium, edge, brave, opera, webview. BotBrowser adjusts the User-Agent, Client Hints headers, and related API values to match the selected brand.

Recipe 6: Session with Cookies and History

Pre-populate the browser with session data:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-cookies='[{"name":"session_id","value":"abc123","domain":".example.com"},{"name":"pref","value":"dark","domain":".example.com"}]' \
  --bot-bookmarks='[{"title":"Dashboard","type":"url","url":"https://example.com/dashboard"}]' \
  --bot-inject-random-history \
  --bot-always-active \
  --user-data-dir="/data/persistent-session" \
  --headless

--bot-cookies sets initial cookies. --bot-bookmarks adds bookmark entries. --bot-inject-random-history creates synthetic browsing history for session authenticity. --bot-always-active keeps windows active even when unfocused.

For large cookie sets, load from a JSON file:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-cookies="@/opt/data/cookies.json" \
  --headless

The @ prefix tells BotBrowser to read cookies from the specified file path instead of parsing the value as inline JSON.

Recipe 8: Deterministic Noise for Reproducibility

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-noise-seed=42 \
  --bot-time-seed=42 \
  --bot-time-scale=0.92 \
  --headless

--bot-noise-seed makes Canvas, WebGL, audio, text metrics, and ClientRect noise deterministic. The same seed produces the same fingerprint hash every time. --bot-time-seed provides deterministic execution timing diversity across browser operations. --bot-time-scale compresses performance.now() intervals to reduce timing-based tracking signals.

Recipe 9: Canvas Recording for Analysis

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-canvas-record-file="/tmp/canvas-capture.jsonl" \
  --bot-noise-seed=12345 \
  --headless

Records all Canvas 2D, WebGL, and WebGL2 API calls to a JSONL file. The noise seed is fixed so recorded output is reproducible. Use this for forensic analysis and debugging of Canvas-related fingerprint behavior.

Recipe 10: Framework-Less Automation

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-script="/opt/scripts/automation.js" \
  --bot-disable-debugger \
  --bot-disable-console-message \
  --headless

Runs a JavaScript file with direct chrome.debugger CDP access. No Node.js or npm required. --bot-disable-debugger prevents pages from pausing execution with debugger statements. --bot-disable-console-message suppresses console output from being exposed through CDP.

Recipe 11: Headless with Specific Window Size

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-config-window="1920x1080" \
  --bot-config-screen="2560x1440" \
  --window-size=1920,1080 \
  --headless

Sets both the profile-level window/screen dimensions and the Chromium window size. The --bot-config-window and --bot-config-screen flags control what JavaScript APIs report, while --window-size sets the actual viewport.

Recipe 12: WebRTC Privacy with Custom STUN

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-webrtc-ice="google" \
  --bot-local-dns \
  --headless

--bot-webrtc-ice controls what STUN/TURN endpoints are exposed through WebRTC, preventing local IP leakage. --bot-local-dns keeps DNS resolution local instead of relying on the proxy provider's DNS.

Recipe 13: Custom HTTP Headers

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-custom-headers='{"X-Requested-With":"com.example.app","X-Custom-Auth":"token123"}' \
  --headless

Injects custom headers into all outgoing HTTP requests. Useful for API authentication and request routing.

Recipe 14: Port Protection

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-port-protection \
  --headless

Prevents remote pages from detecting which services are running on localhost by blocking port scanning across common development and remote access ports.

Recipe 15: Debug and Troubleshooting

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-internal --v=1 \
  --enable-logging=stderr \
  --headless

Enables BotBrowser's internal logging (--bot-internal --v=1) and Chromium's stderr logging for detailed diagnostic output. Use this when troubleshooting configuration issues.

Verification

After applying any recipe, verify the result by navigating to a fingerprint testing tool:

# Quick verification with a test URL
chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-noise-seed=42 \
  --remote-debugging-port=9222 \
  --headless

Then connect via CDP and navigate to CreepJS or Pixelscan to confirm your configuration produces a consistent, realistic fingerprint. See How to Verify Your Browser Fingerprint Protection for detailed testing methodology.

Best Practices

Start minimal, add flags as needed. Begin with Recipe 1 and add flags only when you have a specific requirement. Unnecessary flags add complexity without benefit.

Let auto-detection work. If you are using a proxy, BotBrowser handles timezone, locale, and language automatically. Override only when the auto-detected values do not match your needs.

Use --user-data-dir for every concurrent instance. Without separate data directories, instances share cookies, cache, and profile data, causing unpredictable behavior.

Use --bot-title for identification. When running multiple instances, the title makes it easy to identify which instance is which in logs and process listings.

Prefer --bot-config-* over profile editing. CLI flags have the highest priority and do not require modifying encrypted files.

Log everything in development. Use --bot-internal --v=1 during development and testing. Disable verbose logging in production for performance.

For deeper dives into specific topics, see Profile Management for organizing profiles, Headless Server Setup for Ubuntu server configuration, Docker Deployment Guide for containerized deployments, and Bot Script Automation for framework-less automation.

#cli#recipes#flags#configuration#getting-started