opensteer 0.8.13 → 0.8.14

package/skills/opensteer/references/cli-reference.md

@@ -1,261 +1,117 @@
 # Opensteer CLI Reference
 
-This covers DOM exploration and browser administration. For request capture workflows, see the [Request Workflow](request-workflow.md) reference.
-
-Use the CLI when you need a fast JSON-first loop against a repo-local workspace browser.
-
-## Sections
-
-- [Quickstart](#quickstart)
-- [Snapshot Output — What To Read](#snapshot-output--what-to-read)
-- [End-to-End Example](#end-to-end-example)
-- [Browser Lifecycle And Profile Cloning](#browser-lifecycle-and-profile-cloning)
-- [Browser Modes](#browser-modes)
-- [Advanced Semantic Operations](#advanced-semantic-operations)
-- [Extraction Schema And Array Auto-Generalization](#extraction-schema-and-array-auto-generalization)
+Use the CLI for fast exploration before writing SDK code.
 
 ## Quickstart
 
 ```bash
 opensteer open https://example.com --workspace demo
 opensteer snapshot action --workspace demo
-# Read the "html" field in the JSON output. Find elements by their c="N" attributes.
-# Example: <input c="5" placeholder="Search"> means element 5 is the search input.
-# Example: <button c="7">Search</button> means element 7 is the search button.
-
-# Act on elements AND persist their paths with human-readable descriptions
-opensteer run dom.input --workspace demo \
-  --input-json '{"target":{"kind":"element","element":5},"text":"search term","persistAsDescription":"search input"}'
-opensteer run dom.click --workspace demo \
-  --input-json '{"target":{"kind":"element","element":7},"persistAsDescription":"search button"}'
-
-# Re-snapshot after navigation, then persist an extraction descriptor
+opensteer input 5 laptop --workspace demo --persist "search input" --capture-network search
+opensteer click 7 --workspace demo --persist "search button" --capture-network search
 opensteer snapshot extraction --workspace demo
-opensteer extract --workspace demo \
-  --description "page summary" \
-  --schema-json '{"title":{"element":3},"url":{"source":"current_url"}}'
-
-# Replay later with just descriptions — no snapshot needed
-opensteer click --workspace demo --description "search button"
-opensteer extract --workspace demo --description "page summary"
+opensteer extract "search results" --workspace demo \
+  --schema '{"items":[{"name":{"element":13},"price":{"element":14}},{"name":{"element":22},"price":{"element":23}}]}'
 opensteer close --workspace demo
 ```
 
-- Stateful CLI commands currently require `--workspace <id>`.
-- Use `snapshot action` to discover page elements during exploration.
-- Use `opensteer run dom.*` with `persistAsDescription` to cache element paths under descriptions.
-- Replay cached actions with `--description` alone — no snapshot needed.
-- `extract --description --schema-json` writes a persisted extraction descriptor.
-- `extract --description` replays the stored extraction.
-- Persisted network history (`network.query`, `network.tag`, and `network.clear`) is SQLite-backed and initializes on first use.
-- Generic workspace and browser commands do not require SQLite capability unless they touch network history persistence.
+## What To Read From Snapshots
 
-## Snapshot Output — What To Read
+`snapshot action` and `snapshot extraction` return filtered HTML in the `html` field.
 
-`snapshot action` and `snapshot extraction` both return JSON:
+- Read the `html` string.
+- Find `c="N"` markers in that HTML.
+- Use those numbers as positional `element` ids in CLI commands and extraction schemas.
+- Re-snapshot after navigation before using new element numbers.
 
-```json
-{
-  "url": "https://example.com/search?q=airpods",
-  "title": "Search Results",
-  "mode": "extraction",
-  "html": "<span c=\"12\">$549.99</span>\n<a c=\"15\" href=\"/p/product-1\">\n  <div c=\"16\">Apple AirPods Max</div>\n</a>\n<a c=\"18\" href=\"/b/apple\">Apple</a>...",
-  "counters": [{"element":12,"tagName":"SPAN","pathHint":"span",...}, ...]
-}
-```
+## Core Commands
 
-**Read the `html` field.** It is a clean, filtered DOM. Hidden elements, scripts, and styles are already removed. Every element has a `c="N"` attribute.
-
-- `c="N"` in the HTML = `element: N` in commands and extraction schemas
-- `snapshot action` keeps interactive elements (buttons, inputs, links) for clicking/typing
-- `snapshot extraction` keeps all visible content (text, prices, titles) for data extraction
-- Do NOT parse the `counters` array to find elements — it is verbose metadata. Read the HTML string, find the `c="N"` values, and use those numbers.
-
-## End-to-End Example
-
-Goal: go to a site, search for a product, extract all results.
+### Session and Pages
 
 ```bash
-# 1. Open the page
 opensteer open https://example.com --workspace demo
-
-# 2. Snapshot to discover elements
+opensteer goto https://example.com/search --workspace demo --capture-network page-load
 opensteer snapshot action --workspace demo
-# Read html field. Find: <input c="5" placeholder="Search"> and <button c="7">Search</button>
-
-# 3. Type search term and persist the element path
-opensteer run dom.input --workspace demo \
-  --input-json '{"target":{"kind":"element","element":5},"text":"airpods","pressEnter":true,"persistAsDescription":"search input"}'
-
-# 4. Re-snapshot the results page (always re-snapshot after navigation!)
 opensteer snapshot extraction --workspace demo
-# Read html field. Find product items with their c="N" values:
-# <div c="13">Apple AirPods Max</div> <span c="14">$549.99</span>
-# <div c="22">Apple AirPods Pro</div> <span c="23">$249.99</span>
-
-# 5. Extract all results — array auto-generalizes from template rows
-opensteer extract --workspace demo \
-  --description "search results" \
-  --schema-json '{"items":[{"name":{"element":13},"price":{"element":14}},{"name":{"element":22},"price":{"element":23}}]}'
-# Returns ALL matching rows on the page, not just the 2 templates.
-
-# 6. Close
+opensteer tab list --workspace demo
+opensteer tab 2 --workspace demo
+opensteer tab close 2 --workspace demo
 opensteer close --workspace demo
 ```
 
-Total: 6 commands.
-
-## Browser Lifecycle And Profile Cloning
-
-```bash
-opensteer browser clone --workspace github-sync \
-  --source-user-data-dir "$HOME/Library/Application Support/Google/Chrome" \
-  --source-profile-directory Default
-opensteer open https://github.com --workspace github-sync
-opensteer browser status --workspace github-sync
-opensteer close --workspace github-sync
-opensteer browser reset --workspace github-sync
-opensteer browser delete --workspace github-sync
-```
-
-- `browser clone`, `browser reset`, and `browser delete` require a persistent workspace browser.
-- `browser clone` copies a local Chromium profile into `.opensteer/workspaces/<id>/browser/user-data`.
-- `close` stops the active session/browser but keeps the workspace registry, traces, artifacts, and cloned browser data.
-
-## Browser Modes
-
-- `persistent`: default with `--workspace`. Browser state lives in the workspace.
-- `temporary`: isolated browser state for the current run.
-- `attach`: connect to a running Chromium browser.
-
-```bash
-opensteer open https://example.com --workspace demo --browser temporary
-opensteer browser discover
-opensteer browser inspect --attach-endpoint ws://127.0.0.1:9222/devtools/browser/abc
-opensteer open https://example.com --workspace demo --browser attach --attach-endpoint ws://127.0.0.1:9222/devtools/browser/abc
-```
-
-Common options:
-
-- `--headless true|false`
-- `--executable-path <path>`
-- `--arg <value>` repeatable
-- `--timeout-ms <ms>`
-- `--context-json <json>`
-- `--fresh-tab true|false` for `--browser attach`
-
-## Advanced Semantic Operations
-
-The short CLI only special-cases a small set of commands. For advanced operations and fields not exposed by shorthand parsing, use:
+### DOM Actions
 
 ```bash
-opensteer run <semantic-operation> --workspace <id> --input-json <json>
-```
-
-Examples:
-
-```bash
-opensteer run dom.click --workspace demo \
-  --input-json '{"target":{"kind":"selector","selector":"button.primary"},"persistAsDescription":"primary button","captureNetwork":"load-products"}'
-
-opensteer run page.goto --workspace demo \
-  --input-json '{"url":"https://example.com/products","captureNetwork":"page-load"}'
-
-opensteer run network.query --workspace demo \
-  --input-json '{"capture":"load-products","includeBodies":true,"limit":20}'
-
-opensteer run request-plan.infer --workspace demo \
-  --input-json '{"recordId":"rec_123","key":"products.search","version":"v1"}'
-
-opensteer run request-plan.infer --workspace demo \
-  --input-json '{"recordId":"rec_123","key":"products.search.portable","version":"v1","transport":"direct-http"}'
-
-opensteer run request.execute --workspace demo \
-  --input-json '{"key":"products.search","query":{"q":"laptop"}}'
+opensteer click 7 --workspace demo --persist "primary button"
+opensteer hover 7 --workspace demo --persist "primary button"
+opensteer input 5 "search term" --workspace demo --persist "search input" --press-enter
+opensteer scroll down 400 --workspace demo
+opensteer scroll down 400 --workspace demo --element 12 --persist "results list"
+opensteer extract "page summary" --workspace demo --schema '{"title":{"element":3},"url":{"source":"current_url"}}'
 ```
 
-- Command aliases such as `network query` and `request-plan infer` still exist, but they usually depend on `--input-json` for nontrivial inputs.
-- Use `run page.goto` when you need `captureNetwork` on navigation. The short `goto` form only parses the URL positional.
-- Use `run dom.click` / `run dom.input` / `run dom.hover` / `run dom.scroll` when you need `persistAsDescription`.
-
-## Extraction Schema
-
-Always run `snapshot extraction` before building a schema — you need the `c="N"` counter values from the HTML.
+Rules:
 
-Schemas are **literal**: each `element` reference points to one specific DOM element, and you get back exactly the values you asked for. The schema is not a prompt or pattern — it is a precise specification.
+- `--persist` caches DOM action targets by name.
+- `extract <description>` uses `description` because extraction descriptors are named by description.
+- There is no CLI `--selector`, `--description` target flag, `--text`, or `--input-json`.
 
-Flat field bindings:
+### Network Discovery
 
 ```bash
-opensteer extract --workspace demo \
-  --description "page summary" \
-  --schema-json '{"title":{"element":3},"price":{"element":7}}'
-
-opensteer extract --workspace demo \
-  --description "links" \
-  --schema-json '{"url":{"selector":"a.primary","attribute":"href"},"pageUrl":{"source":"current_url"}}'
+opensteer network query --workspace demo --capture search
+opensteer network query --workspace demo --hostname api.example.com --limit 20
+opensteer network detail rec_123 --workspace demo
+opensteer replay rec_123 --workspace demo
+opensteer replay rec_123 --workspace demo --query keyword=headphones --query count=10
+opensteer fetch https://api.example.com/search --workspace demo --query keyword=laptop
 ```
 
-## Array Extraction (Two-Step Process)
+`network query` is intentionally short:
 
-Extracting lists of items (product rows, search results, etc.) is a two-step process:
+- one compact block per record
+- record id
+- method and status
+- resource type
+- URL
+- request and response body summaries when useful
 
-**Step 1 — Teach the pattern (schema + description):**
+Use `network detail` when you need headers, cookies sent, request body previews, response body previews, GraphQL metadata, or redirect chains.
 
-Provide 2 structurally similar rows as templates. The extractor returns exactly those rows (literal), but behind the scenes consolidates the templates into a generalized selector and saves it as a descriptor.
+### Browser State
 
 ```bash
-opensteer extract --workspace demo \
-  --description "product list" \
-  --schema-json '{"items":[{"name":{"element":13},"price":{"element":14}},{"name":{"element":22},"price":{"element":23}}]}'
-```
-
-Returns exactly 2 rows (the literal template values):
-```json
-{
-  "items": [
-    {"name": "Apple AirPods Max", "price": "$549.99"},
-    {"name": "Apple AirPods Pro", "price": "$249.99"}
-  ]
-}
+opensteer cookies --workspace demo
+opensteer cookies example.com --workspace demo
+opensteer storage example.com --workspace demo
+opensteer state example.com --workspace demo
 ```
 
-**Step 2 — Replay to get all rows (description only, no schema):**
+Use these when replay needs cookies, storage-backed tokens, hidden fields, or globals.
 
-Replay the saved descriptor. The generalized selector finds ALL matching rows on the page:
+### Browser Admin
 
 ```bash
-opensteer extract --workspace demo --description "product list"
-```
-
-Returns all matching rows:
-```json
-{
-  "items": [
-    {"name": "Apple AirPods Max", "price": "$549.99"},
-    {"name": "Apple AirPods Pro", "price": "$249.99"},
-    {"name": "Apple AirPods 4", "price": "$129.99"},
-    {"name": "Apple AirPods 4 (ANC)", "price": "$179.99"}
-  ]
-}
+opensteer browser status --workspace demo
+opensteer browser clone --workspace github-sync --source-user-data-dir "$HOME/Library/Application Support/Google/Chrome" --source-profile-directory Default
+opensteer browser reset --workspace github-sync
+opensteer browser delete --workspace github-sync
+opensteer record https://example.com --workspace demo
 ```
 
-This replay is deterministic and works across page updates, pagination, and different page states.
-
-Rules:
+## Recommended Exploration Loop
 
-- Build the exact JSON shape you want. The extractor does not accept `"string"` or prompt-style schemas.
-- Each leaf must be `{ element: N }`, `{ selector: "..." }`, optional `attribute`, or `{ source: "current_url" }`.
-- Use `element` fields during CLI exploration with a fresh snapshot. Deterministic scripts use `description`.
-- For arrays, provide 2 representative objects from different positions in the list. This gives the consolidator enough structural signal to generalize. Add more when rows have structural variants.
-- Nested arrays are not supported.
-- Do NOT expect the initial `extract --schema-json` call to return all rows. It returns exactly the template rows. Use description-only replay for the full list.
+1. `opensteer open`
+2. `opensteer goto ... --capture-network <label>` or a DOM action with `--capture-network`
+3. `opensteer network query`
+4. `opensteer network detail <recordId>`
+5. `opensteer replay <recordId>`
+6. `opensteer cookies` / `storage` / `state` if needed
+7. `opensteer close`
 
-## What NOT To Do
+## Common Mistakes
 
-- Do NOT use `page.evaluate()` to scrape DOM data. Use `extract()` with element-based schemas.
-- Do NOT parse the `counters` array to find elements. Read the `html` string and find `c="N"` values.
-- Do NOT use CSS selectors in reusable scripts. Use `description` from cached descriptors.
-- Do NOT write loops to enumerate list items. Use array extraction: provide 2 template rows in the schema, then replay with description only to get all rows.
-- Do NOT expect `extract --schema-json` with array templates to return all rows. It returns exactly the templates. Replay with `--description` alone for the full list.
-- Do NOT skip re-snapshot after navigation. Always re-snapshot before targeting new elements.
+- Starting API discovery with `snapshot` instead of `captureNetwork`.
+- Parsing the old `counters` metadata instead of reading the `html` string.
+- Trying to use removed surfaces such as `opensteer run`, `--input-json`, `--selector`, or `--description` target flags.
+- Forgetting to re-snapshot after navigation.