UniClipboard
CLI

命令参考

uniclip 发布版中的空间、成员、内容、搜索、诊断与移动端同步命令。

在 GitHub 上编辑

本页只介绍发布版中由 uniclip --help 展示的公开命令。第一次使用 CLI，请先看 快速上手。开发专用和隐藏命令留在仓库开发文档中，不混入用户指南。

空间

命令作用
uniclip space status查看当前空间和设备信任摘要。
uniclip space init为当前 profile 创建新的加密空间。
uniclip space invite签发一次性配对邀请。
uniclip space join交互输入邀请码，或传入 --code <CODE>；加 --switch 可切换到另一个空间。
uniclip space reset --yes重建为只包含本机的新空间，同时保留本机历史、已完成文件、设置、设备身份和解锁能力。

空间重建会永久废弃旧的配对、信任和同步关系，所有设备都需要重新配对。它不会删除本机 历史，也不是恢复出厂设置。

脚本可以运行 uniclip --json space init --passphrase <PASSPHRASE>，成功后会得到一个 包含 space_id、device_id 和 fingerprint 的 JSON 对象。JSON 模式不会打开交互提示， 因此必须显式提供口令。uniclip --json space invite 会逐行输出 JSON：第一条事件包含 邀请码和到期时间，后续事件报告配对完成、失败或被中断。这样调用方可以在命令继续等待 另一台设备时先读到邀请码。

space join 默认等待最终结果。--no-wait 会在请求被接受后返回；之后可用 space join status 和 space join cancel 查看或取消等待中的请求。切换空间时， 除非传入 --yes，否则命令会先要求确认。--preserve-unreadable-history 会在 切换时保留无法读取的本机记录，而不是丢弃它们。

加入请求

命令作用
uniclip space join --no-wait记录等待中的加入请求后立即返回，不等待最终结果。
uniclip space join status查看当前加入请求及其 Engine 状态。
uniclip space join cancel请求取消当前仍在等待的加入。

Ctrl-C 只会停止本地等待；确实要取消请求时应使用 space join cancel。

成员

命令返回内容
uniclip member list本空间的成员 —— 本机加上已配对的对端 —— 及各对端的最近一次可达状态：{name} ({online | offline | unknown})。
uniclip member list --probe同上，但会先主动 ping 每个已配对对端以刷新状态（会多一次网络往返）。

旧的 uniclip members 及其别名 uniclip devices 已隐藏并弃用。为兼容既有脚本， 它们仍可执行，但会打印弃用提示。新脚本应使用 uniclip member list；三种写法都支持 --json。

移除成员

uniclip member remove <PEER-ID>

即使对方离线，这条命令也会记录不可逆的移除意图，并立即停止向它发送新内容。 移除后可用 uniclip member trust status 查看当前设备关系状态。

设备信任变化

命令作用
uniclip member trust status查看当前设备组变化、变化 ID 以及每种选择的影响。
uniclip member trust choose从当前设备组问题的可用选项中选择。

交互终端可按提示选择。脚本或 JSON 调用应传入 --issue <ISSUE-ID> 和 --choice <CHOICE-ID>， 使用 member trust status 返回的编号；涉及移除本机还需 --confirm-local-removal。 如果状态已变化，应重新查询再选择；提交结果可能仍在等待或需要重新配对。

按成员设置同步

命令作用
uniclip member sync show <DEVICE>查看一个成员的发送、接收和内容类型设置。
uniclip member sync set <DEVICE> [OPTIONS]只修改命令中明确给出的设置。

<DEVICE> 可以是设备 ID；在交互终端中也可以使用没有歧义的设备名称。 set 支持 --send on|off、--receive on|off，以及逗号分隔的 --send-types / --receive-types；用 all 或 none 表示全部类型或不选任何类型。

发送与监听

# 把一段文本发给所有在线已配对设备
uniclip send "hello from the CLI"

# 或者从 stdin 读取
echo "from a heredoc" | uniclip send

# 限定 fan-out 到指定设备（可重复）
uniclip send "scoped message" --peer DEVICE_ID_A --peer DEVICE_ID_B

# 发送现有普通文件（自动识别）
uniclip send ./report.pdf

# 强制把现有文件名作为文字发送
uniclip send --text report.pdf

# 重新分发一条本地已捕获的条目（不读 stdin / positional text）。
# 不带 `--peer` 时默认目标为 trusted peer 中尚未收到该条目的差集。
uniclip send --resend <ENTRY_ID>

# 实时打印收到的剪贴 payload（Ctrl-C 停止）
uniclip watch

--resend 只能重发 本地捕获 且 payload 仍在缓存里的条目。 从远端 peer 同步进来的条目不能从本机 resend；可叠加 --peer ... 显式指定 fan-out 目标。

uniclip watch 是 诊断观察器：它会打印首个文本表示（图片型 payload 则按 representation 摘要展示）， 但 不会 写入系统剪贴板 —— 写系统剪贴板是守护进程的职责。

发送和接收文件

# 发送端：显式强制文件模式（保留用于兼容）
uniclip send -f ./big-file.bin

# 发送端：从 stdin 逐行读取完整文件路径
printf '%s\n' ./one.bin './files/two words.bin' | uniclip send -f

# 接收端：等待下一条入站内容。文件会从守护进程缓存导出到
# 指定目录。Ctrl-C 停止等待。
uniclip get --wait --out ./inbox

位置参数对应现有普通文件时会自动按文件发送。使用 --text 可强制把文件名作为文字 发送，使用 -f / --file 可强制进入文件模式。没有位置路径时，文件模式会从 stdin 逐行读取完整路径；stdin 表示路径，不是文件内容。空行会被忽略，所有路径会在发送前 完成校验，重复路径只发送一次。暂不支持目录；明显但不存在的路径会直接报错，不会 静默当作文字。文件模式支持重复使用 --peer；所有相关目标均已完成、失败或离线后 命令会自动退出，Ctrl-C 可取消等待。get --wait 成功时沿用下文的 get 输出约定。

读取已同步的条目

get 默认读取守护进程历史里已经存在的内容并立即返回。加上 --wait 后， 它会订阅命令启动后到达的下一条匹配内容，按相同输出规则处理一次后退出。 --wait 可与 --type 或 --id 组合，但不会取用旧历史条目或已经完成的传输。

# 最新一条可用条目（文本/链接打到 stdout）
uniclip get

# 同时复制到当前终端所在电脑的剪贴板
uniclip get -c

# 等待下一条新同步内容
uniclip get -w

# 等待下一条文件；交互终端在 stderr 显示接收进度
uniclip get -w --type file

# 仅在指定 id 于订阅建立后到达时处理
uniclip get -w --id <ENTRY_ID>

# 等待下一条内容并复制
uniclip get --copy --wait

# 最新一条指定类型：image | file | text | link
uniclip get --type image

# 按 id 取指定条目（id 来自 `uniclip search`），落地到目录
uniclip get --id <ENTRY_ID> --out ./inbox

# 仅列出最近条目，不取回
uniclip get --list -n 20

输出约定：文本 / 链接内容打到 stdout（可管道）；仅当 stdout 是交互式终端时才补一个尾换行，因此管道或重定向输出保持字节精确；图片 / 文件字节写入 --out（目录，默认 per-user 缓存目录）并把绝对路径打到 stdout，或用 --out - 直接写到 stdout。成功获取时不会再输出额外状态提示，因此可以直接管道传递或捕获结果。 等待提示只写入 stderr，不会污染 stdout。

加上 -c 或 --copy 后，文本和链接会复制内容，图片和文件会复制落盘后的完整 路径。图片和文件不能同时使用 --copy 与 --out -，因为后者不会产生文件路径。

等待匹配文件时，交互终端会显示真实已接收字节；总量已知时同时显示总字节和百分比， 总量未知时显示已接收字节与活动状态。进度只写入 stderr；JSON stdout 只包含最终结果， 非交互 stderr 不产生动画控制字符。当前 pending 事件可通过非空文件名列表提前确认 file，但不能可靠区分 image、text 和 link，因此这些过滤会等待最终分类， 不会为了提前显示进度而锁定无关传输。

旧的 uniclip recv [--out DIR] 已隐藏并进入弃用期。本版本仍兼容已有脚本，并会在 stderr 输出一次提醒；新脚本应改用 uniclip get --wait [--out DIR]。

搜索

uniclip search 是 GUI 仪表盘搜索框背后那个加密全文索引的命令行入口。

uniclip search status                    # 索引是否就绪 / 是否在建
uniclip search rebuild                   # 从历史重建索引（同步执行）
uniclip search "报告"                    # 基本查询
uniclip search "报告" \
    --type text --ext md \
    --limit 20 --detailed
uniclip search "报告" \
    --from-ms 1710000000000 --to-ms 1710100000000
uniclip search "报告" \
    --source-device "Laptop"             # 只看来自该设备的内容
uniclip search "报告" \
    --operator or --time-preset last_7d \
    --tag favorited --offset 20

筛选项可以组合。--type、--tag、--ext 和 --source-device 都可重复使用。 --operator 可选 and 或 or；--time-preset 可选 today、yesterday、 last_7d 或 last_30d；--offset 和 --limit 用于分页。来源设备可以是 不区分大小写的设备名或设备 ID；运行 uniclip member list 可查看可用名称。 --detailed 和 --json 的结果会包含来源设备 ID。

rebuild 是同步命令，重建完成才返回；脚本里抓诊断快照很有用。

移动端同步

uniclip mobile ... 是移动端同步功能的命令行入口，覆盖 设备 → 移动端同步 面板的所有动作。协议层文档见 移动端 LAN API。

# 一键向导：开启功能、配置 LAN 监听器、注册一台 iPhone，打印
# 安装 QR 码与一次性密码。
uniclip mobile setup

# 只读命令（daemon 在跑时也可以调）
uniclip mobile status            # 综合视图：功能 + LAN + 已配对设备

# 已配对设备管理
uniclip mobile add --label "My iPhone" \
    [--username my_user] [--password-stdin]
uniclip mobile revoke <device-id>

# 进阶监听器配置。`setup` 已覆盖常用场景，需要手动改地址或配置反向代理时
# 再使用这一组。
uniclip mobile network interfaces
# LAN 形态：宣告内网 IPv4 → 安装 URL 为 http://<IP>:<port>
uniclip mobile network set --ip <LAN_IPV4> [--port 42720] --accept-network-risk
# 反代形态：宣告完整 base URL → 安装 URL/二维码指向 HTTPS 前端（如 Caddy），
# 监听器本身仍是内网明文 HTTP
uniclip mobile network set --url https://clip.example.com --accept-network-risk
uniclip mobile network off       # 只关 LAN 监听器

# 把整个功能彻底关掉（总开关 + 监听器都关；已配对设备记录保留，
# 想清掉用 `revoke`）
uniclip mobile disable

行为约定：

  • 公开的移动端命令都通过后台服务执行。 它们会连接正在运行的服务，或在需要时 自动启动服务，因此运行 setup、add 或 network set 前不需要退出桌面应用。
  • --json 隐含 non-interactive。 不会出任何交互提示。setup 在 non-interactive / JSON 模式下必须显式给 --label、--accept-network-risk； --ip / --port 是可选的高级覆盖项（不给则二维码自动携带所有检测到的 网卡）；--username / --password-stdin 仍可选，缺省走自动生成。
  • --password-stdin 从 stdin 读取一行作为密码。用它从密码管理器 或 CI 里管道喂密码，避免泄漏到 shell history。
  • 默认端口 42720（SPEC §3.2）。daemon socket 永远 bind 在 0.0.0.0:<port>，--ip 只决定打印到安装 URL 的 IPv4。
  • network set 必须二选一给出 --ip <IP> 或 --url <URL>。 --ip 得到 LAN 形态 http://<IP>:<port>；--url 写入完整 base URL（scheme + host + 可选 port，如 https://clip.example.com），让安装 URL / 二维码 指向 TLS 反向代理（Caddy、nginx 等），而监听器本身仍是内网明文 HTTP。 两者互斥，设一个会清掉另一个；mobile status 会反映当前生效的那个。

完整的端到端配置教程（监听器风险提示、iOS 快捷指令安装、密码轮换）见 移动端同步指南。

调试与日志导出

uniclip debug status                       # 当前是否开启持久化调试日志？
uniclip debug on                           # 开启更详细的本地日志
uniclip debug off                          # 恢复正常日志档位
uniclip debug capture status               # 查看连接抓取状态
uniclip debug capture start                # 开始一次有时限的详细抓取
uniclip debug capture stop                 # 停止当前抓取
uniclip debug export-logs                  # 把最近 24h 打包到下载目录
uniclip debug export-logs --since-hours 6  # 收窄时间窗口

debug on / off 会把更详细的日志档位持久化，跨重启生效；status 报告当前生效的档位，以及是否还需要重启才能完全生效。剪贴板内容仍然 不会被记录。

export-logs 把最近时间窗口（默认 24h）内的 GUI、daemon、CLI 日志打 成一个 zip 放到下载目录 —— 这是收齐 issue 报告所需材料最快的方式。 GUI 里在 设置 → 常规 下有同样的操作。

连接抓取只应用于短时间排障。用 debug capture status 查看当前抓取，问题复现完成后 立即停止，再按支持人员的要求导出日志。

升级检测游标

uniclip upgrade            # 不带子命令时打印状态
uniclip upgrade status     # 与不带子命令时等价
uniclip upgrade ack        # 把游标推进到当前构建版本

查看或推进升级检测游标 —— 用于手动验证升级模块。普通用户基本用不到。

退出码

uniclip 使用稳定的退出码（在 src/exit_codes.rs 中定义）。0 表示成功，非零值对应不同的失败类别 （配置、网络、配对等）且跨版本保持稳定。脚本应基于退出码判断成败，而不是解析人类可读输出。

uniclip get 额外使用 6（没有条目匹配 selector）和 7（条目存在但 payload 不可用——Lost 或尚未下载，需在源设备重发）。

最新的子命令列表请直接运行 uniclip --help —— 二进制自带的 help 是权威来源。

快速上手

从终端创建或加入空间、发送内容并查看历史。

高级配置

用于隔离 profile、无头节点、网络部署和诊断的环境变量。

本页目录

空间加入请求成员移除成员设备信任变化按成员设置同步发送与监听发送和接收文件读取已同步的条目搜索移动端同步调试与日志导出升级检测游标退出码