tabctl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tab Control

标签控制

Use tabctl to inspect and analyze tabs safely, then perform targeted actions only when requested.

使用tabctl安全地检查和分析标签页，仅在收到请求时执行针对性操作。

GraphQL API (preferred for agents)

GraphQL API（Agent优先使用）

Use

tabctl query

for field-selective reads and mutations in a single roundtrip. Use

tabctl schema

to discover available types and fields.

使用

tabctl query

可在单次往返中完成字段选择性读取和Mutation操作。使用

tabctl schema

可查看可用的类型和字段。

Read examples

读取示例

bash

undefined

bash

undefined

Get only tabId and url for all windows

tabctl query '{ windows { windowId tabs { tabId url } } }'

Paginated tabs (default limit 20)

tabctl query '{ tabs { items { tabId url title } total hasMore } }'

tabctl query '{ tabs(offset: 20) { items { tabId url } total hasMore } }'

Get tabs in a specific window

tabctl query '{ tabs(windowId: 123) { items { tabId title url } total } }'

Get groups with tab counts

tabctl query '{ groups { groupId title tabCount } }'

Get a single tab by ID

tabctl query '{ tab(id: 456) { tabId url title active groupTitle } }'

undefined

tabctl query '{ tab(id: 456) { tabId url title active groupTitle } }'

undefined

Mutation examples

Mutation 示例

bash

undefined

bash

undefined

Close tabs and get remaining tabs in one call

tabctl query 'mutation { closeTabs(tabIds: [123, 456], confirm: true) { txid closedTabs remainingTabs { tabId url } } }'

Open tabs and get the new tab IDs

tabctl query 'mutation { openTabs(urls: ["https://example.com"], group: "Research") { tabs { tabId url } } }'

Refresh tabs

tabctl query 'mutation { refreshTabs(tabIds: [123]) { refreshedTabs } }'

undefined

tabctl query 'mutation { refreshTabs(tabIds: [123]) { refreshedTabs } }'

undefined

Introspection

内省查询

bash

tabctl schema                    # Full SDL
tabctl query '{ __type(name: "Tab") { fields { name } } }'  # Discover Tab fields

bash

tabctl schema                    # Full SDL
tabctl query '{ __type(name: "Tab") { fields { name } } }'  # Discover Tab fields

Safety

安全注意事项

Prefer read-only commands: list, analyze, inspect, report, query (without mutations).
Never run
```
archive --all
```
or
```
close --apply
```
in a normal session.
Only mutate explicit targets (
```
--tab
```
,
```
--group
```
,
```
--window
```
) and use
```
--confirm
```
for close.
Respect policy: protected tabs are excluded.
Use screenshots only when you need visual context.

优先使用只读命令：list、analyze、inspect、report、无Mutation的query。
常规会话中切勿运行
```
archive --all
```
或
```
close --apply
```
命令。
仅对明确目标（
```
--tab
```
、
```
--group
```
、
```
--window
```
）执行变更操作，关闭标签时需使用
```
--confirm
```
参数。
遵守策略：受保护的标签页会被排除在外。
仅当需要可视化上下文时才使用截图功能。

Discover commands

查看可用命令

Use
```
tabctl help
```
(or
```
tabctl help --json
```
) to discover commands and flags.
For specific commands, use
```
tabctl <command> --help
```
.

使用
```
tabctl help
```
（或
```
tabctl help --json
```
）查看所有命令和参数。
如需查看特定命令的帮助，使用
```
tabctl <command> --help
```
。

Common tasks (CLI)

常见任务（CLI）

List tabs in a window:

tabctl list --window <id|active|last-focused>

List ungrouped tabs:
```
tabctl list --ungrouped
```
List with pagination:
```
tabctl list --all --limit 10 --offset 0
```

Close tabs:

tabctl close --tab <id1> --tab <id2> --confirm

Refresh a tab:
```
tabctl refresh --tab <id>
```
Generate a report:
```
tabctl report --format md
```
(add scope flags as needed)

Get page metadata:

tabctl inspect --tab <id> --signal page-meta

Get page metadata after JS loads:

tabctl inspect --tab <id> --signal page-meta --wait-for settle

Extract links safely (absolute http(s) only):

tabctl inspect --tab <id> --selector '{"name":"links","selector":"a[href]","attr":"href-url","all":true}'

Capture visual context when needed:

tabctl screenshot --tab <id> --mode full

Undo most recent change:
```
tabctl undo --latest
```

Undo by txid:

tabctl undo <txid>

(from

tabctl history --json | jq -r '.[] | .txid'

)

列出指定窗口的标签页：

tabctl list --window <id|active|last-focused>

列出未分组的标签页：
```
tabctl list --ungrouped
```
分页列出标签页：
```
tabctl list --all --limit 10 --offset 0
```

关闭标签页：

tabctl close --tab <id1> --tab <id2> --confirm

刷新标签页：
```
tabctl refresh --tab <id>
```
生成报告：
```
tabctl report --format md
```
（可按需添加范围参数）

获取页面元数据：

tabctl inspect --tab <id> --signal page-meta

获取JS加载完成后的页面元数据：

tabctl inspect --tab <id> --signal page-meta --wait-for settle

安全提取链接（仅提取http(s)绝对链接）：

tabctl inspect --tab <id> --selector '{"name":"links","selector":"a[href]","attr":"href-url","all":true}'

必要时捕获可视化上下文：

tabctl screenshot --tab <id> --mode full

撤销最近一次变更：
```
tabctl undo --latest
```

通过txid撤销操作：

tabctl undo <txid>

（txid可通过

tabctl history --json | jq -r '.[] | .txid'

获取）

Narrow scope

缩小作用域

Use one or more of:

--window

--group

--group-id

--tab

--ungrouped

. If scope is unclear, ask for it before running mutating commands.

可使用以下一个或多个参数：

--window

、

--group

、

--group-id

、

--tab

、

--ungrouped

。如果作用域不明确，在运行变更命令前请先询问确认。

Troubleshooting

问题排查

Check profile health:
```
tabctl doctor
```
Auto-repair broken profiles and resync extension files:
```
tabctl doctor --fix
```
Verify connection + runtime version sync:
```
tabctl ping --json
```
Read version state only from
```
ping
```
/
```
version
```
surfaces (not from
```
open
```
/
```
list
```
output payloads).
For local release-like sync checks during development, run a scoped command with
```
TABCTL_AUTO_SYNC_MODE=release-like
```
(example:
```
TABCTL_AUTO_SYNC_MODE=release-like tabctl list --all
```
).

检查配置文件健康状态：
```
tabctl doctor
```
自动修复损坏的配置文件并同步扩展文件：
```
tabctl doctor --fix
```
验证连接和运行时版本同步状态：
```
tabctl ping --json
```
仅从
```
ping
```
/
```
version
```
接口读取版本状态（不要从
```
open
```
/
```
list
```
输出负载中获取）。
开发过程中如需进行类正式发布的同步检查，可添加环境变量
```
TABCTL_AUTO_SYNC_MODE=release-like
```
运行限定范围的命令（示例：
```
TABCTL_AUTO_SYNC_MODE=release-like tabctl list --all
```
）。

Output flags

输出参数

Use
```
--json
```
for JSON output (list/analyze/inspect/etc.).
```
--format
```
is only for
```
report
```
(e.g.,
```
tabctl report --format md
```
).

使用
```
--json
```
获取JSON格式输出（适用于list/analyze/inspect等命令）。
```
--format
```
仅适用于
```
report
```
命令（例如：
```
tabctl report --format md
```
）。

Wait modes for inspect/screenshot

inspect/screenshot等待模式

Use

--wait-for

to control when inspection runs:

```
load
```
– wait for page load event (may miss JS-set titles)
```
dom
```
– wait for DOMContentLoaded
```
settle
```
– wait for URL and title to stabilize (500ms quiet period); use for JS-heavy pages or freshly opened tabs
```
none
```
– no waiting (default)

Example for newly opened tabs:

bash

tabctl open --url "https://example.com" --json
tabctl inspect --tab <new_tab_id> --wait-for settle --wait-timeout-ms 10000 --json

使用

--wait-for

控制检查操作的触发时机：

```
load
```
– 等待页面load事件触发（可能遗漏JS设置的标题）
```
dom
```
– 等待DOMContentLoaded事件触发
```
settle
```
– 等待URL和标题稳定（500ms无变化周期）；适用于重JS页面或刚打开的标签页
```
none
```
– 不等待（默认值）

新打开标签页的使用示例：

bash

tabctl open --url "https://example.com" --json
tabctl inspect --tab <new_tab_id> --wait-for settle --wait-timeout-ms 10000 --json

tabctl

Original

Translation

Tab Control

标签控制

GraphQL API (preferred for agents)

GraphQL API（Agent优先使用）

Read examples

读取示例

Get only tabId and url for all windows

Get only tabId and url for all windows

Paginated tabs (default limit 20)

Paginated tabs (default limit 20)

Next page

Next page

Get tabs in a specific window

Get tabs in a specific window

Get groups with tab counts

Get groups with tab counts

Get a single tab by ID

Get a single tab by ID

Mutation examples

Mutation 示例

Close tabs and get remaining tabs in one call

Close tabs and get remaining tabs in one call

Open tabs and get the new tab IDs

Open tabs and get the new tab IDs

Refresh tabs

Refresh tabs

Introspection

内省查询

Safety

安全注意事项

Discover commands

查看可用命令

Common tasks (CLI)

常见任务（CLI）

Narrow scope

缩小作用域

Troubleshooting

问题排查

Output flags

输出参数

Wait modes for inspect/screenshot

inspect/screenshot等待模式