Session and Namespace Model

• --session / OPENSTEER_SESSION: logical session name (daemon routing is scoped by canonical cwd + logical session)
• --name / OPENSTEER_NAME: selector cache namespace (applies on open)

If --session is omitted:

• Interactive terminal: Opensteer creates/reuses a terminal-scoped default.
• Non-interactive mode: set OPENSTEER_SESSION or OPENSTEER_CLIENT_ID.

CWD-Scoped Routing

• Daemon reuse now requires both:
  • same logical session name, and
  • same canonical current working directory (realpath(cwd)).
• The same logical session name can be active in multiple directories on the same machine without collisions.

Step 1 — Set session and open the page.

export OPENSTEER_SESSION=my-session
opensteer open https://example.com --name "my-scraper"

The --name value is the cache namespace. It must match name: in the SDK constructor (Phase 2). Pick a stable name now and do not change it.

Step 2 — Snapshot and interact using counters.

Use snapshot action for interactions. Use snapshot extraction for data. Each element in the output has a counter (c="N"). Use that number directly.

opensteer snapshot action
opensteer click 3
opensteer input 5 "laptop" --pressEnter

Step 3 — Navigate and re-snapshot after every page change.

opensteer navigate https://example.com/results
opensteer snapshot action

Use opensteer open once at the start only. Use opensteer navigate for all subsequent pages — it includes a visual stability wait that open does not.

Step 4 — Cache every action and extraction with --description.

Re-run each action with --description added. This writes the resolved selector to the cache so scripts replay without counters.

opensteer click 3 --description "the products link"
opensteer input 5 "laptop" --pressEnter --description "the search input"

For data, the agent must define the extraction object from the snapshot.

• First run opensteer snapshot extraction and inspect the counters.
• Decide the exact JSON object the task needs.
• Treat the extraction snapshot as a planning aid only. It is trimmed/filtered, so do not read final values from the snapshot HTML itself.
• Build the full extract schema yourself so every leaf field is explicitly bound with { element: N }, { element: N, attribute: "..." }, or { source: "current_url" }.
• Always call extract to read the actual field values from the live page/runtime DOM.
• Use --description only to cache that extraction for replay. Do not rely on --description to tell Opensteer what data to collect.
• For arrays, include at least 2 representative items so Opensteer infers the repeating pattern.
• Do not replace extract with custom DOM parsing when the desired output can be expressed as a structured object.

opensteer snapshot extraction
# Decide the full output object first, then bind every leaf field explicitly
opensteer extract '{"images":[{"imageUrl":{"element":11,"attribute":"src"},"alt":{"element":11,"attribute":"alt"},"caption":{"element":14},"credit":{"element":15}},{"imageUrl":{"element":24,"attribute":"src"},"alt":{"element":24,"attribute":"alt"},"caption":{"element":27},"credit":{"element":28}}]}' \
  --description "article images with captions and credits"

Repeat Step 3 → Step 4 for every distinct page type the scraper will visit.

Step 5 — Close when done.

opensteer close

SDK Rule: Every browser action in a script MUST use an opensteer.* method.

---

Covered Features

• cli:open
• sdk:getNamespace

Related Docs

• CLI Sessions
• Resolution and Replay
• Selector Cache
• Snapshot Modes