命令列工具
從 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 風格的全螢幕互動介面：邊輸入邊過濾，按 Enter 即複製選中條目。
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 pairtoken 會把本機的配對碼顯示出來，碼本身獨占 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 使用指南。