Auto-generated by
tap docs. Regenerate withmise run docs.
Tap runs site-specific JS scripts against websites and extracts clean content from URLs. Scripts execute in QuickJS (fast, no browser) with automatic fallback to a real Chrome browser when auth or JS rendering is needed.
Quick start: tap site list List available site scripts tap site hackernews/top Run a site script tap fetch https://example.com Extract clean readable content tap attach chrome Reuse your existing Chrome tap browser open https://example.com Open a page in the default browser context tap browser open https://github.com/login --show tap status Show the active browser context + current tab
Use 'tap --help' for details on any command.
| Flag | Description | Default | Env |
|---|---|---|---|
--sites-dir |
Directory containing site scripts | ~/.cache/tap/sites | TAP_SITES_DIR |
--verbose |
Enable verbose logging | ||
--quiet, -q |
Suppress all log output | ||
--local-only |
Only use scripts from local override dir (~/.config/tap/sites/), skip cache | ||
--no-color |
Disable colored output | NO_COLOR |
Usage: Run site scripts
tap site <script-name> [key=value ...]
Run site-specific JavaScript scripts that extract structured data from websites.
Scripts are organized as site/action (e.g. hackernews/top, google/search) and execute in QuickJS with automatic browser fallback when cookies or DOM are needed.
Scripts auto-sync from the remote catalog every 24 hours into ~/.cache/tap/sites/. Local overrides in ~/.config/tap/sites/ take precedence over cached scripts.
Examples: tap site list List all available scripts tap site hackernews/search query=golang Run a script with arguments tap site -b twitter/search query=go Run with browser cookies (auth) tap site info hackernews/search Show script details and args tap site search "weather" Search the online catalog tap site sync Force-refresh the script cache tap site hackernews/top -f json Output as JSON
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--format, -f |
Output format: json, pretty (default), raw | pretty | |
--browser, -b |
Use the browser path and reuse the resolved browser context | ||
--show, --no-headless |
Run the browser visibly | ||
--wait, --delay |
Wait a fixed duration after navigation before continuing | ||
--wait-selector |
Wait until a CSS selector becomes visible before continuing | ||
--wait-js |
Wait until a JavaScript expression becomes truthy before continuing | ||
--timeout, -t |
Execution timeout; 0 means no timeout | ||
--browser-url, --ws-url, --devtools-url |
One-shot DevTools endpoint override | ||
--profile-dir |
One-shot browser profile override | ||
--lightpanda, --lp |
Use Lightpanda instead of Chrome (implies --browser) |
Usage: Run a site script
tap site run <script-name> [key=value ...]
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--format, -f |
Output format: json, pretty (default), raw | pretty | |
--browser, -b |
Use the browser path and reuse the resolved browser context | ||
--show, --no-headless |
Run the browser visibly | ||
--wait, --delay |
Wait a fixed duration after navigation before continuing | ||
--wait-selector |
Wait until a CSS selector becomes visible before continuing | ||
--wait-js |
Wait until a JavaScript expression becomes truthy before continuing | ||
--timeout, -t |
Execution timeout; 0 means no timeout | ||
--browser-url, --ws-url, --devtools-url |
One-shot DevTools endpoint override | ||
--profile-dir |
One-shot browser profile override | ||
--lightpanda, --lp |
Use Lightpanda instead of Chrome (implies --browser) |
Usage: List all available scripts (grouped by site)
Usage: Show detailed info for a script
tap site info <script-name>
Usage: Search scripts online by name or description
tap site search <query>
Usage: Sync scripts from the remote catalog
Usage: Fetch and extract clean content from a URL
tap fetch <url>
Fetch a URL and extract the main content as clean Markdown, stripping ads, navigation, scripts, and boilerplate via go-defuddle.
Examples: tap fetch https://example.com/article Clean Markdown output tap fetch --json https://example.com/article Full metadata as JSON tap fetch -b https://example.com Use browser for JS-rendered pages tap fetch --lp https://example.com Use Lightpanda (fast headless, no auth)
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--json |
Output as JSON with full metadata | ||
--browser, -b |
Use the browser path and reuse the resolved browser context | ||
--show, --no-headless |
Run the browser visibly | ||
--wait, --delay |
Wait a fixed duration after navigation before continuing | ||
--wait-selector |
Wait until a CSS selector becomes visible before continuing | ||
--wait-js |
Wait until a JavaScript expression becomes truthy before continuing | ||
--timeout, -t |
Execution timeout; 0 means no timeout | ||
--browser-url, --ws-url, --devtools-url |
One-shot DevTools endpoint override | ||
--profile-dir |
One-shot browser profile override | ||
--lightpanda, --lp |
Use Lightpanda instead of Chrome (implies --browser) |
Usage: Browser automation and page interaction
Open pages, interact with elements, and extract content from websites.
Quick start: tap browser open Open or navigate to a URL tap browser tabs List open tabs tap browser switch Switch to a different tab tap browser click "#submit" Click an element tap browser text Extract readable page content tap browser screenshot Capture the current page tap browser snapshot --interactive Map interactive elements to @eN refs tap browser click @e3 Act on a ref from the snapshot
For authenticated access: tap attach chrome Attach your existing Chrome tap browser open https://example.com/login --show
Default behavior:
- Uses the default browser context (managed or attached)
- Operates on the current tab (created automatically if needed)
- Use --new-tab to open in a new tab instead of navigating current
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--state-root |
Durable state directory for browser sessions and tabs | TAP_BROWSER_STATE_DIR |
Usage: Open or navigate to a URL in the current browser context
tap browser open <url>
Open a URL in the default browser context.
If no current tab exists, creates one. If a current tab exists, navigates it. Use --new-tab to force creation of a new tab.
Examples: tap browser open https://example.com tap browser open https://github.com --new-tab tap browser open https://example.com --show
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--session |
Browser session name (default: use active context) | ||
--new-tab |
Create a new tab instead of navigating current tab | ||
--show, --no-headless |
Run browser in visible mode | ||
--wait |
Wait duration after navigation | ||
--wait-selector |
Wait until selector is visible | ||
--timeout, -t |
Global timeout |
Usage: List browser tabs
Show all tabs in the current browser context.
This is a simplified view of tracked tabs with stable IDs.
Examples: tap browser tabs tap browser tabs --json
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--session |
Browser session name | ||
--json |
Output as JSON |
Usage: Switch to a different tab
tap browser switch <tab-id>
Set the current working tab.
Examples: tap browser switch tab-2 tap browser switch tab-1
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--session |
Browser session name |
Usage: Close a browser tab
tap browser close-tab [tab-id]
Close a tab. If no tab ID is given, closes the current tab.
After closing, the next live tab becomes current.
Examples: tap browser close-tab # Close current tab tap browser close-tab tab-2 # Close specific tab
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--session |
Browser session name |
Usage: Show browser context and tab status
Display information about the current browser context and selected tab.
Examples: tap browser status tap browser status --json
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--session |
Browser session name | ||
--json |
Output as JSON |
Usage: Navigate a tracked browser tab to a URL
tap browser navigate <url>
Navigate the resolved tracked tab to the given URL.
Examples: tap browser navigate https://example.com tap browser navigate --session dev --tab main https://example.com
Usage: Navigate back in history
Navigate the resolved tracked tab back one entry in browser history.
Examples: tap browser back tap browser back --session dev --tab main
Usage: Navigate forward in history
Navigate the resolved tracked tab forward one entry in browser history.
Examples: tap browser forward tap browser forward --session dev --tab main
Usage: Reload the current page
Reload the current page of the resolved tracked tab.
Examples: tap browser reload tap browser reload --session dev --tab main
Usage: Extract clean readable text from the page via defuddle
tap browser text [selector]
Extract clean, readable content from the current page using defuddle. Strips navigation, ads, scripts, and boilerplate — returns only the main content as Markdown (default) or JSON with metadata.
Optionally scope to a CSS selector to extract from a specific section.
This is the most token-efficient way to read page content — far cheaper than evaluating outerHTML.
Examples: tap browser text Extract main content as Markdown tap browser text "#article" Extract from a specific section tap browser text -f json Include metadata (title, word count)
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--format, -f |
Output format: json, pretty (default), raw | pretty |
Usage: Capture an AI-friendly semantic page snapshot with stable refs
tap browser snapshot [flags]
Capture a compact semantic tree from the current page and assign stable refs for interactive elements (e.g. @e1, @e2). Refs can be reused in click/type/fill/select/hover.
Use --depth to limit the AX tree depth captured. --selector is reserved for future scoped snapshots and has no effect today.
Examples: tap browser snapshot tap browser snapshot --interactive -f json tap browser snapshot --depth 4 tap browser click @e3 tap browser type @e1 "hello"
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--interactive |
Only include interactive nodes (button/link/input/etc) | ||
--selector |
Optional scope selector (reserved for future use) | ||
--depth |
Maximum AX tree depth to capture | ||
--format, -f |
Output format: json, pretty (default), raw | pretty |
Usage: Run JavaScript in a tracked browser tab
tap browser evaluate <javascript>
Evaluate JavaScript in the resolved tracked tab.
Output formatting follows the same pretty/json/raw conventions used by 'tap site'.
Examples: tap browser evaluate "document.title" tap browser evaluate "document.querySelectorAll('a').length" tap browser evaluate "JSON.stringify(performance.timing)" -f json
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--format, -f |
Output format: json, pretty (default), raw | pretty |
Usage: Capture a screenshot from a tracked browser tab
Capture a screenshot from the resolved tracked tab.
When --output is omitted, tap will generate a deterministic file path from the session name, tab name, and current timestamp.
Examples: tap browser screenshot tap browser screenshot --output page.png tap browser screenshot --session dev --tab main
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--output |
Write the screenshot to this file; defaults to a generated path when omitted |
Usage: Save the current page as PDF
tap browser pdf [flags]
Save the current page of the resolved tracked tab as a PDF file.
--background defaults to true (background graphics are printed). Pass --background=false to omit them. When --output is omitted, tap generates a file name from the session, tab name, and timestamp.
Examples: tap browser pdf tap browser pdf --output report.pdf --landscape tap browser pdf --scale 0.8 --background=false
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--output |
Write the screenshot to this file; defaults to a generated path when omitted | ||
--landscape |
Use landscape orientation | ||
--background |
Print background graphics | true | |
--scale |
Scale of the webpage rendering (default 1.0) | 1 |
Usage: Query element and page properties
Read-only element and page queries. Accepts CSS selectors or snapshot refs (@eN).
Examples: tap browser get text "h1" tap browser get html "#content" tap browser get value "input[name=q]" tap browser get attr "a.logo" href tap browser get title tap browser get url tap browser get count "li.item" tap browser get box "#sidebar" tap browser get styles "button.primary"
Usage: Get the raw textContent of an element
tap browser get text <selector|@eN>
Print the raw textContent of the first element matching the selector.
Unlike 'tap browser text' (which runs defuddle for clean markdown), this returns the unprocessed DOM text — useful for reading specific values.
Examples: tap browser get text "h1" tap browser get text @e2
Usage: Get the innerHTML of an element
tap browser get html <selector|@eN>
Print the innerHTML of the first element matching the selector.
Examples: tap browser get html "#article" tap browser get html @e1
Usage: Get the value property of an input element
tap browser get value <selector|@eN>
Print the .value property of the first element matching the selector. Works on input, textarea, and select elements.
Examples: tap browser get value "input[name=email]" tap browser get value @e4
Usage: Get an attribute value from an element
tap browser get attr <selector|@eN> <attr>
Print the value of the named attribute on the first element matching the selector. Returns an empty string if the attribute is absent.
Examples: tap browser get attr "a.logo" href tap browser get attr "img#banner" src tap browser get attr @e1 aria-label
Usage: Get the current page title
Print the document.title of the current page.
Examples: tap browser get title
Usage: Get the current page URL
Print the current location.href of the tracked tab.
Examples: tap browser get url
Usage: Count elements matching a CSS selector
tap browser get count <selector>
Print the number of elements matching the CSS selector. Note: count does not support @eN refs since snapshot refs address single elements.
Examples: tap browser get count "li.result" tap browser get count "input[type=checkbox]"
Usage: Get the bounding box of an element
tap browser get box <selector|@eN>
Print the bounding box (x, y, width, height in pixels) of the first element matching the selector, as JSON.
Examples: tap browser get box "#sidebar" tap browser get box @e2
Usage: Get the computed CSS styles of an element
tap browser get styles <selector|@eN>
Print the computed style properties of the first element matching the selector, as a JSON object mapping property names to values.
Examples: tap browser get styles "button.primary" tap browser get styles @e1
Usage: Check element boolean state
Boolean element state checks. Prints "true" or "false" and exits 0. Accepts CSS selectors or snapshot refs (@eN).
Examples: tap browser is visible "#modal" tap browser is enabled "button[type=submit]" tap browser is checked "input[type=checkbox]" tap browser is visible @e3
Usage: Check if an element is visible
tap browser is visible <selector|@eN>
Print "true" if the element exists, is not hidden (display/visibility/opacity), and has non-zero dimensions. Prints "false" otherwise. Always exits 0.
Examples: tap browser is visible "#modal" tap browser is visible @e3
Usage: Check if a form element is enabled (not disabled)
tap browser is enabled <selector|@eN>
Print "true" if the element exists and its .disabled property is false. Prints "false" if the element is disabled or not found. Always exits 0.
Examples: tap browser is enabled "button[type=submit]" tap browser is enabled @e5
Usage: Check if a checkbox or radio input is checked
tap browser is checked <selector|@eN>
Print "true" if the element exists and its .checked property is true. Prints "false" otherwise. Always exits 0.
Examples: tap browser is checked "input[type=checkbox]#agree" tap browser is checked @e7
Usage: Click an element by CSS selector or snapshot ref
tap browser click <selector|@eN>
Dispatch a real mouse click (mouseMoved → mousePressed → mouseReleased) on the first visible element matching the CSS selector.
Unlike JavaScript .click(), this triggers hover states and works with sites that listen on mousedown or have hover-triggered menus.
Examples: tap browser click "button.submit" tap browser click @e3 tap browser click "a[href='/login']"
Usage: Double-click an element by CSS selector or snapshot ref
tap browser dblclick <selector|@eN>
Dispatch a real double-click (clickCount=2) on the first visible element.
Examples: tap browser dblclick "td.editable" tap browser dblclick @e3
Usage: Type text into an element with real key events
tap browser type <selector|@eN> <text>
Focus the element matching the CSS selector and send individual keyDown/keyUp events for each character — behaving like a real user typing.
Use this instead of 'fill' when the site validates per-keystroke input or has anti-bot detection.
Examples: tap browser type "#search" "golang tutorials" tap browser type @e1 "hello world" tap browser type "input[name=q]" "hello world"
Usage: Fill form fields in a tracked browser tab
tap browser fill <selector|@eN> <value> [<selector|@eN> <value> ...]
Fill one or more form fields by CSS selector, then optionally submit.
Arguments are target/value pairs. Targets can be CSS selectors or snapshot refs. Values are set using React-compatible native setters with proper input/change event dispatch, so this works with React, Vue, Angular, and vanilla HTML forms.
Examples: tap browser fill "#username" "myuser" tap browser fill @e1 "me@example.com" tap browser fill "#email" "me@example.com" "#password" "secret" --submit "button[type=submit]" tap browser fill "input[type=search]" "query text"
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--submit |
CSS selector of element to click after filling (e.g. button[type=submit]) |
Usage: Move mouse to an element to trigger hover state
tap browser hover <selector|@eN>
Move the mouse to the center of the first visible element matching the CSS selector or snapshot ref. Dispatches real mouseMoved events that trigger CSS :hover states and mouseenter/mouseover listeners.
Examples: tap browser hover "nav.menu > li:first-child" tap browser hover ".dropdown-trigger" tap browser hover @e4
Usage: Focus an element by CSS selector or snapshot ref
tap browser focus <selector|@eN>
Move browser focus to the element matching the selector.
Examples: tap browser focus "input[name=email]" tap browser focus @e1
Usage: Ensure a checkbox is checked
tap browser check <selector|@eN>
Read the current checkbox state and click only if unchecked. Dispatches React-compatible events on state change.
Examples: tap browser check "input[name=agree]" tap browser check @e4
Usage: Ensure a checkbox is unchecked
tap browser uncheck <selector|@eN>
Read the current checkbox state and click only if checked. Dispatches React-compatible events on state change.
Examples: tap browser uncheck "input[name=newsletter]" tap browser uncheck @e5
Usage: Scroll to an element or position
tap browser scroll [selector]
Scroll the element matching the CSS selector into view, or scroll to an absolute pixel position via --x/--y. You must supply either a CSS selector or at least one of --x/--y.
CSS-only: @eN snapshot refs are not supported here. Use 'scrollintoview' to scroll a snapshot ref into the viewport instead.
Use this to trigger lazy-loaded content or scroll-based UI updates.
Examples: tap browser scroll "#comments" tap browser scroll --y 1000 tap browser scroll --x 0 --y 99999
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--x |
Absolute X pixel position (when no selector given) | ||
--y |
Absolute Y pixel position (when no selector given) |
Usage: Scroll an element into the viewport
tap browser scrollintoview <selector|@eN>
Scroll the element matching the selector into view using DOM.scrollIntoViewIfNeeded.
Examples: tap browser scrollintoview "#footer" tap browser scrollintoview @e7
Usage: Select an option in a element tap browser select <selector|@eN> <value> Select an option by value in a element, dispatching focus, input, and change events. Works with native HTML selects.
For custom dropdown components (React Select, etc.), use 'click' instead.
Usage: Locate elements by semantic attribute and perform an action
Find elements using semantic locators (role, text, label, …) and interact with them without needing a CSS selector.
Supported actions: click — real mouse click fill — set value via React-compatible native setter (requires ) type — simulate key-by-key typing (requires ) hover — move mouse to element centre focus — keyboard-focus the element check — check a checkbox or radio uncheck — uncheck a checkbox or radio text — print the element's trimmed textContent
Multiple matches: the first matching element is used.
Examples: tap browser find role button click --name "Submit" tap browser find text "Sign in" click tap browser find label "Email" fill "me@example.com" tap browser find placeholder "Search…" type "golang" tap browser find testid "login-btn" click tap browser find first "li.item" text tap browser find nth 2 "li.item" click tap browser find last "tr" text
Usage: Find by ARIA role
tap browser find role <role> <action> [value]
Find the first element with the given ARIA role and perform action.
Use --name to narrow the match to a specific accessible name.
Examples: tap browser find role button click --name "Submit" tap browser find role textbox fill "hello@example.com" --name "Email" tap browser find role link click --name "Sign in"
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--name, -n |
Filter by accessible name (substring, case-insensitive) |
Usage: Find by visible text content
tap browser find text <text> <action> [value]
Find the first element whose textContent contains (or exactly matches) the given text, then perform action.
Examples: tap browser find text "Sign in" click tap browser find text "Submit" click --exact tap browser find text "Welcome" text
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--exact |
Require an exact text match instead of substring |
Usage: Find a form element by its label text
tap browser find label <label> <action> [value]
Find the first input/textarea/select/button associated with a label whose text contains the given string, then perform action.
Resolution order: label[for=id] → wrapping → aria-label.
Examples: tap browser find label "Email" fill "me@example.com" tap browser find label "Password" fill "secret" tap browser find label "Remember me" check
Usage: Find an input by its placeholder attribute
tap browser find placeholder <placeholder> <action> [value]
Find the first element whose placeholder attribute contains the given string (case-insensitive), then perform action.
Examples: tap browser find placeholder "Search…" type "golang" tap browser find placeholder "Email address" fill "me@example.com"
Usage: Find an element by its alt attribute
tap browser find alt <text> <action>
Find the first element whose alt attribute contains the given string (case-insensitive), then perform action.
Examples: tap browser find alt "company logo" click tap browser find alt "product image" hover
Usage: Find an element by its title attribute
tap browser find title <text> <action>
Find the first element whose title attribute contains the given string (case-insensitive), then perform action.
Examples: tap browser find title "Close dialog" click tap browser find title "More options" hover
Usage: Find an element by its data-testid attribute
tap browser find testid <id> <action> [value]
Find the first element with a data-testid attribute containing the given string (case-insensitive), then perform action.
Examples: tap browser find testid "login-btn" click tap browser find testid "email-input" fill "me@example.com" tap browser find testid "username" type "alice"
Usage: Act on the first element matching a CSS selector
tap browser find first <css-selector> <action> [value]
Find the first element matching the CSS selector, then perform action. Equivalent to nth 0 .
Examples: tap browser find first "li.item" text tap browser find first "button[type=submit]" click
Usage: Act on the last element matching a CSS selector
tap browser find last <css-selector> <action> [value]
Find the last element matching the CSS selector, then perform action.
Examples: tap browser find last "tr" text tap browser find last "li.result" click
Usage: Act on the n-th (1-based) element matching a CSS selector
tap browser find nth <n> <css-selector> <action> [value]
Find the n-th element matching the CSS selector (1-based), then perform action. Use 1 for the first element, 2 for the second, etc.
Examples: tap browser find nth 2 "li.item" click tap browser find nth 3 "tr" text
Usage: Wait for a page condition to become true
tap browser wait [<selector-or-duration>]
Wait for a page condition before proceeding.
Modes (exactly one must be active):
POSITIONAL ARGUMENT Wait for CSS selector to become visible (default state). Pure time wait when the argument is a plain integer (ms). Pure time wait when the argument is a Go duration (e.g. 2s).
FLAGS --state Change element state: visible (default), hidden, attached, detached. Requires a positional CSS selector argument. --text Wait until document.body.innerText contains the substring. --url Wait until location.href matches the glob pattern. Supports * (any chars except /) and ** (any chars including /). --load Wait for a named page-load event: load — fires when the load event completes domcontentloaded — fires when DOMContentLoaded fires networkidle — no new network requests for ~500 ms --fn Poll until the JS expression returns a truthy value.
--timeout Maximum wait duration (default 30s). Applies to all modes.
Examples: tap browser wait "#login-form" tap browser wait ".spinner" --state hidden tap browser wait 2000 tap browser wait 1.5s tap browser wait --text "Welcome back" tap browser wait --url "**/dashboard" tap browser wait --load networkidle tap browser wait --fn "window.__ready === true"
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--timeout |
Maximum time to wait (default 30s) | 30s | |
--state |
Element state: visible (default), hidden, attached, detached | visible | |
--text |
Wait until document.body.innerText contains this substring | ||
--url |
Wait until location.href matches this glob (supports * and **) | ||
--load |
Wait for page load event: load, domcontentloaded, networkidle | ||
--fn |
Poll until this JS expression evaluates to a truthy value |
Usage: Send keyboard events to the page
tap browser keypress <key>
Dispatch a single key or modifier combo to the page. One invocation = one key event.
Common keys: Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Space, Home, End, PageUp, PageDown, F1-F12
Modifier combos (separated with +): Ctrl+a, Ctrl+c, Ctrl+v, Shift+Tab
Use 'keyboard type' to type multi-character text per-character instead.
Usage: Hold a key down
tap browser keydown <key>
Dispatch a rawKeyDown event for the given key name. Use 'keyup' to release. Standard key names: Enter, Tab, Escape, Shift, Control, etc.
Examples: tap browser keydown Shift tap browser keydown Control
Usage: Release a held key
tap browser keyup <key>
Dispatch a keyUp event for the given key name.
Examples: tap browser keyup Shift tap browser keyup Control
Usage: Low-level keyboard event dispatch
Dispatch keyboard events at the current focus point.
Sub-commands: type Send per-character key events (real typing) insert Paste text instantly via Input.insertText (no key events)
Usage: Type text at current focus with real key events
tap browser keyboard type <text>
Send per-character keyDown/char/keyUp events for the given text. Use this when the site validates per-keystroke input.
Examples: tap browser keyboard type "hello world"
Usage: Insert text instantly without key events
tap browser keyboard insert <text>
Insert text via Input.insertText — no keyDown/keyUp events are dispatched. Faster than 'type' but bypasses keystroke listeners.
Examples: tap browser keyboard insert "paste this text"
Usage: Low-level mouse event dispatch
Dispatch individual mouse events.
Sub-commands: move Move cursor to absolute position down [button] Press button (left|right|middle, default left) up [button] Release button wheel [dx] Scroll vertically (and optionally horizontally)
Usage: Move the mouse cursor to absolute coordinates
tap browser mouse move <x> <y>
Dispatch a mouseMoved event to the given absolute pixel position. Coordinates are relative to the viewport top-left corner.
Examples: tap browser mouse move 640 480 tap browser mouse move 0 0
Usage: Press a mouse button
tap browser mouse down [button]
Dispatch a mousePressed event. button defaults to left.
Examples: tap browser mouse down tap browser mouse down right
Usage: Release a mouse button
tap browser mouse up [button]
Dispatch a mouseReleased event. button defaults to left.
Examples: tap browser mouse up tap browser mouse up right
Usage: Dispatch a mouse wheel scroll event
tap browser mouse wheel <dy> [dx]
Dispatch a mouseWheel event. dy scrolls vertically (positive = down), dx scrolls horizontally (default 0).
Examples: tap browser mouse wheel 300 tap browser mouse wheel -200 50
Usage: Mouse-based drag and drop from source to destination
tap browser drag <src-selector> <dst-selector>
Perform a real mouse drag: move→press→interpolate→release.
Both arguments are CSS selectors (or snapshot refs whose selector hints are used).
Examples: tap browser drag ".card" ".dropzone" tap browser drag @e2 @e8
Usage: Set files on a file input element
tap browser upload <selector> <file> [file...]
Set one or more local file paths on a element via DOM.setFileInputFiles. The files must exist on the local filesystem.
Examples: tap browser upload "input[type=file]" /tmp/report.pdf tap browser upload "#avatar" photo.jpg
Usage: Accept or dismiss a JavaScript dialog
tap browser dialog [flags]
Handle a pending JavaScript dialog (alert, confirm, prompt, onbeforeunload).
--accept defaults to true (dialog is accepted). Pass --accept=false to dismiss. For prompt dialogs, supply the response text with --text.
Unhandled dialogs block all CDP commands. Use this to dismiss them.
Examples: tap browser dialog tap browser dialog --accept=false tap browser dialog --text "my answer"
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--accept |
Accept the dialog (default: true) | true | |
--text |
Text to enter for prompt dialogs |
Usage: Discover fillable form elements in a tracked browser tab
tap browser forms [flags]
List all fillable form elements (inputs, textareas, selects, buttons) in the resolved tracked tab.
Each element includes its best CSS selector, type, name, placeholder, current value, associated label, and role (text, toggle, select, submit). Use the reported selectors with 'tap browser fill'.
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--format, -f |
Output format: json, pretty (default), raw | pretty |
Usage: Manage browser cookies (includes httpOnly)
Get, set, or clear cookies for the current page.
Unlike document.cookie, this uses CDP and can access httpOnly cookies.
Usage: List all cookies for the current page
List all cookies visible to the current page via CDP, including httpOnly cookies that are inaccessible via document.cookie.
Examples: tap browser cookies get tap browser cookies get -f json
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--format, -f |
Output format: json, pretty (default), raw | pretty |
Usage: Set a cookie
tap browser cookies set <name> <value>
Set a browser cookie via CDP (can set httpOnly cookies).
Examples: tap browser cookies set "session_id" "abc123" tap browser cookies set "token" "xyz" --domain .example.com --path /api
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--domain |
Cookie domain | ||
--path |
Cookie path | / |
Usage: Delete all cookies for the current page
Delete all cookies for the current page's context via CDP. Useful for logging out or resetting auth state before a new login flow.
Example: tap browser cookies clear
Usage: Read and write browser web storage (localStorage / sessionStorage)
Inspect and manipulate localStorage and sessionStorage of the current tab.
Sub-commands: local Dump all localStorage entries as JSON local Print a single localStorage value local set Set a localStorage entry local clear Clear all localStorage entries session [...] Same four forms for sessionStorage
Usage: Manage localStorage for the current tab
tap browser storage local [key]
Read or write localStorage entries for the current page.
Usage: tap browser local Dump all entries as JSON tap browser local Print one value tap browser local set Set an entry tap browser local clear Clear all entries
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--format, -f |
Output format: json, pretty (default), raw | pretty |
Usage: Set a localStorage entry
tap browser storage local set <key> <value>
Set a key-value pair in localStorage for the current page's origin.
Usage: Clear all localStorage entries
Remove all entries from localStorage for the current page's origin.
Usage: Manage sessionStorage for the current tab
tap browser storage session [key]
Read or write sessionStorage entries for the current page.
Usage: tap browser session Dump all entries as JSON tap browser session Print one value tap browser session set Set an entry tap browser session clear Clear all entries
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--format, -f |
Output format: json, pretty (default), raw | pretty |
Usage: Set a sessionStorage entry
tap browser storage session set <key> <value>
Set a key-value pair in sessionStorage for the current page's origin.
Usage: Clear all sessionStorage entries
Remove all entries from sessionStorage for the current page's origin.
Usage: Save and load browser auth state (cookies + localStorage)
Export or import browser auth state in Playwright storageState format.
The state file is JSON: { "cookies": [{name, value, domain, path, expires, httpOnly, secure, sameSite}], "origins": [{"origin": "https://example.com", "localStorage": [{"name", "value"}]}] }
Limitations: save: captures localStorage only for the CURRENT tab's origin. All cookies from the entire browser context are included. load: cookies are applied globally; localStorage is only restored for origins matching the current page — other origins are skipped with a warning.
Usage: Export cookies and localStorage of the current origin to a file
tap browser state save <path>
Save all browser cookies and the localStorage of the current page's origin to a JSON file in Playwright storageState format.
The file is written with 0600 permissions (it contains auth cookies).
Example: tap browser state save auth.json
Usage: Import cookies and localStorage from a saved state file
tap browser state load <path>
Load browser auth state from a JSON file (Playwright storageState format).
All cookies are applied globally. localStorage is restored only for the origin matching the current page — mismatched origins are skipped with a warning.
Example: tap browser state load auth.json
Usage: Configure emulation overrides for the current tab
Persist and immediately apply emulation settings. Settings survive across invocations — they are re-applied automatically every time a tab is resolved for any browser command.
Subcommands: viewport [scale] Set viewport dimensions and optional device scale factor device Emulate a device preset (e.g. "iPhone 14") geo Override geolocation offline on|off Toggle offline mode headers Set extra HTTP request headers ({"Name":"Value",...}) media dark|light Emulate prefers-color-scheme useragent Override User-Agent string clear Remove all persisted emulation settings
Usage: Set viewport dimensions
tap browser set viewport <width> <height> [scale]
Override the browser viewport size and optional device scale factor.
Examples: tap browser set viewport 1280 720 tap browser set viewport 390 844 3.0
Usage: Emulate a device preset
tap browser set device <name>
Emulate a device using a chromedp/device preset. Sets viewport, user agent, and touch emulation in one shot.
Common devices: "iPhone 14", "iPhone 14 Pro", "Pixel 5", "iPad Pro", "Galaxy S8", "Nexus 5X", "Kindle Fire HDX"
Examples: tap browser set device "iPhone 14" tap browser set device "Pixel 5"
Usage: Override geolocation
tap browser set geo <lat> <lng>
Override the browser's geolocation to the given latitude and longitude.
Examples: tap browser set geo 37.7749 -122.4194 tap browser set geo 51.5074 -0.1278
Usage: Toggle offline mode
tap browser set offline on|off
Emulate network offline (on) or restore connectivity (off).
Examples: tap browser set offline on tap browser set offline off
Usage: Set extra HTTP request headers
tap browser set headers <json>
Add extra HTTP headers sent with every request from the tab. The argument must be a JSON object mapping header names to values.
Examples: tap browser set headers '{"Authorization":"Bearer token123"}' tap browser set headers '{"X-Custom-Header":"value","Accept-Language":"en-US"}'
Usage: Emulate prefers-color-scheme
tap browser set media dark|light
Force prefers-color-scheme to dark or light for the current tab.
Examples: tap browser set media dark tap browser set media light
Usage: Override the User-Agent string
tap browser set useragent <ua>
Override the browser User-Agent sent with every request.
Examples: tap browser set useragent "Mozilla/5.0 (compatible; MyBot/1.0)" tap browser set useragent "Googlebot/2.1 (+http://www.google.com/bot.html)"
Usage: Remove all persisted emulation settings for the tab
Wipe all persisted emulation overrides for the current tab. The browser's active overrides are not reversed until the next navigation or reload.
Examples: tap browser set clear
Usage: Capture and intercept network requests in a tracked browser tab
Network observation and interception for tracked browser tabs.
Uses the CDP Network domain for passive capture (wait, log, body) and the Fetch domain for active interception (intercept, clear).
Usage: Wait for a network request matching filters
Block until a network request matching the given filters completes, then print the captured request/response entry.
The --url-pattern flag uses glob syntax where * matches any characters including path separators. For example: /api/ matches https://example.com/api/v1/users .ads. matches https://tracker.ads.example.com/pixel
Examples: tap browser network wait --url-pattern "/api/search" tap browser network wait --url-pattern "*/graphql" --method POST --body tap browser network wait --resource-type XHR,Fetch --timeout 10s
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--url-pattern |
Glob pattern to match request URLs (* matches any chars including /) | ||
--method |
HTTP method(s) to match, comma-separated (e.g. GET,POST) | ||
--resource-type |
Resource type(s) to match, comma-separated (e.g. XHR,Fetch,Document) | ||
--timeout |
Maximum time to wait for a matching request | 30s | |
--body |
Include the response body in the output | ||
--format, -f |
Output format: json, pretty (default), raw | pretty |
Usage: Fetch the response body for a completed request by ID
tap browser network body <requestId>
Fetch and print the response body for a network request identified by its request ID (from 'tap browser network wait' or 'tap browser network log' output).
Examples: tap browser network body "12345.67" tap browser network body "12345.67" --format json
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--format, -f |
Output format: json (base64-encoded), raw (binary to stdout) | raw |
Usage: Stream captured network requests as NDJSON
Enable the Network domain and stream completed request/response entries as newline-delimited JSON (NDJSON) to stdout.
Runs until --timeout expires or the process is interrupted (Ctrl-C).
Examples: tap browser network log tap browser network log --url-pattern "/api/" --timeout 30s tap browser network log --resource-type XHR,Fetch
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--url-pattern |
Glob pattern to match request URLs | ||
--method |
HTTP method(s) to match, comma-separated | ||
--resource-type |
Resource type(s) to match, comma-separated | ||
--timeout |
Maximum duration to capture (0 = until interrupted) |
Usage: Set request interception rules (block, mock, or modify headers)
Set Fetch domain interception rules on a tracked tab.
Rules are replace-all: each call replaces any previously set rules. Pass a single rule per invocation. Use 'tap browser network clear' to remove all rules.
This command keeps running to serve interception rules until interrupted (Ctrl-C). Scripts should run it in the background.
Examples:
tap browser network intercept --block --url-pattern ".ads."
tap browser network intercept --url-pattern "*/api/user" \ --respond '{"name":"test"}' --status 200
tap browser network intercept --url-pattern "/api/" \ --header "Authorization: Bearer tok_abc123"
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--url-pattern |
Glob pattern to match request URLs | ||
--method |
HTTP method(s) to match, comma-separated | ||
--resource-type |
Resource type(s) to match, comma-separated | ||
--block |
Block matching requests (mutually exclusive with --respond) | ||
--header |
Add/override request header (repeatable, format "Key: Value") | ||
--respond |
Mock response body (mutually exclusive with --block) | ||
--status |
Mock response HTTP status code (required with --respond) | 200 | |
--content-type |
Mock response Content-Type header | application/json |
Usage: Remove all Fetch domain interception rules
Disable the Fetch domain and remove all interception rules from the resolved tracked tab.
This does not affect passive Network domain capture (log/wait).
Usage: Connect tap to existing Chrome or Electron apps
Attach tap to an already-running browser or app for reuse.
This command establishes a persistent connection to your existing Chrome/Chromium.
Once attached, all tap browser commands will use this context.
Examples: tap attach chrome Auto-discover your Chrome tap attach chrome --browser-url http://localhost:9222 tap attach status Show attachment info tap attach clear Detach from external target
Usage: Attach to your existing Chrome/Chromium browser
Attach tap to an already-running Chrome or Chromium instance.
Your browser must have remote debugging enabled. Common ways:
- Chrome started with --remote-debugging-port=9222
- Chrome with "Developer Tools" open in user data dir
Examples: tap attach chrome Auto-discover from DevToolsActivePort tap attach chrome --browser-url http://localhost:9222 tap attach chrome --port-file ~/Library/Application\ Support/Google/Chrome/DevToolsActivePort
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--browser-url, --url, --ws-url |
Chrome DevTools endpoint URL (WebSocket or HTTP base URL) | ||
--port-file |
Path to DevToolsActivePort file |
Usage: Show attachment status
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--json |
Output as JSON |
Usage: Detach from external browser/app
Remove the attachment metadata.
This does not close the external browser or app, nor does it delete cookies. It only stops tap from using this target as the default context.
Usage: Show the active browser context and current tab
Display the current default browser context, authentication state, and active tab information.
This command helps you understand which browser context and tab will be used by subsequent tap commands.
Examples: tap status Show human-readable status tap status --json Show machine-readable status
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--json |
Output as JSON |
Usage: Check and manage browser dependencies
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--install |
Install or update Lightpanda to the latest nightly build |
Usage: Upgrade tap to the latest version
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--force |
Upgrade even if already on the latest version |
Usage: Manage the embedded tap-web skill
The tap-web skill provides AI agent capabilities for web access. It is embedded in the tap binary and can be installed to the skills directory.
Usage: Install or update the embedded skill
Flags:
| Flag | Description | Default | Env |
|---|---|---|---|
--force |
Reinstall even if already up to date | ||
--path, --dir |
Custom installation directory (default: ~/.config/tap/skills/tap-web/) | TAP_SKILL_DIR |
Usage: Print the full command reference as Markdown