CLI

abg を使うと、ターミナル、スクリプト、エージェントから共有中のタブを探し、読み取り、操作できます。

コマンドは、--format で別の形式を選ばない限り JSON を出力します。JSON のキーは安定した契約として扱われます。詳しくはエラーと出力を参照してください。

共有中のタブを探す

abg status
abg tabs --compact
abg inspect

abg status は Gateway の状態、接続中の拡張機能、共有中のタブ数を返します。
abg tabs --compact は共有中のタブを t1 のような短い ref 付きで一覧します。
abg inspect は両方を1つの JSON にまとめて返します。

ref は、Gateway が動いている間は同じタブを指し続けます。他のタブを開いたり閉じたりしても番号はずれません。Gateway を再起動したとき、タブを閉じたとき、共有が終わったときは ref を取り直します。Chrome のプロファイルを複数つないでいるときは、生の tabId ではなく ref を使ってください。同じタブ ID が別のプロファイルにも存在すると、ABG は ambiguous_tab_id を返します。

ページを読み取る

次のコマンドは読み取り専用です。共有中のタブは必要ですが、承認ウィンドウは開きません。

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*"

--selector で範囲を絞ると出力が小さくなります。snapshot は @e1 のような参照を振り、abg click t1 --ref @e1 に渡せます。--out を省くと、screenshot は $TMPDIR/abg/screenshots/ に保存します。

ページを操作する

書き込み系のコマンドも同じ共有タブに作用します。初期設定では、実行前に許可と拒否を選べるローカルの承認ウィンドウが開きます。

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

click のセレクターが複数の要素に一致すると、何もクリックせずに ambiguous_selector を返します。セレクターを絞るか、abg find first|last|nth やスナップショットの参照を使います。
navigate で別のオリジンへ移動すると共有は終わります。
upload には、拡張機能の Allow access to file URLs をオンにしておく必要があります。オフのままだと file_access_required を返します。
revoke はタブの共有を解除します。承認は求めません。

承認をやめるには、拡張機能のポップアップで 書き込み操作の前に承認を求める をオフにします。

ref を使わずにタブを指定する

ref の代わりに URL やタイトルで照合できます。

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

複数の共有タブが一致すると ambiguous_tab_match を返します。最初に一致したタブでよければ --first を付けます。

iframe の中を扱う

先に frame を一覧します。同一オリジンの frame には @f1 のような参照が付きます。

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

クロスオリジンの frame も一覧には出ますが、セレクターでアクセスすると frame_not_accessible が返ります。

リッチエディターを編集する

通常の入力欄や素直な編集領域には fill を使います。リッチエディターが fill を受け付けないときは、中身を消してから貼り付けます。

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

監査ログにはセレクター、操作名、バイト数を記録します。貼り付けた本文は記録しません。

ページに注釈を付けて伝える

注釈を使うと、ページ上の場所に印とコメントを付け、エージェントに読ませられます。

注釈モードを始めます。ポップアップで このタブに注釈を付ける を選ぶか、次を実行します。
Terminal window
```
abg annotate t1 --start
```
範囲で矩形をドラッグするか、テキスト で文字列を選びます。注釈ごとにコメントを書きます。
完了を押すか、Escape キーを押して終えます。
注釈を JSON で読み取ります。
Terminal window
```
abg annotate t1
```

ページを再読み込みすると、注釈は保存されますが再描画はされません。このとき abg annotate t1 は nextCommand として abg annotate t1 --restore を返します。

注釈の参照ID

各注釈には、固定の参照ID abg-annotation:<uid>があります。注釈の編集画面を開いてIDをコピーを選ぶか、マーカーを選択して、macOSではCommand-C、それ以外ではCtrl-Cを押します。もう一度クリックすると編集画面が開きます。注釈モードがオフのときは、マーカーをクリックすると参照IDを直接コピーできます。テキストを選択している場合や編集可能な入力欄では、ブラウザーの通常のコピー操作が使えます。

参照IDをread-abg-annotationsに貼り付けると、対象を確認したうえで、その注釈だけを取得・削除できます。Cloudでは、メソッドannotation_modeにaction: "get"またはaction: "remove"とuidを指定します。他の注釈は残ります。現在のソース版CLIは、abg annotate <reference>とabg annotate <reference> --clearにも対応しています。これらのコマンドを使用するには、注釈の参照IDへの対応を含むCLIビルドが必要です。

注釈の編集中は、ツールバーの「元に戻す」「やり直す」ボタン、またはmacOSではCommand-Z／Command-Shift-Z、それ以外ではCtrl-Z／Ctrl-Shift-Zを使用できます。キャプチャセッション内の直近50件の変更を元に戻したり、やり直したりできます。停止、再読み込み、復元、エージェントによる注釈の削除・一括消去を行うと、この履歴はリセットされます。テキスト入力欄や編集可能なページ内のコンテンツでは、通常の「元に戻す」操作が使えます。

タブを録画する

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

abg record start は、他の承認をオフにしていても必ずローカルの承認ウィンドウを開きます。許可を押すと、共有中のタブをタブの音声付きで WebM に録画し始めます。部屋の音も混ぜたいときだけ --mic を付けます。

ブックマークとリーディングリスト

ブックマークとリーディングリストは、共有タブの内容とは別のデータです。先にポップアップで ブックマークへのアクセス または リーディングリストへのアクセス をオンにします。

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 は Chrome の chrome.bookmarks API と、任意の bookmarks 権限を使います。reading-list は chrome.readingList を使います。Chrome のドキュメントでは Chrome 120 以降で任意の readingList 権限とともに使える API です。chrome.readingList がないブラウザーでは、未対応であることを示すエラーを返します。監査ログには件数、ID、バイト数を残し、ブックマークやリーディングリストの URL そのものは残しません。

JavaScript は最後の手段にする

get、find、wait、snapshot、プラグインのコマンドなど、名前の付いたコマンドを優先します。それで足りないときだけ eval を使います。

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

eval は、ポップアップで 承認制の JavaScript eval を許可 をオンにするまで使えません。信頼済み自動化（AutoMode） がオフの間は、eval を呼ぶたびに --approve とローカルの承認が必要です。

エラーと出力

失敗すると JSON オブジェクトを標準エラーに出し、0 以外の終了コードで終わります。次の例では userMessage キーを省いています。

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

error は変わらない snake_case のコードです。nextCommand がある場合は、次に実行しても安全なローカルのコマンドが入っています。多くのエラーには、人向けの対処を書いた userMessage も付きます。よく出るコードは次のとおりです。

| コード | 意味 | 次の操作 | | --- | --- | --- | | gateway_not_running | Gateway アプリが起動していません。 | アプリを起動し、abg status を実行します。 | | extension_not_connected | 拡張機能が接続されていません。 | 拡張機能を確かめ、abg status を実行します。 | | no_permitted_tabs | 共有中のタブがありません。 | タブを共有し、abg tabs --compact を実行します。 | | tab_not_permitted | タブが共有されていないか、共有が終わりました。 | 共有し直し、abg tabs --compact を実行します。 | | tab_ref_not_found | その ref の共有タブがありません。 | abg tabs --compact で今の ref を確かめます。 |

出力の契約は docs/CLI_JSON_CONTRACT.md にあります。コマンドの全一覧は README を参照してください。MCP クライアントからは abg mcp-server 経由で同じコマンドを呼べます。インストールを参照してください。

CLI