命令行工具

从 2.2.0 版本开始，每一份 CrossPaste 桌面安装包都自带了一个原生命令行工具 crosspaste。复制、粘贴、搜索历史、交互式挑选、实时订阅新内容、配对设备，甚至在没有图形界面的服务器上运行——这一切都可以在终端和脚本里完成。

为什么终端用户需要它

剪贴板是你每天用得最多、却最难被脚本触达的系统能力。CrossPaste CLI 把它变成了一个标准的命令行公民：

• 管道即复制：git log -1 --format=%H | crosspaste，命令输出直接进入剪贴板历史，并同步到你所有已配对的设备。
• 历史可编程：剪贴板历史不再只是一个 GUI 面板，而是可以 grep、jq、xargs 的数据源。
• 跨设备打通：在 SSH 连接的服务器上复制一段日志，它会出现在你的 Mac 和手机上。
• 遵循 Unix 惯例：输出走 stdout、提示走 stderr、退出码语义清晰、支持 --json、尊重 NO_COLOR 和 $EDITOR。你熟悉的一切习惯在这里都成立。

它是用 Kotlin/Native 编译的独立二进制，启动飞快，没有 JVM 预热，专为脚本和管道场景设计。

安装

CLI 已经打包在桌面安装包里，只差把它加入 PATH：

平台	命令名	安装方式
macOS	crosspaste	首次启动 App 时弹窗一键安装；或在 扩展 → 命令行 中随时安装/修复
Windows（安装包 / 商店版）	crosspaste-cli	自动配置，开箱即用
Windows（zip 版）	crosspaste-cli	App 内一键添加到 PATH（之后需新开终端）
Linux（deb）	crosspaste	自动安装 /usr/bin/crosspaste
Linux（tarball）	crosspaste	手动软链：sudo ln -s <安装目录>/lib/app/bin/crosspaste-cli /usr/local/bin/crosspaste

Windows 上为什么叫 crosspaste-cli？

在 Windows 上 crosspaste 命令保留给了图形界面 App，命令行工具因此叫 crosspaste-cli。本文示例统一写 crosspaste，Windows 用户替换命令名即可。

装好后验证一下：

crosspaste status

它会显示 App 版本、监听状态、设备数和历史条数。这是唯一一个永远不会自动拉起 App 的命令，App 未运行时以退出码 3 退出，很适合放进健康检查脚本。

30 秒上手

三个最常用的操作，各有一个单字母别名（c / p / h）：

# 复制：参数、或管道输入
crosspaste copy "hello world"
echo "hello world" | crosspaste     # 有管道输入时连 copy 都可以省略

# 粘贴：输出最新一条到 stdout
crosspaste paste

# 历史：最近 20 条
crosspaste history

没错——管道进来的内容不需要任何子命令，git log | crosspaste 就能把日志存进历史。这是整个 CLI 里最顺手的一条设计。

如果运行命令时 App 没有启动，交互式终端下 CLI 会先询问是否启动；在脚本里则直接以退出码 3 失败，不会卡住等输入。用 --start / --no-start 可以显式控制这个行为。

搜索与筛选历史

history 支持和 App 内搜索窗口相同的筛选条件：

crosspaste history TODO                        # 关键词搜索
crosspaste history --type link --limit 50      # 按类型筛选：text/link/image/file/html/rtf/color
crosspaste history --tag work --sort oldest    # 按标签、按时间正序

输出格式为脚本而生：

crosspaste history TODO --format json | jq '.items[].preview'   # 完整元数据
crosspaste history --format id | xargs -n1 crosspaste delete    # 只输出 id，批量清理

pick：全屏模糊搜索选择器

crosspaste pick 会打开一个 fzf 风格的全屏交互界面：边输入边过滤，回车即复制选中条目。

crosspaste pick

常用按键：

按键	作用
↵	复制选中条目并退出
^e	在 $EDITOR 中编辑选中条目
^t / ^g	按类型 / 标签筛选
^s	切换时间排序
⇥	开关预览面板
?	帮助
esc	关闭选择器 / 清空查询 / 退出

取消时退出码为 130，与 fzf 惯例一致。

精确取回内容：paste 的三种形态

crosspaste paste             # 默认：友好的摘要展示
crosspaste paste --summary   # 纯文本渲染（HTML/RTF 会转成文本）
crosspaste paste --raw       # 原始内容：HTML/RTF 输出源码，图片直接输出字节

--raw 让剪贴板里的图片变成了普通的字节流：

crosspaste paste --raw > screenshot.png                   # 截图存盘
crosspaste paste --raw | magick - -resize 50% small.png   # 直接进管道处理

配合 --no-newline 可以保证不多写一个换行符，重定向到文件时内容分毫不差。

Windows 用户注意

Windows PowerShell 5.1 的 > 会把输出重编码为 UTF-16，破坏二进制数据。保存图片请用 cmd /c "crosspaste-cli paste --raw > shot.png"，或升级到 PowerShell 7.4+。

终端里直接看图

在支持的终端里，paste 和 pick 的预览面板会把剪贴板图片以真实像素内联渲染——支持 Kitty / Ghostty（Kitty 协议）、iTerm2 / WezTerm（OSC 1337）以及 Windows Terminal 等 sixel 终端。tmux 下会自动回退为打印文件路径。

watch：实时订阅剪贴板流

watch 会持续输出新产生的剪贴板条目——包括从其他设备同步过来的。默认每条一行、内容干净，天生为管道准备：

crosspaste watch --type link | xargs -n1 yt-dlp        # 手机上复制视频链接，电脑自动下载
crosspaste watch --format json | jq '.preview'          # 完整元数据流
crosspaste watch --format id | while read -r id; do     # 逐条取原始字节归档
  crosspaste paste "$id" --raw > "paste-$id.txt"
done

想象一下：在手机上复制一个链接，几秒后你的工作站自动开始处理它。这就是「剪贴板 + 同步 + 管道」组合出来的自动化空间。

注意 watch 是实时流而非持久队列——CLI 未运行期间产生的条目不会补发。App 重启后它会自动重连。

在终端里配对设备

设备配对也不再需要图形界面：

crosspaste pair

它会列出局域网内可配对的设备，选中后在终端里输入对方屏幕上显示的 6 位验证码即可（输入是隐藏的）。

对端如果是台没有屏幕的机器怎么办？这正是 token 命令存在的意义：

# 在无界面的服务器上（比如通过 SSH）
crosspaste token --wait

# 在你的电脑上
crosspaste pair

token 会把本机的配对码显示出来，码本身独占 stdout（CODE=$(crosspaste token) 可以直接取值），说明文字全部走 stderr。配对码每 30 秒轮换，--wait 会等待配对请求到来并保持接受窗口开启。

无界面运行：服务器上的 CrossPaste

CrossPaste 桌面 App 支持 --headless 参数以守护进程方式运行（无图形环境时自动启用）。这意味着你可以在一台 Linux 服务器上跑一个 CrossPaste 节点：

crosspaste --start status    # CLI 会在无 GUI 环境下自动以 headless 模式拉起 App

配合 systemd user unit 可以做到开机自启、登出保留。此后这台服务器就成了你剪贴板网络里的一个节点：crosspaste copy 写入的内容会同步到所有设备，watch 也能收到其他设备的新条目。

唯一的限制符合直觉：headless 模式下没有系统剪贴板，所以「把某条历史复制回系统剪贴板」这一个动作不可用，其余命令全部正常。

那些让人安心的细节

好的命令行工具体现在细节里，这些是我们特意做对的地方：

• 本地通信零暴露：CLI 通过 Unix domain socket 上的本地 HTTP API 与 App 通信，socket 文件权限 0600，没有 TCP 端口，网络上的其他设备无法触达。
• stdout 纯净：所有提示、进度、询问都走 stderr，stdout 只有命令输出本身，重定向和管道永远拿到干净的数据。
• 退出码有语义：0 成功，1 错误，2 用法错误，3 App 未运行。脚本可以精确分支。
• --json 全局可用：任何命令都能输出机器可读的 JSON。
• shell 补全：source <(crosspaste --generate-completion zsh)，bash 和 fish 同样支持。
• 尊重你的环境：$VISUAL / $EDITOR、NO_COLOR、COLUMNS，非 TTY 时自动关闭颜色。

常用命令速查

命令	作用
crosspaste copy (c)	复制文本 / 读取管道输入
crosspaste paste (p)	输出条目内容（--raw / --summary）
crosspaste history (h)	搜索筛选历史
crosspaste pick	全屏模糊搜索选择器
crosspaste edit	在 $EDITOR 中编辑条目
crosspaste delete	删除条目
crosspaste watch	实时订阅新条目流
crosspaste tags	管理标签
crosspaste devices	列出已配对设备
crosspaste pair / token	发起配对 / 显示本机配对码
crosspaste config	查看和修改配置
crosspaste status	查看运行状态（从不自动启动 App）

完整的命令参考、headless 部署指南和更多脚本示例，见官方 CLI 使用指南。