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