Skip to content

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.md
index 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.md
index 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.com
curl '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.md
index 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 Alternative
pinchtab 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 Pages
diff --git a/docs/reference/eval.md b/docs/reference/eval.md
index 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 Alternative
pinchtab 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 Pages
diff --git a/docs/reference/fill.md b/docs/reference/fill.md
index 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 Alternative
pinchtab 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 Pages
diff --git a/docs/reference/focus.md b/docs/reference/focus.md
index 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 Alternative
pinchtab 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 Pages
diff --git a/docs/reference/frame.md b/docs/reference/frame.md
index 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.md
index 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 Alternative
pinchtab 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 Pages
diff --git a/docs/reference/navigate.md b/docs/reference/navigate.md
index 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.
```bash
curl -X POST http://localhost:9867/navigate \
@@ -8,18 +8,45 @@ curl -X POST http://localhost:9867/navigate \
-d '{"url":"https://pinchtab.com"}'
# CLI Alternative
pinchtab 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 Pages
diff --git a/docs/reference/pdf.md b/docs/reference/pdf.md
index 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 Pages
diff --git a/docs/reference/press.md b/docs/reference/press.md
index 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 Alternative
pinchtab 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.md
index 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 Alternative
pinchtab 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 text
4. 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:
```bash
pinchtab 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 Pages
diff --git a/docs/reference/snapshot.md b/docs/reference/snapshot.md
index 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
```bash
curl "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 Pages
diff --git a/docs/reference/tabs.md b/docs/reference/tabs.md
index 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.
```bash
curl 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.md
index 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 current
document. 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 extraction
pinchtab 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 id
pinchtab 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-heavy
pages such as dashboards, SERPs, grids, pricing tables, or short log panes that
Readability may trim away.
diff --git a/docs/reference/type.md b/docs/reference/type.md
index 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 Alternative
pinchtab 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