browser-steel

# Browser Steel Use Steel CLI first. Use the Python runtime only when the workflow needs selector-heavy custom logic that is awkward to express through raw CLI steps. ## What `CLI` means here `CLI` means **Command Line Interface**. In this skill, it specifically means the Steel terminal commands themselves, for example: ```bash steel scrape https://example.com steel browser start --session demo steel browser open https://example.com --session demo steel browser snapshot -i --session demo ``` The wrapper script does not replace Steel CLI. It packages it into a more publishable, agent-friendly entrypoint: ```bash python3 {baseDir}/scripts/main.py scrape --url https://example.com python3 {baseDir}/scripts/main.py start-session --session demo python3 {baseDir}/scripts/main.py browser --session demo -- snapshot -i -c ``` So the relationship is: - **Steel CLI** = the underlying browser command system - **`scripts/main.py`** = the wrapper that calls Steel CLI by default - **Python runtime** = a fallback path for custom Playwright logic when CLI steps are not enough ## First checks 1. Run the doctor command before the first real task in a new environment: ```bash python3 {baseDir}/scripts/main.py doctor ``` 2. Prefer stateless commands for one-shot extraction or capture. 3. Prefer named sessions for multi-step interaction. 4. Keep the same `--session` value across every step in one workflow. 5. Never bake private cookies, profile names, or local paths into the skill itself. ## Runtime selection - `auto`: prefer installed `steel`, otherwise fall back to `npx @steel-dev/cli` - `cli`: same as `auto`, but fail if no CLI path is available - `node`: force the Node-distributed CLI path through `npx @steel-dev/cli` - `python`: use Steel SDK + Playwright through `run-python-plan` Read `references/runtime-modes.md` only when runtime choice or env resolution matters. Read `references/official-docs.md` when you need the authoritative Steel CLI or Playwright-Python upstream reference. ## Preferred commands ### Health check ```bash python3 {baseDir}/scripts/main.py doctor ``` ### Stateless commands ```bash python3 {baseDir}/scripts/main.py scrape --url https://example.com --format markdown --json python3 {baseDir}/scripts/main.py screenshot --url https://example.com --full-page --json python3 {baseDir}/scripts/main.py pdf --url https://example.com --json ``` ### Named-session workflow ```bash python3 {baseDir}/scripts/main.py start-session --session demo --stealth --json python3 {baseDir}/scripts/main.py browser --session demo -- open https://example.com python3 {baseDir}/scripts/main.py browser --session demo -- snapshot -i -c python3 {baseDir}/scripts/main.py browser --session demo -- fill @e2 "hello" python3 {baseDir}/scripts/main.py browser --session demo -- click @e5 python3 {baseDir}/scripts/main.py browser --session demo -- wait --load-state networkidle python3 {baseDir}/scripts/main.py stop-session --session demo --json ``` ### Python Playwright plan ```bash python3 {baseDir}/scripts/main.py run-python-plan \ --plan-file {baseDir}/references/example-plan.json \ --url https://example.com ``` Read `references/python-plan.md` only when the CLI path is insufficient. ## Guardrails - Start with `scrape`, `screenshot`, or `pdf` when the task is stateless. - For interactive workflows, follow `start-session -> browser commands -> stop-session`. - After any navigation or meaningful DOM change, take a fresh `snapshot -i` before using another `@eN` ref. - Keep secrets in env vars or an explicit `--env-file`, not in the skill files. - Pass cookies only through `--cookies-file` or `STEEL_BROWSER_COOKIES_FILE`. - Use the Python runtime only for tasks that genuinely benefit from custom Playwright logic. - Record confirmed improvements in `maintenance.log`. ## References - `references/official-docs.md` — upstream Steel CLI and Playwright-Python references - `references/runtime-modes.md` — runtime choice, env loading, and privacy rules - `references/cli-workflows.md` — reliable Steel CLI patterns - `references/python-plan.md` — JSON plan schema and supported actions - `references/troubleshooting.md` — install/auth/runtime recovery