From zero to bashing browsers

npm install -g browserbash-cli
browserbash --version

browserbash run "Open https://news.ycombinator.com and store the top story title as 'top_story'"

# no visible window, give up after 90 seconds
browserbash run "Open https://example.com and store the heading as 'h1'" --headless --timeout 90

# Option 1 — local and free (default): just have Ollama running
ollama pull qwen3
browserbash run "Open https://example.com and store the heading as 'h1'"

# Option 2 — Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
browserbash run "Open https://example.com and store the heading as 'h1'"

# Option 3 — OpenRouter: get a key at openrouter.ai/keys
export OPENROUTER_API_KEY=sk-or-...
browserbash run "..." --model openrouter/anthropic/claude-sonnet-4-6
browserbash run "..." --model openrouter/meta-llama/llama-3.3-70b-instruct

browserbash run "<objective>" --agent --headless --timeout 120

# progress events, one per step
{"type":"step","step":1,"status":"passed","action":"navigate","remark":"..."}

# terminal event
{"type":"run_end","status":"passed|failed|error|timeout","summary":"...","final_state":{...},"duration_ms":...,"test_url":"..."}

# exit codes: 0 passed · 1 failed · 2 error · 3 timeout

mkdir -p .browserbash/tests
cat > .browserbash/tests/login_test.md <<'EOF'
# Login flow

- Open {{base_url}}/login
- Type {{username}} into the email field
- Type {{password}} into the password field and press Enter
- Verify the dashboard heading is visible
- Store the logged-in user name as 'user_name'
EOF

browserbash testmd run .browserbash/tests/login_test.md
# -> writes .browserbash/tests/Result.md next to the test file

browserbash run "Log in to {{base_url}} as {{username}} with password {{password}}" \
  --variables '{"base_url":"https://app.example.com","username":"qa@example.com","password":{"value":"hunter2","secret":true}}'

# or keep them in a file
browserbash run "Log in to {{base_url}} as {{username}} with password {{password}}" \
  --variables-file ./staging.vars.json

# secret values never leak — logs show: Type ***** into the password field

# .github/workflows/e2e.yml
name: e2e
on: [push]
jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g browserbash-cli
      - run: browserbash testmd run .browserbash/tests/smoke_test.md --agent --headless --timeout 180
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
# exit code is the verdict: 0 passed · 1 failed · 2 error · 3 timeout

# record a run — screenshot + session video on any engine
browserbash run "Open https://example.com and store the heading as 'h1'" --record

# the recording is saved locally; see it with: browserbash dashboard

# free, local, no account — opens http://localhost:4477
browserbash dashboard

# run and pop the local dashboard open on this run
browserbash run "Open https://example.com and store the heading as 'h1'" --record --dashboard

# optional cloud: connect once, then push the runs you choose
browserbash connect --key bb_...      # key from browserbash.com/dashboard
browserbash run "..." --record --upload

# credentials: lambdatest.com -> Account Settings -> Password & Security
export LT_USERNAME=your_username
export LT_ACCESS_KEY=your_access_key
export ANTHROPIC_API_KEY=sk-ant-...        # cloud grids use the builtin (Anthropic) engine

# or store creds once instead of env vars:
browserbash login --provider lambdatest --username your_username --access-key your_access_key

browserbash run "Open https://www.saucedemo.com, log in as standard_user with password secret_sauce, and store the first product name as 'product'" \
  --provider lambdatest

# run ends with the session link:
#   test_url: https://automation.lambdatest.com/build
# -> open it: video replay, network log, console, and pass/fail status — recorded automatically

# credentials: browserstack.com -> Account & Profile -> Summary (Automate section)
export BROWSERSTACK_USERNAME=your_username
export BROWSERSTACK_ACCESS_KEY=your_access_key
export ANTHROPIC_API_KEY=sk-ant-...        # cloud grids use the builtin (Anthropic) engine

# or: browserbash login --provider browserstack --username ... --access-key ...

# single run on the grid
browserbash run "Open https://news.ycombinator.com and store the top story title as 'top_story'" \
  --provider browserstack

# whole markdown test file on the grid — same file, just add the flag
browserbash testmd run .browserbash/tests/login_test.md --provider browserstack

# test_url: https://automate.browserstack.com/dashboard
# -> video replay + logs per session, already marked passed/failed