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:

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:

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:

   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

python3 {baseDir}/scripts/main.py doctor

Stateless commands

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

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

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