快速上手

uniclip 是 UniClipboard 的终端客户端。它与桌面应用连接同一个后台服务，因此 CLI 和 GUI 可以使用同一个 profile 与空间。需要后台服务的命令发现它尚未运行时，会自动启动同版本的 uniclipd。

如果 uniclip --version 还不能运行，请先阅读安装 CLI。

全局参数

这些参数可用于所有公开命令：

参数	作用
`--json`	返回便于脚本处理的 JSON。
`-v`, `--verbose`	在终端显示更多诊断信息。
`--profile <NAME>`	使用隔离的数据、安全存储条目和网络身份。

桌面应用已经打开时，不需要为 CLI 单独设置 profile。只有在确实要运行一个完全独立的实例时才使用 --profile，例如在一台电脑上模拟两台测试设备。

创建或加入空间

先创建空间，再为另一台设备生成邀请：

uniclip space init
uniclip space invite

两个命令都会引导你输入所需信息。邀请码是短期秘密，只能使用一次。

在新设备上运行加入命令，然后按提示粘贴邀请码：

uniclip space join

非交互调用需要显式传入邀请码：

uniclip space join --code <INVITATION_CODE>

命令还会要求输入空间口令，并等待最终结果。成功后查看成员列表：

uniclip member list

脚本只想等到加入请求被接受、不想等待最终结果时，可以加 --no-wait，之后再查看或取消请求：

uniclip space join status
uniclip space join cancel

Ctrl-C 只会停止本地等待，不会取消加入请求。

发送和读取内容

# 把文本发送给在线的已配对设备
uniclip send "hello from the CLI"

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

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

# 从标准输入读取文本
printf 'hello from a pipe' | uniclip send

# 打印本机已经同步的最新文本或链接
uniclip get

# 等待下一条同步内容，输出后退出
uniclip get --wait

# 等待下一条内容，通过当前终端复制后退出
uniclip get --copy --wait

# 只列出最近条目，不下载内容
uniclip get --list -n 20

# 搜索历史
uniclip search "报告"

get 默认读取已经进入本机历史的内容并立即返回。get --wait 只处理命令订阅建立后到达的下一条匹配内容并退出，可与 --type 或 --id 组合。交互终端会为已匹配的文件显示真实接收进度；进度只写入 stderr，因此 stdout 仍可安全用于管道和 JSON。 watch 会持续等待并打印之后收到的内容，直到按下 Ctrl-C：

uniclip watch

watch 只负责观察，不会把内容写入系统剪贴板。

发送或接收文件

# 显式强制文件模式
uniclip send --file ./report.pdf

# 从 stdin 逐行读取完整文件路径
printf '%s\n' ./report.pdf './images/cover art.png' | uniclip send --file

# 等待下一条内容；文件保存到 ./inbox
uniclip get --wait --out ./inbox

现有普通文件会被自动识别。文件传输由后台服务负责，所有相关目标进入终态后命令会自动退出。-f / --file 没有位置路径时，stdin 表示文件路径列表，而不是文件内容；空行会被忽略，所有路径会在发送前完成校验，重复路径只发送一次。可以重复使用 --peer 限制目标，按 Ctrl-C 可取消等待。

管理守护进程

大多数命令会连接当前 profile 的 daemon，或在需要时自动启动一个实例。明确控制生命周期时可以使用：

命令	作用
`uniclip run`	前台运行，保留信号、日志与 daemon 退出码。
`uniclip run --server`	前台运行无头节点，不读写系统剪贴板。
`uniclip service start`	需要时安装并启动用户服务，开启登录启动。
`uniclip service status`	分别报告注册、运行与 HTTP 健康状态。
`uniclip service restart`	使用已保存选项重启，并恢复登录启动。
`uniclip service stop`	停止并关闭登录启动，保留服务定义。
`uniclip stop`	停止当前 profile 的独立 daemon。
`uniclip space status`	查看空间、网络和信任状态。

用户服务支持 Linux systemd 和 macOS launchd；Windows 服务命令会明确报未支持。 service start --server 选择无头模式。生产服务要求将匹配的 uniclip 和 uniclipd 安装到稳定的同一目录，拒绝临时构建、Git 工作树和便携安装。

run 拒绝已有 daemon，包括桌面应用拥有的实例；应显式停止原所有者，或使用其他 --profile。服务管理的 daemon 用 service stop 停止。服务在用户登录管理器启动时启动，不承诺登录前运行。健康失败与服务要求见命令参考。

uniclip start 已弃用。兼容期内仍默认后台运行并输出迁移提示，--foreground 和 --server 保留旧行为；新脚本应使用 run 或 service start。

在脚本中使用

需要让其他程序读取结果时，加上 --json：

uniclip --json space status
uniclip --json member list
uniclip --json search "报告" --limit 10

为了保持标准输出干净，部分命令会把面向人的状态提示写到标准错误。脚本应读取 JSON 和退出状态，不要匹配终端提示文字。

切换或重建空间

切换到另一个空间时，可读的本机历史会迁移到新空间：

uniclip space join --switch --code <NEW_INVITATION_CODE>

命令会先要求确认。只应在受控的非交互流程中添加 --yes。如果有本机记录无法读取，命令默认停止；使用 --preserve-unreadable-history 可以保留这些记录，避免在切换时丢弃。

要把当前设备重建为只包含本机的新空间：

uniclip space reset --yes

这会永久废弃旧的配对、信任和同步关系，但保留本机历史、已完成文件、设置、设备身份和解锁能力。所有设备都需要重新配对。这不是恢复出厂设置。

重建不会改变当前口令。要修改口令，请使用 uniclip space change-passphrase（仅限已解锁且本机是唯一成员的空间）。uniclip space init 只用于还没有空间的设备，重建后再运行会提示 “setup has already been completed”。

所有公开命令和参数见 CLI 参考。