Clawbrowser – browser control via Playwright CLI

Setup & orientation

1. 1. Install the CLI and verify availability:

   npm install -g @playwright/cli@latest
   playwright-cli --help
   

1. 2. The CLI reads playwright-cli.json by default or whatever file you pass with --config. Use the config to tune browser name, launch/context options, viewport, timeouts, output directories, and recording settings without changing every command.
2. Keep playwright-cli --help terminal-accessible; the script self-documents the latest commands and options so you can refresh your memory before trying a new action.

Core interaction loop

1. 1. Start with playwright-cli open <url> to load the page (add --session=name if you want isolation up front).
2. Run playwright-cli snapshot to generate element refs (e1, e2, …) before any interaction. Always re-snapshot after DOM changes or navigation to avoid stale refs.
3. Use refs for actions:

1. 4. Capture output evidence with screenshot [ref], pdf, console [level], or network to prove the flow or inspect errors.
2. Example flow:

Sessions & persistence

• - Use --session=<name> to keep cookies, storage, and tabs isolated per workflow. Sessions behave like persistent profiles: they remember auth state, history, and tabs between commands.
• Export PLAYWRIGHT_CLI_SESSION=mysession if you are running many commands in the same session — the CLI will default to that session without needing --session each time.
• Manage sessions explicitly:

  playwright-cli session-list
  playwright-cli session-stop <name>
  playwright-cli session-stop-all
  playwright-cli session-restart <name>
  playwright-cli session-delete <name>
  

• - Use playwright-cli --isolated open ... for ephemeral contexts that do not persist to disk.
• Whenever you change browser settings for a session (launch args, headless toggle, browser selection), rerun playwright-cli config for that session and then session-restart to apply the new config.

Tabs, navigation, and devtools

• - Tab helpers: tab-list, tab-new [url], tab-close <index>, tab-select <index>.
• Navigation shortcuts: go-back, go-forward, reload.
• Keyboard and mouse control: press <key>, keydown, keyup, mousemove <x> <y>, mousedown [button], mouseup [button], mousewheel <dx> <dy>.
• Devtools-style introspection:

  playwright-cli console [level]
  playwright-cli network
  playwright-cli run-code "async page => await page.context().grantPermissions(['clipboard-read'])"
  

Recording, tracing, and exports

• - Record traces and videos around delicate interactions so you can replay what the agent did later:

  playwright-cli tracing-start
  # perform steps
  playwright-cli tracing-stop
  playwright-cli video-start
  # perform steps
  playwright-cli video-stop video.webm
  

• - Save evidence to disk with screenshot, pdf, or snapshot (which dumps element refs). Recorded files honor the outputDir from your config.

Config, state, and housekeeping

• - Use playwright-cli config to tweak runtime flags without reinstalling. Examples:

  playwright-cli config --headed --browser=firefox
  playwright-cli --session=auth config --config=playwright-cli.json
  

• - Running playwright-cli install refreshes browser binaries if the environment is new or you receive errors about missing binaries.
• Clean up sessions when finished to avoid stale state:

Troubleshooting & reminders

• - If a command fails, rerun playwright-cli snapshot to confirm refs are still valid. Snapshots provide the current DOM context for click/type operations.
• INLINECODE63 always shows the latest command set, so consult it before trying a rarely used flag.
• When the agent needs to replicate a recorded manual flow, capture a screenshot, note the session name, and mention which refs and tabs were in use.
• If targeting a visible browser is required (e.g., manual inspection), reconfigure with --headed, or run playwright-cli open --headed <url> for that session only.