peekaboo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Peekaboo

Peekaboo is a full macOS UI automation CLI: capture/inspect screens, target UI elements, drive input, and manage apps/windows/menus. Commands share a snapshot cache and support

--json

-j

for scripting. Run

peekaboo

peekaboo <cmd> --help

for flags;

peekaboo --version

prints build metadata. Tip: run via

polter peekaboo

to ensure fresh builds.

Peekaboo是一款完整的macOS UI自动化CLI工具：可捕获/检查屏幕、定位UI元素、模拟输入操作，以及管理应用程序/窗口/菜单。所有命令共享快照缓存，并支持

--json

-j

参数用于脚本编写。运行

peekaboo

或

peekaboo <cmd> --help

查看可用参数；

peekaboo --version

会打印构建元数据。提示：通过

polter peekaboo

运行以确保使用最新版本构建。

Features (all CLI capabilities, excluding agent/MCP)

功能（所有CLI功能，不包含agent/MCP）

Core

```
bridge
```
: inspect Peekaboo Bridge host connectivity
```
capture
```
: live capture or video ingest + frame extraction
```
clean
```
: prune snapshot cache and temp files
```
config
```
: init/show/edit/validate, providers, models, credentials
```
image
```
: capture screenshots (screen/window/menu bar regions)
```
learn
```
: print the full agent guide + tool catalog
```
list
```
: apps, windows, screens, menubar, permissions
```
permissions
```
: check Screen Recording/Accessibility status
```
run
```
: execute
```
.peekaboo.json
```
scripts
```
sleep
```
: pause execution for a duration
```
tools
```
: list available tools with filtering/display options

Interaction

```
click
```
: target by ID/query/coords with smart waits
```
drag
```
: drag & drop across elements/coords/Dock
```
hotkey
```
: modifier combos like
```
cmd,shift,t
```
```
move
```
: cursor positioning with optional smoothing
```
paste
```
: set clipboard -> paste -> restore
```
press
```
: special-key sequences with repeats
```
scroll
```
: directional scrolling (targeted + smooth)
```
swipe
```
: gesture-style drags between targets
```
type
```
: text + control keys (
```
--clear
```
, delays)

System

```
app
```
: launch/quit/relaunch/hide/unhide/switch/list apps
```
clipboard
```
: read/write clipboard (text/images/files)
```
dialog
```
: click/input/file/dismiss/list system dialogs
```
dock
```
: launch/right-click/hide/show/list Dock items
```
menu
```
: click/list application menus + menu extras
```
menubar
```
: list/click status bar items
```
open
```
: enhanced
```
open
```
with app targeting + JSON payloads
```
space
```
: list/switch/move-window (Spaces)
```
visualizer
```
: exercise Peekaboo visual feedback animations
```
window
```
: close/minimize/maximize/move/resize/focus/list

Vision

```
see
```
: annotated UI maps, snapshot IDs, optional analysis

Global runtime flags

```
--json
```
/
```
-j
```
,
```
--verbose
```
/
```
-v
```
,
```
--log-level <level>
```
```
--no-remote
```
,
```
--bridge-socket <path>
```

核心功能

```
bridge
```
：检查Peekaboo Bridge主机连接状态
```
capture
```
：实时捕获或视频导入 + 帧提取
```
clean
```
：清理快照缓存和临时文件
```
config
```
：初始化/查看/编辑/验证配置、提供者、模型、凭据
```
image
```
：捕获屏幕截图（屏幕/窗口/菜单栏区域）
```
learn
```
：打印完整的agent指南 + 工具目录
```
list
```
：列出应用程序、窗口、屏幕、菜单栏、权限
```
permissions
```
：检查屏幕录制/辅助功能权限状态
```
run
```
：执行
```
.peekaboo.json
```
脚本
```
sleep
```
：暂停执行指定时长
```
tools
```
：列出可用工具，支持过滤/显示选项

交互功能

```
click
```
：通过ID/查询/坐标定位目标，支持智能等待
```
drag
```
：在元素/坐标/程序坞之间拖放
```
hotkey
```
：组合键操作，例如
```
cmd,shift,t
```
```
move
```
：定位光标，可选平滑移动效果
```
paste
```
：设置剪贴板内容 -> 粘贴 -> 恢复原剪贴板内容
```
press
```
：特殊按键序列，支持重复操作
```
scroll
```
：定向滚动（目标定位 + 平滑滚动）
```
swipe
```
：在目标间执行手势式拖动
```
type
```
：输入文本 + 控制键（支持
```
--clear
```
参数、延迟输入）

系统功能

```
app
```
：启动/退出/重启/隐藏/显示/切换/列出应用程序
```
clipboard
```
：读取/写入剪贴板内容（文本/图片/文件）
```
dialog
```
：点击/输入/选择文件/关闭/列出系统对话框
```
dock
```
：启动/右键点击/隐藏/显示/列出程序坞项目
```
menu
```
：点击/列出应用程序菜单 + 额外菜单项
```
menubar
```
：列出/点击状态栏项目
```
open
```
：增强版
```
open
```
命令，支持应用定位 + JSON负载
```
space
```
：列出/切换/移动窗口到不同桌面（Spaces）
```
visualizer
```
：演示Peekaboo的视觉反馈动画
```
window
```
：关闭/最小化/最大化/移动/调整大小/聚焦/列出窗口

视觉功能

```
see
```
：生成带注释的UI映射图、快照ID，可选分析功能

全局运行参数

```
--json
```
/
```
-j
```
、
```
--verbose
```
/
```
-v
```
、
```
--log-level <level>
```
```
--no-remote
```
、
```
--bridge-socket <path>
```

Quickstart (happy path)

快速入门（最佳实践）

bash

peekaboo permissions
peekaboo list apps --json
peekaboo see --annotate --path /tmp/peekaboo-see.png
peekaboo click --on B1
peekaboo type "Hello" --return

bash

peekaboo permissions
peekaboo list apps --json
peekaboo see --annotate --path /tmp/peekaboo-see.png
peekaboo click --on B1
peekaboo type "Hello" --return

Common targeting parameters (most interaction commands)

通用定位参数（大多数交互命令适用）

App/window:

--app

--pid

--window-title

--window-id

--window-index

Snapshot targeting:
```
--snapshot
```
(ID from
```
see
```
; defaults to latest)
Element/coords:
```
--on
```
/
```
--id
```
(element ID),
```
--coords x,y
```

Focus control:

--no-auto-focus

--space-switch

--bring-to-current-space

--focus-timeout-seconds

--focus-retry-count

应用/窗口：

--app

、

--pid

、

--window-title

、

--window-id

、

--window-index

快照定位：
```
--snapshot
```
（来自
```
see
```
命令的ID；默认使用最新快照）
元素/坐标：
```
--on
```
/
```
--id
```
（元素ID）、
```
--coords x,y
```

聚焦控制：

--no-auto-focus

、

--space-switch

、

--bring-to-current-space

、

--focus-timeout-seconds

、

--focus-retry-count

Common capture parameters

通用捕获参数

Output:
```
--path
```
,
```
--format png|jpg
```
,
```
--retina
```

Targeting:

--mode screen|window|frontmost

--screen-index

--window-title

--window-id

Analysis:
```
--analyze "prompt"
```
,
```
--annotate
```

Capture engine:

--capture-engine auto|classic|cg|modern|sckit

输出：
```
--path
```
、
```
--format png|jpg
```
、
```
--retina
```

定位：

--mode screen|window|frontmost

、

--screen-index

、

--window-title

、

--window-id

分析：
```
--analyze "prompt"
```
、
```
--annotate
```

捕获引擎：

--capture-engine auto|classic|cg|modern|sckit

Common motion/typing parameters

通用运动/输入参数

Timing:
```
--duration
```
(drag/swipe),
```
--steps
```
,
```
--delay
```
(type/scroll/press)
Human-ish movement:
```
--profile human|linear
```
,
```
--wpm
```
(typing)

Scroll:

--direction up|down|left|right

--amount <ticks>

--smooth

时序：
```
--duration
```
（拖动/滑动）、
```
--steps
```
、
```
--delay
```
（输入/滚动/按键）
类人化操作：
```
--profile human|linear
```
、
```
--wpm
```
（输入速度）

滚动：

--direction up|down|left|right

、

--amount <ticks>

、

--smooth

Examples

示例

See -> click -> type (most reliable flow)

查看 -> 点击 -> 输入（最可靠流程）

bash

peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png
peekaboo click --on B3 --app Safari
peekaboo type "user@example.com" --app Safari
peekaboo press tab --count 1 --app Safari
peekaboo type "supersecret" --app Safari --return

bash

peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png
peekaboo click --on B3 --app Safari
peekaboo type "user@example.com" --app Safari
peekaboo press tab --count 1 --app Safari
peekaboo type "supersecret" --app Safari --return

Target by window id

通过窗口ID定位

bash

peekaboo list windows --app "Visual Studio Code" --json
peekaboo click --window-id 12345 --coords 120,160
peekaboo type "Hello from Peekaboo" --window-id 12345

bash

peekaboo list windows --app "Visual Studio Code" --json
peekaboo click --window-id 12345 --coords 120,160
peekaboo type "Hello from Peekaboo" --window-id 12345

Capture screenshots + analyze

捕获屏幕截图 + 分析

bash

peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png
peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"
peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"

bash

peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png
peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"
peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"

Live capture (motion-aware)

实时捕获（运动感知）

bash

peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \
  --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture

bash

peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \
  --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture

App + window management

应用 + 窗口管理

bash

peekaboo app launch "Safari" --open https://example.com
peekaboo window focus --app Safari --window-title "Example"
peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800
peekaboo app quit --app Safari

bash

peekaboo app launch "Safari" --open https://example.com
peekaboo window focus --app Safari --window-title "Example"
peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800
peekaboo app quit --app Safari

Menus, menubar, dock

菜单、菜单栏、程序坞

bash

peekaboo menu click --app Safari --item "New Window"
peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"
peekaboo menu click-extra --title "WiFi"
peekaboo dock launch Safari
peekaboo menubar list --json

bash

peekaboo menu click --app Safari --item "New Window"
peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"
peekaboo menu click-extra --title "WiFi"
peekaboo dock launch Safari
peekaboo menubar list --json

Mouse + gesture input

鼠标 + 手势输入

bash

peekaboo move 500,300 --smooth
peekaboo drag --from B1 --to T2
peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800
peekaboo scroll --direction down --amount 6 --smooth

bash

peekaboo move 500,300 --smooth
peekaboo drag --from B1 --to T2
peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800
peekaboo scroll --direction down --amount 6 --smooth

Keyboard input

键盘输入

bash

peekaboo hotkey --keys "cmd,shift,t"
peekaboo press escape
peekaboo type "Line 1\nLine 2" --delay 10

Notes

Requires Screen Recording + Accessibility permissions.
Use
```
peekaboo see --annotate
```
to identify targets before clicking.

bash

peekaboo hotkey --keys "cmd,shift,t"
peekaboo press escape
peekaboo type "Line 1\nLine 2" --delay 10

注意事项

需要屏幕录制 + 辅助功能权限。
点击操作前，使用
```
peekaboo see --annotate
```
命令定位目标元素。