CLI

Use abg to find a shared tab, read it, and operate it from a terminal, a script, or an agent.

Every command prints JSON unless you choose another --format. The JSON keys are a stable contract; see Errors and output.

Find the shared tab

abg status
abg tabs --compact
abg inspect

• abg status shows Gateway state, connected extensions, and the shared tab count.
• abg tabs --compact lists shared tabs with a short ref such as t1.
• abg inspect returns both in one JSON object.

A ref stays bound to the same tab while the Gateway runs, even when other tabs open or close. Get a fresh ref after the Gateway restarts, the tab closes, or its share ends. When several Chrome profiles are connected, use refs instead of raw tabId values. The same tab ID can exist in two profiles, and ABG then returns ambiguous_tab_id.

Read a page

These commands are read-only. They need a shared tab but do not open an approval window.

abg read t1 --format markdown
abg read t1 --selector article --format markdown
abg get text t1 "h1"
abg snapshot t1 --interactive-only --compact
abg screenshot t1 --out page.png
abg table t1 --format markdown
abg console t1
abg network t1 --url "*api*"

Use --selector to keep output small. snapshot assigns refs such as @e1 that you can pass to abg click t1 --ref @e1. Without --out, screenshot saves to $TMPDIR/abg/screenshots/.

Operate a page

Write commands act on the same shared tab. By default, each one opens a local approval window with Allow and Deny before it runs.

abg click t1 --selector "button.save"
abg fill t1 --selector "input[name=email]" --value "me@example.com"
abg key t1 Enter
abg upload t1 --selector "input[type=file]" --file ./report.pdf
abg navigate t1 "https://example.com"
abg revoke t1

• A click selector that matches more than one element returns ambiguous_selector and clicks nothing. Narrow the selector, or use abg find first|last|nth or a snapshot ref.
• navigate to another origin ends the share.
• upload needs Allow access to file URLs turned on for the extension. Without it, ABG returns file_access_required.
• revoke stops sharing the tab and never prompts.

To turn approvals off, use Require approval for write operations in the extension popup.

Target a tab without a ref

Match on URL or title instead of a ref:

abg read --match-url "*notion.so*" --format markdown
abg click --match-title "Dashboard" --selector "button.refresh"

If more than one shared tab matches, ABG returns ambiguous_tab_match. Add --first to use the first match.

Work inside iframes

List frames first. Same-origin frames get refs such as @f1:

abg frames t1
abg read t1 --frame @f1 --selector "main" --format markdown

Cross-origin frames appear in the list, but selector access returns frame_not_accessible.

Edit rich editors

Use fill for normal inputs and plain editable fields. When a rich editor ignores fill, clear it and paste instead:

abg clear t1 --selector "[contenteditable=true]"
printf "new content" | abg paste t1 --selector "[contenteditable=true]" --stdin

The audit log records the selector, action, and byte length. It does not record the pasted text.

Annotate a page for the agent

Annotations let you mark parts of a page and add comments that the agent can read.

1. Start annotation mode. In the popup, choose Annotate this tab, or run:

   abg annotate t1 --start

2. Use Area to drag a rectangle or Text to select text. Add a comment to each annotation.

3. Click Done or press Escape.

4. Read the annotations as JSON:

   abg annotate t1

After a page reload, annotations are saved but not redrawn. abg annotate t1 then returns a nextCommand of abg annotate t1 --restore.

Annotation references

Each annotation has a stable abg-annotation:<uid> reference. Open its editor and choose Copy ID, or select a marker and press Command-C on macOS or Ctrl-C elsewhere. A second click opens the editor. Outside annotation mode, clicking the marker copies its reference directly. Selected text and editable fields retain normal browser copy behavior.

Paste the reference into read-abg-annotations to read and remove only that annotation after confirming its target. In Cloud, use method annotation_mode with action: "get" or action: "remove" and uid; other notes remain. The current source CLI also supports abg annotate <reference> and abg annotate <reference> --clear; these commands require a CLI build containing annotation-reference support.

While annotating, use toolbar Undo/Redo buttons or Command-Z/Command-Shift-Z on macOS and Ctrl-Z/Ctrl-Shift-Z elsewhere. The latest 50 changes in the capture session can be undone or redone. Stopping, reloading, restoring, or agent removal/clearing resets this history. Text inputs and editable page content retain native undo.

Record a tab

abg record start t1 --out demo.webm
abg record status
abg record stop

abg record start always opens a local approval window, even when other approvals are off. The Allow click starts a WebM recording of the shared tab with tab audio. Add --mic only when room audio should be mixed in.

Bookmarks and Reading List

Bookmarks and Reading List entries are separate from shared-tab content. Turn on Bookmarks access or Reading List access in the popup first:

abg bookmarks list
abg bookmarks search "docs"
abg bookmarks get <bookmark-id>
abg bookmarks open <bookmark-id>
abg reading-list list
abg reading-list search "later"

bookmarks uses Chrome’s chrome.bookmarks API and the optional bookmarks permission. reading-list uses chrome.readingList, which Chrome documents for Chrome 120 and newer with the optional readingList permission. Browsers without chrome.readingList return an explicit unsupported error. Audit entries store counts, ids, and byte lengths, not full bookmark or Reading List URLs.

Run JavaScript as a last resort

Prefer named commands such as get, find, wait, snapshot, and plugin commands. Use eval only when they are not enough:

abg eval t1 --script "document.title" --approve

Eval is off until you turn on Allow approved JavaScript eval in the popup. While Trusted automation (AutoMode) is off, every eval call needs --approve and a local approval.

Errors and output

Failures print a JSON object to stderr and exit with a non-zero status. This example omits the userMessage key:

{
  "error": "tab_ref_not_found",
  "message": "No shared tab exists for ref t1.",
  "nextCommand": "abg tabs --compact"
}

error is a stable snake_case code. nextCommand, when present, is a safe local command to run next. Many errors also include a userMessage with recovery steps for a person. Common codes:

| Code | Meaning | Next step | | --- | --- | --- | | gateway_not_running | The Gateway app is not running. | Start the app, then run abg status. | | extension_not_connected | No browser extension is connected. | Check the extension, then run abg status. | | no_permitted_tabs | No tab is shared. | Share a tab, then run abg tabs --compact. | | tab_not_permitted | The tab is not shared or its share ended. | Share it again, then run abg tabs --compact. | | tab_ref_not_found | No shared tab has that ref. | Run abg tabs --compact for current refs. |

The full output contract is in docs/CLI_JSON_CONTRACT.md. The complete command list is in the README. MCP clients can call the same commands through abg mcp-server; see Install.

Related

• Plugins: add commands and domain-specific Markdown.
• Security: approvals, eval, and the audit log.