Chrome/Chromium Command-Line Flags for CDP Automation

The flags you'll actually use when launching a browser for programmatic control.

Chrome/Chromium has 1000+ command-line flags. Most are internal or experimental. This reference covers the ones relevant to CDP automation, testing, and a CDP-based tool.

Essential - Required for CDP

Flag	Description
`--remote-debugging-port=9222`	Starts the CDP WebSocket server on this port. Without this flag, CDP is unavailable. Port is your choice (9222 is convention).
`--user-data-dir=/path/to/profile`	Use a specific browser profile directory. Controls cookies, extensions, settings, localStorage. Use a temp dir for isolation, or a real profile to load extensions.

Headless Mode

Flag	Description
`--headless`	Run without a visible window (new headless mode since Chrome 112 - same rendering engine as headful). Good for CI.
`--headless=old`	Use the old headless implementation (separate renderer, less compatible). Rarely needed now.

New vs old headless: Since Chrome 112, --headless runs the same browser engine as the visible mode - full CSS, extensions, and rendering. The old headless was a separate implementation with subtle rendering differences. Always use the new mode unless you have a specific reason.

Startup Behaviour

Flag	Description
`--no-first-run`	Skip "Welcome to Chrome/Brave" first-run dialogs and setup.
`--no-default-browser-check`	Don't prompt to make this the default browser.
`--disable-default-apps`	Don't install default apps (Gmail, YouTube shortcuts, etc.) on first run.
`--disable-extensions`	Disable all extensions. Use when you want a clean environment without extension interference.
`--disable-component-extensions-with-background-pages`	Disable background pages for built-in component extensions (reduces noise).
`--disable-popup-blocking`	Allow popups (useful if your app uses `window.open()`).
`--start-maximized`	Start with the window maximized.
`--new-window`	Open a new window instead of a new tab in an existing instance.

Window & Display

Flag	Description
`--window-size=1920,1080`	Set the initial window size (width,height in pixels).
`--window-position=0,0`	Set the initial window position on screen.
`--force-device-scale-factor=2`	Force a specific device pixel ratio (e.g., 2 for Retina simulation).
`--hide-scrollbars`	Hide scrollbars (useful for consistent screenshots).

Security & Permissions

Flag	Description
`--disable-web-security`	Disable same-origin policy and CORS. Dangerous - only for testing. Lets your page make cross-origin requests freely.
`--allow-insecure-localhost`	Allow invalid/self-signed certificates on localhost. Useful for local dev servers with HTTPS.
`--ignore-certificate-errors`	Ignore all SSL certificate errors. Dangerous - only for testing against self-signed certs.
`--disable-features=IsolateOrigins,site-per-process`	Disable site isolation (can simplify iframe interaction in testing, but reduces security).
`--auto-accept-camera-and-microphone-capture`	Auto-grant camera/microphone permissions without prompting.
`--use-fake-ui-for-media-stream`	Use fake UI for camera/mic permission prompts (auto-accept).
`--use-fake-device-for-media-stream`	Use a fake camera/mic device (no real hardware needed).

Network

Flag	Description
`--proxy-server=http://host:port`	Route all traffic through a proxy.
`--proxy-bypass-list=localhost,127.0.0.1`	Bypass the proxy for specified hosts.
`--host-resolver-rules="MAP * 127.0.0.1"`	Override DNS resolution (map hostnames to specific IPs).
`--remote-debugging-address=0.0.0.0`	Allow remote CDP connections from other machines (default is localhost only). Security risk - only for trusted networks.

Performance & Resource Usage

Flag	Description
`--disable-gpu`	Disable GPU hardware acceleration. Useful in CI/Docker environments without GPU access.
`--disable-dev-shm-usage`	Write shared memory to /tmp instead of /dev/shm. Fixes crashes in Docker where /dev/shm is too small.
`--no-sandbox`	Disable the Chrome sandbox. Required when running as root in Docker, but a security risk otherwise.
`--disable-setuid-sandbox`	Disable setuid sandbox (less aggressive than --no-sandbox, sometimes sufficient).
`--single-process`	Run everything in one process (reduces memory in resource-constrained environments, but less stable).
`--disable-background-timer-throttling`	Don't throttle timers in background tabs. Important for testing - ensures setInterval/setTimeout run at full speed even when the tab isn't focused.
`--disable-backgrounding-occluded-windows`	Don't reduce priority for windows that are occluded (hidden behind other windows).
`--disable-renderer-backgrounding`	Don't reduce priority for renderer processes of background pages.

Automation-Specific

Flag	Description
`--enable-automation`	Enable automation mode (shows "Chrome is being controlled by automated test software" bar). Some sites detect this.
`--disable-blink-features=AutomationControlled`	Prevent `navigator.webdriver` from being set to `true`. Helps avoid bot detection.
`--disable-infobars`	Suppress all info bars (including the "controlled by automation" bar). Deprecated in newer Chrome versions.
`--disable-hang-monitor`	Disable the "Page unresponsive" dialog. Useful in automation where long scripts are expected.
`--disable-ipc-flooding-protection`	Disable throttling of IPC messages. Useful when sending many CDP commands rapidly.
`--password-store=basic`	Don't use the system keychain for passwords (avoids keychain prompts on macOS).
`--use-mock-keychain`	Use a mock keychain (macOS - avoids system keychain access prompts).

Testing & Debugging

Flag	Description
`--enable-logging=stderr`	Print Chrome's internal logs to stderr. Useful for debugging browser-level issues.
`--v=1`	Set verbose logging level (1 = verbose, 2 = very verbose).
`--disable-features=TranslateUI`	Disable the translation prompt bar (interferes with page layout during testing).
`--lang=en-US`	Force the browser language (consistent rendering in tests regardless of system locale).
`--font-render-hinting=none`	Disable font hinting (more consistent text rendering across platforms for screenshot comparison).

Recommended Combinations

Local development/debugging (visible browser)

/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser \
  --remote-debugging-port=9222 \
  --user-data-dir=/path/to/test-profile \
  --no-first-run \
  --no-default-browser-check \
  --disable-background-timer-throttling

CI/headless (Docker or GitHub Actions)

google-chrome \
  --headless \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-test \
  --no-first-run \
  --no-sandbox \
  --disable-gpu \
  --disable-dev-shm-usage \
  --disable-background-timer-throttling \
  --disable-backgrounding-occluded-windows \
  --disable-renderer-backgrounding \
  --window-size=1920,1080 \
  --hide-scrollbars

Testing with extensions loaded (Brave profile)

/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser \
  --remote-debugging-port=9222 \
  --user-data-dir="/path/to/your/brave-profile" \
  --no-first-run \
  --no-default-browser-check \
  --disable-background-timer-throttling \
  --disable-popup-blocking

Clean isolated run (no extensions, no history)

/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/cdp-clean-run \
  --no-first-run \
  --no-default-browser-check \
  --disable-extensions \
  --disable-default-apps \
  --disable-background-timer-throttling \
  --password-store=basic \
  --use-mock-keychain

Full list: For all 1000+ flags, see chrome-flags.com or the Chromium source (chrome_switches.cc). The flags above are the ones relevant to CDP automation.