CLI Recipes

Use copy-paste BotBrowser CLI recipes for proxy, fingerprint, identity, and deployment scenarios.

Prerequisites

BotBrowser binary installed on your system. See INSTALLATION.md for platform-specific setup.
A profile file (.enc for production, .json for local development). Download from GitHub Releases or use the profiles in profiles/ .

All recipes below use chromium-browser as the executable name. Replace with the correct path for your platform:

Windows: chrome.exe or full path to the extracted binary
macOS: /Applications/Chromium.app/Contents/MacOS/Chromium
Ubuntu: chromium-browser

Quick Start

1. Minimal launch

The simplest way to start BotBrowser with a profile:


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --user-data-dir="$(mktemp -d)"

2. Headless mode

Run without a visible browser window:


chromium-browser \
  --headless \
  --bot-profile="/path/to/profile.enc" \
  --user-data-dir="$(mktemp -d)"

3. Remote debugging

Expose the DevTools protocol for external tools to connect:


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --remote-debugging-port=9222 \
  --remote-debugging-address=0.0.0.0 \
  --user-data-dir="$(mktemp -d)"

How It Works

This guide is a command cookbook. Pick the recipe that matches your scenario, then combine only the flags you need.

Proxy Configurations

4. HTTP proxy with credentials


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --proxy-server=http://user:pass@proxy.example.com:8080 \
  --user-data-dir="$(mktemp -d)"

BotBrowser auto-detects timezone, locale, and language from the proxy exit IP.

5. SOCKS5 proxy


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --user-data-dir="$(mktemp -d)"

6. SOCKS5H proxy (DNS through tunnel)

Keep DNS resolution within the proxy tunnel for consistent privacy:


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --proxy-server=socks5h://user:pass@proxy.example.com:1080 \
  --user-data-dir="$(mktemp -d)"

7. Skip IP detection for faster navigation (ENT Tier1)

If you already know the proxy’s public IP, provide it to skip per-page IP lookups:


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --proxy-ip="203.0.113.1" \
  --user-data-dir="$(mktemp -d)"

8. Route static assets directly, proxy everything else (PRO)

Use regex patterns to control which requests go through the proxy:


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --proxy-server=http://user:pass@proxy.example.com:8080 \
  --proxy-bypass-rgx="\.(js|css|png|jpg|svg|woff2)(\?|$)" \
  --user-data-dir="$(mktemp -d)"

Timezone, Locale, and Language

9. Override timezone, locale, and language

By default, BotBrowser auto-detects these from the proxy IP. Override when you need a specific configuration:


chromium-browser \
  --bot-profile="/path/to/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,en \
  --user-data-dir="$(mktemp -d)"

10. Use the host system’s real timezone


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-config-timezone=real \
  --user-data-dir="$(mktemp -d)"

Noise Configuration

11. Deterministic noise with a fixed seed (ENT Tier2)

Produce identical fingerprint noise across runs using the same seed value:


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-noise-seed=12345 \
  --user-data-dir="$(mktemp -d)"

12. Disable specific noise channels

Turn off canvas noise while keeping other noise active:


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-config-noise-canvas=false \
  --bot-config-noise-webgl-image=true \
  --bot-config-noise-audio-context=true \
  --user-data-dir="$(mktemp -d)"

WebRTC Control

13. Disable WebRTC entirely

Prevent all WebRTC activity, including ICE candidate gathering:


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-config-webrtc=disabled \
  --user-data-dir="$(mktemp -d)"

14. Custom WebRTC ICE servers (ENT Tier1)

Control which STUN/TURN servers are visible to JavaScript:


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-webrtc-ice="custom:stun:stun.l.google.com:19302,turn:turn.example.com" \
  --user-data-dir="$(mktemp -d)"

Window and Screen Size

15. Custom window and screen dimensions


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-config-window=1920x1080 \
  --bot-config-screen=2560x1440 \
  --user-data-dir="$(mktemp -d)"

16. Force profile-defined dimensions in headful mode

Desktop profiles default to using real system dimensions in headful mode. To use the profile’s values instead:


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-config-window=profile \
  --bot-config-screen=profile \
  --user-data-dir="$(mktemp -d)"

Browser Brand Alignment

17. Present as Microsoft Edge (ENT Tier2)


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-config-browser-brand=edge \
  --bot-config-brand-full-version=142.0.3595.65 \
  --user-data-dir="$(mktemp -d)"

18. Android WebView simulation (ENT Tier3)


chromium-browser \
  --bot-profile="/path/to/android-profile.enc" \
  --user-agent="Mozilla/5.0 (Linux; Android {platform-version}; {model} Build/TP1A.220624.021; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/{ua-full-version} Mobile Safari/537.36" \
  --bot-config-browser-brand=webview \
  --bot-config-platform=Android \
  --bot-config-platform-version=13 \
  --bot-config-model=SM-G991B \
  --bot-config-mobile=true \
  --bot-config-architecture=arm \
  --bot-config-bitness=64 \
  --user-data-dir="$(mktemp -d)"

19. Pre-load cookies (PRO)


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-cookies='[{"name":"session","value":"abc123","domain":".example.com"}]' \
  --user-data-dir="$(mktemp -d)"

Or load from a file:


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-cookies="@/path/to/cookies.json" \
  --user-data-dir="$(mktemp -d)"

20. Pre-populate bookmarks and browsing history


# Random history (2-7 entries)
chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-bookmarks='[{"title":"Example","type":"url","url":"https://example.com"}]' \
  --bot-inject-random-history \
  --user-data-dir="$(mktemp -d)"
 
# Precise history count (15 entries, history.length = 16)
chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-inject-random-history=15 \
  --user-data-dir="$(mktemp -d)"

Performance Tuning

21. Performance timing and frame rate control (ENT Tier2)


chromium-browser \
  --bot-profile="/path/to/profile.enc" \
  --bot-time-scale=0.92 \
  --bot-time-seed=42 \
  --bot-fps=60 \
  --bot-stack-seed=profile \
  --user-data-dir="$(mktemp -d)"

22. Headless server with all protections

A production-ready configuration for server deployment:


chromium-browser \
  --headless \
  --no-sandbox \
  --bot-profile="/path/to/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-port-protection \
  --bot-always-active \
  --bot-disable-console-message \
  --remote-debugging-port=9222 \
  --user-data-dir="$(mktemp -d)"

23. Random profile selection from a directory

Select a different profile on each startup for fingerprint diversity:


chromium-browser \
  --bot-profile-dir="/path/to/profiles/directory/" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --user-data-dir="$(mktemp -d)"

Common Scenarios

Start from the Quick Start command and add only the cli recipes settings shown in this guide.
Re-run the same test page at least twice with the same profile to confirm stable output.
Keep proxy, locale/timezone, and launch args documented so this setup is reproducible.

Troubleshooting / FAQ

Problem	Solution
Flags have no effect	Ensure `--bot-config-*` flags use the correct format. Check for typos in flag names.
Proxy not working	Verify the full URL format: `scheme://user:pass@host:port`. Test the proxy independently first.
Timezone mismatch	Use `--bot-config-timezone` to override. Ensure the IANA timezone name is correct (e.g., `America/New_York`, not `EST`).
Window size ignored in headful	Desktop profiles default to `real` system dimensions. Set `--bot-config-window=profile` explicitly.
JSON parse errors in cookies/bookmarks	Ensure JSON is valid. On Windows CMD, use double quotes for the outer string and escape inner quotes.

Next Steps

CLI Flags Reference. Complete documentation for every available flag.
Profile Management. Understand profile types, versions, and configuration options.
Profile Configuration. Configure browser behavior via profile JSON.
Playwright Guide. Framework integration with Playwright.
Puppeteer Guide. Framework integration with Puppeteer.
First Verification. Verify your setup is working correctly.

Related documentation: Installation | CLI Flags Reference | Profile Configuration

Legal Disclaimer & Terms of Use • Responsible Use Guidelines . BotBrowser is for authorized fingerprint protection and privacy research only.