High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: reference to match current CLI implementation
Luigi Agosticc273ee01dc2
diff --git a/docs/commands.md b/docs/commands.mdindex 71b834c2..fdf59996 100644--- a/docs/commands.md+++ b/docs/commands.md@@ -288,3 +288,20 @@ Commands with `--tab` currently include:- `dialog dismiss`- `console`- `errors`++## Output Format++Most commands output human-readable text by default. Use `--json` for machine-parseable JSON output:++```bash+pinchtab tab # Human-readable: *abc123 https://... Page Title+pinchtab tab --json # JSON: {"tabs":[...]}+pinchtab frame # Human-readable: main+pinchtab frame --json # JSON: {"tabId":"...","scoped":false,...}+pinchtab network # Human-readable: GET 200 https://...+pinchtab network --json # JSON: {"entries":[...],"count":5}+```++**For scripts and automation**: Always use `--json` when piping output or parsing programmatically. Human-readable formats may change between versions and are not guaranteed to be stable. The JSON schema is the stable contract.++Commands with `--json` include: `tab`, `frame`, `network`, `click`, `type`, `scroll`, `nav`, `back`, `forward`, `reload`, `wait`, `find`, `eval`, and most action commands.diff --git a/docs/reference/cli.md b/docs/reference/cli.mdindex 4d6756e6..b5e7992a 100644--- a/docs/reference/cli.md+++ b/docs/reference/cli.md@@ -68,6 +68,19 @@ PINCHTAB_AGENT_ID=agent-crawl-01 pinchtab nav https://pinchtab.comcurl 'http://127.0.0.1:9867/api/activity?agentId=agent-crawl-01'```+## Output Format++Most commands output human-readable text by default. Use `--json` for structured output:++```bash+pinchtab tab # *abc123 https://... Title+pinchtab tab --json # {"tabs":[...]}+pinchtab frame # main+pinchtab network # GET 200 https://...+```++**For scripts**: Always use `--json` when piping or parsing programmatically. Human-readable output may change between versions. JSON is the stable contract.+## Core Commands| Command | Purpose |diff --git a/docs/reference/click.md b/docs/reference/click.mdindex 57e4feb3..027b1249 100644--- a/docs/reference/click.md+++ b/docs/reference/click.md@@ -8,27 +8,45 @@ curl -X POST http://localhost:9867/action \-d '{"kind":"click","ref":"e5"}'# CLI Alternativepinchtab click e5-# Response-{- "success": true,- "result": {- "success": true- }-}+# Response (use --json for full JSON)+OK```-Notes:--- element refs come from `/snapshot`-- refs returned for iframe descendants can be clicked directly; no manual frame switch is required-- selector lookup is limited to the current frame scope; the default scope is `main`-- use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe actions-- missing selectors now fail immediately with `element not found: ...`; if you- want wait semantics for dynamic UI, use [`pinchtab wait`](./wait.md) or- `/wait` before the click-- the raw action endpoint also accepts `selector`, for example `{"kind":"click","selector":"#login"}`-- the CLI also accepts `#login`, `xpath://button`, `text:Submit`, and `find:login button`-- `--wait-nav` exists on the top-level CLI command+## CLI Flags++| Flag | Description |+|------|-------------|+| `--css` | CSS selector instead of ref |+| `--wait-nav` | Wait for navigation after click |+| `--snap` | Output interactive snapshot after click |+| `--snap-diff` | Output snapshot diff after click |+| `--text` | Output page text after click |+| `--dialog-action` | Auto-handle JS dialog: `accept` or `dismiss` |+| `--dialog-text` | Prompt response text (with `--dialog-action accept`) |+| `--x`, `--y` | Click at specific coordinates |+| `--json` | Full JSON response |+| `--tab` | Target specific tab |++## Examples++```bash+pinchtab click e5 # Click by ref+pinchtab click "#login" # Click by CSS+pinchtab click "text:Submit" # Click by text+pinchtab click e5 --snap # Click and show new snapshot+pinchtab click e5 --wait-nav # Click and wait for navigation+pinchtab click e5 --dialog-action accept # Auto-accept alert/confirm+pinchtab click --x 100 --y 200 # Click at coordinates+```++## Notes++- Element refs come from `/snapshot`+- Refs for iframe descendants can be clicked directly without frame switch+- Selector lookup is limited to current frame scope (default: `main`)+- Use [`/frame`](./frame.md) before selector-based iframe actions+- Missing selectors fail immediately; use [`pinchtab wait`](./wait.md) first for dynamic UI+- The API also accepts `selector` field: `{"kind":"click","selector":"#login"}`## Related Pagesdiff --git a/docs/reference/eval.md b/docs/reference/eval.mdindex 02a67ec7..e10c33e2 100644--- a/docs/reference/eval.md+++ b/docs/reference/eval.md@@ -10,19 +10,34 @@ curl -X POST http://localhost:9867/evaluate \-d '{"expression":"document.title"}'# CLI Alternativepinchtab eval "document.title"-# Response-{- "result": "Example Domain"-}+# Response (default is result value; use --json for full JSON)+Example Domain```-Notes:+## CLI Flags-- requires `security.allowEvaluate: true`-- the tab-scoped variant is `POST /tabs/{id}/evaluate`-- `/evaluate` is intentionally not frame-scoped-- current `/frame` state does not affect `pinchtab eval` or `/evaluate`-- if you need iframe access from `/evaluate`, your expression must handle that explicitly+| Flag | Description |+|------|-------------|+| `--await-promise` | Resolve returned Promise before responding |+| `--json` | Full JSON response |+| `--tab` | Target specific tab |++## Examples++```bash+pinchtab eval "document.title"+pinchtab eval "document.querySelectorAll('a').length"+pinchtab eval "fetch('/api/data').then(r => r.json())" --await-promise+pinchtab eval "document.title" --json # {"result":"Example Domain"}+```++## Notes++- Requires `security.allowEvaluate: true`+- Tab-scoped variant: `POST /tabs/{id}/evaluate`+- `/evaluate` is intentionally **not** frame-scoped+- Current `/frame` state does not affect `pinchtab eval`+- For iframe access, your expression must handle that explicitly## Related Pagesdiff --git a/docs/reference/fill.md b/docs/reference/fill.mdindex ef618c4f..c45fb7b9 100644--- a/docs/reference/fill.md+++ b/docs/reference/fill.md@@ -8,25 +8,37 @@ curl -X POST http://localhost:9867/action \-d '{"kind":"fill","ref":"e8","text":"[email protected]"}'# CLI Alternativepinchtab fill e8 "[email protected]"-# Response-{- "success": true,- "result": {- "success": true- }-}+# Response (use --json for full JSON)+OK```-Notes:+## CLI Flags-- the top-level CLI accepts unified selector forms such as `e8`, `#email`, or `text:Email`-- refs returned for iframe descendants can be filled directly; no manual frame switch is required-- selector lookup is limited to the current frame scope; the default scope is `main`-- use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe fills-- missing selectors now fail immediately with `element not found: ...`; use- [`pinchtab wait`](./wait.md) or `/wait` first when the field is expected to- appear asynchronously-- for the raw HTTP action endpoint, use `selector` for CSS, XPath, text, or semantic selectors+| Flag | Description |+|------|-------------|+| `--snap` | Output interactive snapshot after fill |+| `--snap-diff` | Output snapshot diff after fill |+| `--text` | Output page text after fill |+| `--json` | Full JSON response |+| `--tab` | Target specific tab |++## Examples++```bash+pinchtab fill e8 "[email protected]" # Fill by ref+pinchtab fill "#email" "[email protected]" # Fill by CSS+pinchtab fill "text:Email" "[email protected]" # Fill by text selector+pinchtab fill e8 "value" --snap # Fill and show snapshot+```++## Notes++- Accepts unified selectors: `e8`, `#email`, `xpath://...`, `text:Email`+- Refs for iframe descendants can be filled directly without frame switch+- Selector lookup is limited to current frame scope (default: `main`)+- Use [`/frame`](./frame.md) before selector-based iframe fills+- Missing selectors fail immediately; use [`pinchtab wait`](./wait.md) first for async fields+- For API, use `selector` field for CSS/XPath/text selectors## Related Pagesdiff --git a/docs/reference/focus.md b/docs/reference/focus.mdindex 68e34f8f..55cbc48e 100644--- a/docs/reference/focus.md+++ b/docs/reference/focus.md@@ -8,20 +8,23 @@ curl -X POST http://localhost:9867/action \-d '{"kind":"focus","ref":"e8"}'# CLI Alternativepinchtab focus e8-# Response-{- "success": true,- "result": {- "success": true- }-}+# Response (use --json for full JSON)+OK```+## CLI Flags++| Flag | Description |+|------|-------------|+| `--css` | CSS selector instead of ref |+| `--json` | Full JSON response |+| `--tab` | Target specific tab |+This is useful before keyboard-only flows such as `press Enter` or `type`.-The raw action endpoint accepts either `ref` or `selector`. The CLI accepts the same unified selector forms as other top-level action commands.+The CLI accepts unified selector forms: `e8`, `#input`, `xpath://input`, `text:Email`.-Selector lookup is limited to the current frame scope. The default scope is `main`; use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe focus calls.+Selector lookup is limited to current frame scope (default: `main`). Use [`/frame`](./frame.md) before iframe focus calls.## Related Pagesdiff --git a/docs/reference/frame.md b/docs/reference/frame.mdindex fcd84f7a..87e9daa7 100644--- a/docs/reference/frame.md+++ b/docs/reference/frame.md@@ -18,9 +18,10 @@ curl -X POST http://localhost:9867/frame \-d '{"target":"main"}'# CLI Alternative-pinchtab frame-pinchtab frame "#payment-frame"-pinchtab frame main+pinchtab frame # Shows: main (or frameId if scoped)+pinchtab frame "#payment-frame" # Shows: <frameId> (<name>)+pinchtab frame main # Shows: main+pinchtab frame --json # Full JSON response```Targets accepted by `POST /frame` and `pinchtab frame`:diff --git a/docs/reference/hover.md b/docs/reference/hover.mdindex f07b6c5d..533d39ea 100644--- a/docs/reference/hover.md+++ b/docs/reference/hover.md@@ -8,20 +8,24 @@ curl -X POST http://localhost:9867/action \-d '{"kind":"hover","ref":"e5"}'# CLI Alternativepinchtab hover e5-# Response-{- "success": true,- "result": {- "success": true- }-}+# Response (use --json for full JSON)+OK```Use this when menus or tooltips appear only after hover.-The raw action endpoint accepts either `ref` or `selector`. The CLI accepts unified selector forms such as `e5`, `#menu`, `xpath://button`, `text:Menu`, and `find:account menu`.+## CLI Flags-Selector lookup is limited to the current frame scope. The default scope is `main`; use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe hover calls.+| Flag | Description |+|------|-------------|+| `--css` | CSS selector instead of ref |+| `--x`, `--y` | Hover at specific coordinates |+| `--json` | Full JSON response |+| `--tab` | Target specific tab |++The CLI accepts unified selector forms: `e5`, `#menu`, `xpath://button`, `text:Menu`, `find:account menu`.++Selector lookup is limited to current frame scope (default: `main`). Use [`/frame`](./frame.md) before iframe hover calls.## Related Pagesdiff --git a/docs/reference/navigate.md b/docs/reference/navigate.mdindex ccc1451f..98f6bc90 100644--- a/docs/reference/navigate.md+++ b/docs/reference/navigate.md@@ -1,6 +1,6 @@# Navigate-Open a new tab and navigate it to a URL, or reuse a tab when a tab ID is provided through the API.+Open a new tab and navigate it to a URL, or reuse a tab when a tab ID is provided.```bashcurl -X POST http://localhost:9867/navigate \@@ -8,18 +8,45 @@ curl -X POST http://localhost:9867/navigate \-d '{"url":"https://pinchtab.com"}'# CLI Alternativepinchtab nav https://pinchtab.com-# Response-{- "tabId": "8f9c7d4e1234567890abcdef12345678",- "url": "https://pinchtab.com",- "title": "Example Domain"-}+# Response (default is tab ID; use --json for full JSON)+8f9c7d4e1234567890abcdef12345678```-Useful flags:+## CLI Flags-- CLI: `--new-tab`, `--block-images`, `--block-ads`-- API body: `tabId`, `newTab`, `timeout`, `blockImages`, `blockAds`, `waitFor`, `waitSelector`+| Flag | Description |+|------|-------------|+| `--tab` | Reuse existing tab |+| `--new-tab` | Force new tab |+| `--block-images` | Block image loading |+| `--block-ads` | Block ads |+| `--snap` | Output snapshot after navigation |+| `--snap-diff` | Output snapshot diff after navigation |+| `--print-tab-id` | Print only tab ID (auto when piped) |+| `--json` | Full JSON response |++## Examples++```bash+pinchtab nav https://example.com # Navigate, print tab ID+pinchtab nav https://example.com --snap # Navigate and snapshot+TAB=$(pinchtab nav https://example.com) # Capture tab ID for reuse+pinchtab nav https://other.com --tab "$TAB" # Reuse tab+pinchtab nav https://example.com --block-images # Skip images+```++## API Body Fields++| Field | Description |+|-------|-------------|+| `url` | Target URL (required) |+| `tabId` | Reuse existing tab |+| `newTab` | Force new tab |+| `blockImages` | Block image loading |+| `blockAds` | Block ads |+| `timeout` | Navigation timeout |+| `waitFor` | Wait condition |+| `waitSelector` | Wait for selector |## Related Pagesdiff --git a/docs/reference/pdf.md b/docs/reference/pdf.mdindex 187f9ecf..98c1c83b 100644--- a/docs/reference/pdf.md+++ b/docs/reference/pdf.md@@ -13,10 +13,34 @@ pinchtab pdf -o page.pdf}```-Useful flags:+## CLI Flags-- CLI: `-o`, `--tab`, `--landscape`, `--scale`-- API query: `output=file`, `raw`, `landscape`, `scale`, `paperWidth`, `paperHeight`+| Flag | Description |+|------|-------------|+| `-o`, `--output` | Save PDF to file path |+| `--landscape` | Landscape orientation |+| `--scale` | Page scale (e.g. 0.5) |+| `--paper-width` | Paper width (inches) |+| `--paper-height` | Paper height (inches) |+| `--page-ranges` | Page ranges (e.g. 1-3) |+| `--prefer-css-page-size` | Use CSS page size |+| `--display-header-footer` | Show header/footer |+| `--header-template` | Header HTML template |+| `--footer-template` | Footer HTML template |+| `--margin-*` | Margins (top, bottom, left, right) |+| `--generate-tagged-pdf` | Generate tagged PDF |+| `--generate-document-outline` | Generate document outline |+| `--tab` | Target specific tab |++## API Parameters++| Parameter | Description |+|-----------|-------------|+| `output` | `file` to save server-side |+| `raw` | `true` for raw PDF bytes |+| `landscape` | Landscape orientation |+| `scale` | Page scale |+| `paperWidth`, `paperHeight` | Paper dimensions |## Related Pagesdiff --git a/docs/reference/press.md b/docs/reference/press.mdindex d8f6faa1..5b26eebe 100644--- a/docs/reference/press.md+++ b/docs/reference/press.md@@ -8,18 +8,21 @@ curl -X POST http://localhost:9867/action \-d '{"kind":"press","key":"Enter"}'# CLI Alternativepinchtab press Enter-# Response-{- "success": true,- "result": {- "success": true- }-}+# Response (use --json for full JSON)+OK```-Common keys include `Enter`, `Tab`, and `Escape`.+## CLI Flags++| Flag | Description |+|------|-------------|+| `--json` | Full JSON response |+| `--tab` | Target specific tab |++Common keys include `Enter`, `Tab`, `Escape`, `ArrowDown`, `ArrowUp`, `Backspace`, `Delete`.## Related Pages- [Click](./click.md)- [Focus](./focus.md)+- [Keyboard](./keyboard.md)diff --git a/docs/reference/select.md b/docs/reference/select.mdindex 49b5c5f5..e5155eff 100644--- a/docs/reference/select.md+++ b/docs/reference/select.md@@ -8,15 +8,22 @@ curl -X POST http://localhost:9867/action \-d '{"kind":"select","ref":"e12","value":"it"}'# CLI Alternativepinchtab select e12 it-# Response-{- "success": true,- "result": {- "success": true- }-}+# Response (use --json for full JSON)+OK```+## CLI Flags++| Flag | Description |+|------|-------------|+| `--snap` | Output snapshot after select |+| `--snap-diff` | Output snapshot diff after select |+| `--text` | Output page text after select |+| `--json` | Full JSON response |+| `--tab` | Target specific tab |++## Option Matching+Matching is forgiving. PinchTab tries these strategies in order:1. exact `<option value="...">`@@ -24,7 +31,7 @@ Matching is forgiving. PinchTab tries these strategies in order:3. case-insensitive visible text4. case-insensitive substring of visible text-That means all of these can work depending on the page:+All of these can work depending on the page:```bashpinchtab select e12 uk@@ -33,11 +40,9 @@ pinchtab select e12 "united kingdom"pinchtab select e12 "Kingdom"```-Prefer the canonical option value or the full visible text when disambiguation-matters. The raw action endpoint accepts `ref` or `selector`, and the CLI-accepts the same unified selector forms as the other action commands.+Prefer the canonical option value or full visible text when disambiguation matters.-Selector lookup is limited to the current frame scope. The default scope is `main`; use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe selects.+Selector lookup is limited to current frame scope (default: `main`). Use [`/frame`](./frame.md) before iframe selects.## Related Pagesdiff --git a/docs/reference/snapshot.md b/docs/reference/snapshot.mdindex 4b869bec..70ff92e1 100644--- a/docs/reference/snapshot.md+++ b/docs/reference/snapshot.md@@ -8,27 +8,50 @@ Selector scoping is explicit. `selector=...` only searches the current frame sco```bashcurl "http://localhost:9867/snapshot?filter=interactive"-# CLI Alternative+# CLI Alternative (defaults to compact text output)pinchtab snap -i-# Response-{- "url": "https://pinchtab.com",- "title": "Example Domain",- "nodes": [- {- "ref": "e5",- "role": "link",- "name": "More information..."- }- ],- "count": 1-}+# Output+[e5] link "More information..."++# Use --full or --compact=false for JSON+pinchtab snap --full+```++## CLI Flags++| Flag | Description |+|------|-------------|+| `-i`, `--interactive` | Filter to interactive elements + headings (default: true) |+| `-c`, `--compact` | Compact text output (default: true) |+| `-d`, `--diff` | Show diff from previous snapshot |+| `--full` | Full JSON output (shorthand for `--interactive=false --compact=false`) |+| `--text` | Text output format |+| `-s`, `--selector` | CSS selector to scope snapshot |+| `--max-tokens` | Maximum token budget |+| `--depth` | Tree depth limit |+| `--tab` | Target specific tab |++## Examples++```bash+pinchtab snap # Interactive compact (default)+pinchtab snap -i -c # Same as above+pinchtab snap --full # Full JSON with all nodes+pinchtab snap -d # Show changes since last snapshot+pinchtab snap --selector "#main" # Scope to element+pinchtab snap --max-tokens 2000 # Limit output size```-Useful flags:+## API Parameters-- CLI: `-i`, `-c`, `-d`, `--selector`, `--max-tokens`, `--depth`-- API query: `filter`, `format`, `diff`, `selector`, `maxTokens`, `depth`+| Parameter | Description |+|-----------|-------------|+| `filter` | `interactive` for interactive + headings |+| `format` | `compact`, `text`, `yaml`, or default JSON |+| `diff` | `true` for diff mode |+| `selector` | CSS selector to scope |+| `maxTokens` | Token budget limit |+| `depth` | Tree depth limit |## Related Pagesdiff --git a/docs/reference/tabs.md b/docs/reference/tabs.mdindex bae65a53..af593958 100644--- a/docs/reference/tabs.md+++ b/docs/reference/tabs.md@@ -62,9 +62,7 @@ That command opens a tab for the instance and then navigates it.```bashcurl http://localhost:9867/tabs-# CLI Alternative-pinchtab tab-# Response+# Response (API always returns JSON){"tabs": [{@@ -75,6 +73,12 @@ pinchtab tab}]}++# CLI Alternative (human-readable by default)+pinchtab tab+# Output: *8f9c7d4e... https://pinchtab.com PinchTab++pinchtab tab --json # Full JSON response```Notes:diff --git a/docs/reference/text.md b/docs/reference/text.mdindex 9cf26adc..f7c5a6f0 100644--- a/docs/reference/text.md+++ b/docs/reference/text.md@@ -1,50 +1,88 @@# Text-Extract text from the current page.+Extract text from the current page or a specific element.By default, PinchTab runs a Readability-style extraction against the currentdocument. Use full/raw mode when you want `document.body.innerText` instead.+## Element Selection++Extract text from a specific element using a selector:++```bash+# Positional selector argument+pinchtab text "#article-body"+pinchtab text "text:Welcome"++# Or use --selector flag+pinchtab text --selector "#article-body"+pinchtab text -s "xpath://div[@class='content']"+```++Supported selector types: ref (`e5`), CSS (`#id`), XPath (`xpath://...`), text (`text:...`).++## Frame Scope+`/text` is frame-aware:-- `frameId=<id>` targets a specific iframe for a one-shot read+- `--frame <id>` or `frameId=<id>` targets a specific iframe for a one-shot read- otherwise, `/text` inherits the tab's current frame scope from [`/frame`](./frame.md)- if no frame is selected, `/text` reads from the top-level document-```bash-curl "http://localhost:9867/text?mode=raw"-# CLI Alternative-pinchtab text --raw-# Response-{- "url": "https://example.com",- "title": "Example Domain",- "text": "Example Domain\nThis domain is for use in illustrative examples in documents.",- "truncated": false-}-```+## Output Format-Useful flags:+Default output is human-readable text. Use `--json` for structured output:-- CLI: `--full`, `--raw`, `--frame <frameId>`-- API query: `mode=raw`, `maxChars`, `format=text`, `frameId=<frameId>`+```bash+pinchtab text # Plain text output+pinchtab text --json # JSON: {"url":"...","title":"...","text":"..."}+```-Examples:+## Examples```bash# Default Readability extractionpinchtab text-# Full page text (same behavior as --raw)+# Full page text (document.body.innerText)pinchtab text --full+pinchtab text --raw # Alias of --full++# Extract text from specific element+pinchtab text "#main-content"+pinchtab text --selector ".article-body"# One-shot iframe read by frame idpinchtab text --frame FRAME123-# HTTP form of the same idea+# API equivalent+curl "http://localhost:9867/text?mode=raw"+curl "http://localhost:9867/text?selector=%23article-body"curl "http://localhost:9867/text?frameId=FRAME123&format=text"```+## Flags++| Flag | Description |+|------|-------------|+| `--selector`, `-s` | Element selector (ref/CSS/XPath/text) |+| `--frame` | Extract from specific iframe by frameId |+| `--full` | Full page innerText instead of Readability |+| `--raw` | Alias for --full |+| `--json` | Output JSON instead of plain text |+| `--tab` | Target specific tab |++## API Parameters++| Parameter | Description |+|-----------|-------------|+| `selector` | Element selector for text extraction |+| `ref` | Snapshot ref (e.g., `e5`) |+| `frameId` | Target iframe ID |+| `mode` | `raw` for innerText, default for Readability |+| `maxChars` | Truncate output |+| `format` | `text` for plain text response |+Use default mode for article-like pages. Use `--full` / `mode=raw` for UI-heavypages such as dashboards, SERPs, grids, pricing tables, or short log panes thatReadability may trim away.diff --git a/docs/reference/type.md b/docs/reference/type.mdindex a817a199..ac56a76b 100644--- a/docs/reference/type.md+++ b/docs/reference/type.md@@ -8,25 +8,25 @@ curl -X POST http://localhost:9867/action \-d '{"kind":"type","ref":"e8","text":"Ada Lovelace"}'# CLI Alternativepinchtab type e8 "Ada Lovelace"-# Response-{- "success": true,- "result": {- "success": true- }-}+# Response (use --json for full JSON)+OK```-Notes:+## CLI Flags-- use `fill` when you want to set the value more directly-- the top-level CLI accepts unified selector forms such as `e8`, `#name`, `xpath://input`, or `text:Name`-- selector lookup is limited to the current frame scope; the default scope is `main`-- use [`/frame`](./frame.md) or `pinchtab frame` before selector-based iframe typing-- missing selectors now fail immediately with `element not found: ...`; use- [`pinchtab wait`](./wait.md) or `/wait` first when the field is expected to- appear asynchronously-- for typing without a target element (into whatever is focused), use `keyboard type`+| Flag | Description |+|------|-------------|+| `--json` | Full JSON response |+| `--tab` | Target specific tab |++## Notes++- Use `fill` when you want to set the value more directly+- Accepts unified selectors: `e8`, `#name`, `xpath://input`, `text:Name`+- Selector lookup is limited to current frame scope (default: `main`)+- Use [`/frame`](./frame.md) before iframe typing+- Missing selectors fail immediately; use [`pinchtab wait`](./wait.md) for async fields+- For typing into focused element, use `keyboard type`## Related Pages