PikPak CLI 操作技能
透過 pikpak 命令列工具操作 PikPak 雲端儲存。
安裝 pikpak
根據您的作業系統選擇安裝方式：
macOS / Linux：
curl -fsSL https://download.mypikpak.com/cli/install.sh | bash
Windows（PowerShell）：
irm https://download.mypikpak.com/cli/install.ps1 | iex
Homebrew：
brew install pikcloud/tap/pikpak-cli
安裝完成後，執行 pikpak version 以確認。
使用邀請者的邀請碼 — 安裝程式會將其記錄下來，供此電腦下次執行
pikpak auth register 使用，不會聯絡邀請 API：
curl -fsSL https://download.mypikpak.com/cli/install.sh | bash -s -- --affiliate <code>
$env:PIKPAK_AFFILIATE="<code>"; irm https://download.mypikpak.com/cli/install.ps1 | iex
brew install pikcloud/tap/pikpak-cli && pikpak auth register --affiliate <code>
安裝程式會將邀請碼儲存在獨立的純文字 affiliate 檔案中；無需 Python 或
JSON 解析器，且絕不會讀取或修改 settings.json。寫入失敗時會發出警告，
但不會導致安裝失敗或覆蓋先前的邀請碼。若發生此情況，請使用
pikpak auth register --affiliate <code> 傳入邀請碼。
pikpak skill install 會將此文件寫入電腦上所有 AI 程式碼代理程式的技能目錄
（Claude Code、Codex、Gemini CLI、opencode、Cursor、goose、iFlow、Qwen Code...）。
當此文件與已安裝的二進位檔不一致時，請在 pikpak update 後執行此命令；
pikpak skill ls 會顯示其安裝位置以及是否為最新版本。
環境變數
| 變數 | 說明 | 預設值 |
|---|---|---|
PIKPAK_DIR | 憑證目錄 | ~/.pikpak |
PIKPAK_CREDENTIALS | OAuth 憑證檔案的完整路徑 | ~/.pikpak/.credentials.json |
PIKPAK_TOKEN | 個人存取權杖；優先於任何已儲存的憑證 | 未設定 |
PIKPAK_PAT_PATH | 由 auth token 儲存的 PAT 檔案的完整路徑 | ~/.pikpak/.pat.json |
PIKPAK_VERSION | 安裝時指定的版本 | 最新版 |
PIKPAK_INSTALL_DIR | 安裝目錄 | ~/.local/bin（macOS/Linux），%USERPROFILE%\.pikpak（Windows） |
PIKPAK_NO_UPDATE_NOTIFIER | 設為 1 可停用自動更新檢查與提醒；明確的 version --check 和 update 仍可正常運作 | 未設定 |
PIKPAK_NO_LOG | 設為任何非空值（例如 1）可覆蓋 config log，永不記錄診斷日誌 | 未設定 |
PIKPAK_NO_SKILL_SYNC | 設為任何非空值可阻止 pikpak update 重新整理已安裝的代理技能 | 未設定 |
PIKPAK_AFFILIATE | 安裝時由 install.sh / install.ps1 讀取的邀請碼（CLI 本身不會讀取它） | 未設定 |
憑證優先順序：PIKPAK_TOKEN → pikpak auth token 儲存的 PAT → pikpak auth login 的 OAuth 憑證。
裝置身分識別：CLI 在 ~/.pikpak/.device.json 中為每次安裝保留一個穩定的裝置 ID
（X-Device-Id）。它會在所有登入方式中重複使用，並在權杖輪替和 auth logout 後仍然存在；
刪除它會使此機器對 PikPak 的風險控制系統顯示為全新的裝置。
驗證
大多數命令需要先登入。憑證儲存在 ~/.pikpak/.credentials.json 中。
pikpak auth login # 自動偵測登入方式（可用瀏覽器則用瀏覽器，否則使用裝置流程）
pikpak auth login -m browser # 瀏覽器 OAuth 登入（開啟瀏覽器，30 秒無回應則回退至裝置流程）
pikpak auth login -m browser --no-launch-browser # 瀏覽器 OAuth 登入（列印 URL，不自動開啟）
pikpak auth login -m device # 裝置流程（QR 碼 + 驗證 URL + 自動輪詢）
pikpak auth login -m device -F json # 裝置流程：輸出驗證資訊為 JSON 後結束（不輪詢，適用於 AI）
pikpak auth login --continue <device_code> # 輪詢裝置代碼狀態一次後結束（搭配 -F json 使用）
pikpak auth login --force # 即使已驗證也重新登入
pikpak auth login -l "my-session" # 設定自訂工作階段標籤
pikpak auth login --scope files:manage,cloud_download # 預先選擇 OAuth 範圍（逗號分隔）
pikpak auth register # 註冊新帳號（與登入相同的瀏覽器/裝置流程）
pikpak auth register --affiliate <code> # 使用聯盟/邀請碼註冊
pikpak auth register --affiliate= # 跳過安裝程式儲存的邀請碼來進行此註冊
pikpak auth register -m device # 強制使用裝置流程註冊
pikpak auth token <token> # 儲存個人存取權杖以供非互動使用
pikpak auth logout # 清除本地工作階段；可在離線或憑證損壞/過期時運作（無法從環境中移除 PIKPAK_TOKEN）
pikpak auth status # 登入狀態 + 帳戶面板：身分、VIP、儲存空間配額（對指令稿加上 -F json）
支援的 --scope 識別碼：files:read、files:write、files:manage、files:purge、
cloud_download、share、invite、account。省略 --scope 不會傳送任何範圍，
讓授權伺服器套用其預設值。
AI 代理登入指南：密碼登入已不再支援。對於非互動/AI 環境，請使用裝置流程：
- 執行
pikpak auth login -m device -F json以取得device_code、verification_uri、user_code、expires_in、interval- 向使用者顯示驗證 URL 和代碼（或 QR 碼）
- 使用
pikpak auth login --continue <device_code> -F json輪詢，直到status為success如果環境支援瀏覽器（具有 GUI 的 macOS/Linux），則
pikpak auth login（自動偵測）或pikpak auth login -m browser無需任何旗標即可運作。登入會先檢查現有憑證；使用--force建立新工作階段。完全非互動的替代方案：
pikpak auth token <PAT>，或匯出PIKPAK_TOKEN=<PAT>。註冊注意事項：
pikpak auth register -F json會列印signup_uri、handoff_code、qr_png_path、expires_in（以及每當有邀請碼作用中時 — 無論是旗標還是記錄的 — 的affiliate）， 然後結束 — 它不會回傳device_code，因此無法用--continue輪詢。 對於 AI 驅動的註冊，請執行pikpak auth register（不加-F）（它會互動式輪詢）， 或讓使用者在瀏覽器中註冊，然後使用pikpak auth login。
命令參考
檔案瀏覽
根目錄 ID 為空字串 ""，而非 / 或 /root。
pikpak ls # 列出根目錄
pikpak ls <folderID> # 列出指定資料夾（位置參數）
pikpak ls -p <folderID> # 相同，透過旗標（若兩者皆提供，位置引數優先）
pikpak ls --type file # 僅顯示檔案（伺服器端種類過濾，也適用於 --raw）
pikpak ls --type folder # 僅顯示資料夾（伺服器端種類過濾，也適用於 --raw）
pikpak ls -l 50 # 每頁項目數（--limit，預設 100；伺服器會將低於 10 的值設為下限）
pikpak ls -t <token> # 分頁（--token，來自前一次 ls 的輸出）
pikpak ls -F json # JSON 輸出（AI 偏好：id、parent_id、name、kind、size、mime_type、file_category、modified、hash；對於資料夾以及服務未分類的檔案，會省略 mime_type/file_category）
pikpak ls --raw # 未經修改的 API JSON，包含完整清單：新增 params.duration/width/height、params.url、audit、thumbnail_link、spell_name、apps；size 以位元組為單位
僅列出未進入垃圾桶、已完全處理的檔案。一次 ls 為一頁：從輸出中讀取 next_page_token
並將其與 -t 一起傳回以繼續。-l 是一個頁面大小請求，而非硬性上限 —
對於任何較小的值，服務會回傳 10 個項目，且當資料夾結束時，頁面也可能少於 -l。
檔案搜尋（無法使用）
search 命令在此版本中已停用，因為伺服器端搜尋
API 無法使用。請勿建議或執行 pikpak search；請透過
使用 pikpak ls（可選擇加上 -F json）瀏覽資料夾來尋找檔案。
檔案詳細資訊
pikpak get <fileID> # 基本資訊
pikpak get <fileID> --url-type download # 包含下載 URL
pikpak get <fileID> --url-type play # 包含播放 URL
pikpak get <fileID> --url-type all # 包含所有 URL
pikpak get <fileID> --raw # 未經修改的 API JSON（usage=ALL；忽略 url_type）
get -F json 的欄位：id、name、type（file/folder）、size、mime、hash、created、
modified、phase，以及在 --url-type 要求時新增的 download_url、play_url、play_resolution。請注意命名與 ls 不同：此處為 type/mime，而 ls 為 kind/mime_type。
URL 僅對檔案回傳 — 對資料夾使用 --url-type 僅會回傳中繼資料。
--raw 完全繞過此縮減的形狀 — 請參閱下方的原始 API 輸出。
原始 API 輸出（--raw）
pikpak ls --raw 和 pikpak get <fileID> --raw 會逐字列印 PikPak 磁碟 API 的回應主體
（僅重新縮排）。當您需要的欄位不在上述縮減的 ls / get 形狀中時，請使用它們。
pikpak ls --raw # 完整清單，API 回傳的每個欄位
pikpak ls --raw -p <folderID> -l 500 # 與一般 ls 相同的過濾/分頁旗標
pikpak get <fileID> --raw # 單一檔案，usage=ALL
pikpak ls --raw -F yaml # 相同主體轉換為 YAML
--raw 新增的內容（相對於 ls -F json 的 9 個欄位，每個檔案）：
| 原始欄位 | 意義 | 為何重要 |
|---|---|---|
params.duration | 以秒為單位的播放長度，為字串（"1420"） | 影片長度的唯一來源 — ls 和 get 的預設輸出均無此項 |
params.width / params.height | 以字串表示的像素尺寸（"1920" / "1080"） | 解析度過濾；get --url-type play 僅提供類似 1080p 的標籤 |
params.url | 檔案的來源：對於種子為 magnet:?xt=urn:btih:…，對於連結下載為 http(s) URL | 離線下載來源的唯一記錄 |
params.task_id | 產生此檔案的離線任務 ID | 將檔案連結回 pikpak task get <taskID> |
params.db_modify_time、params.platform、params.platform_icon、params.original_share_id | 服務端中繼資料，存在於每個項目上 | 來源出處 |
size | 以字串表示的原始位元組（"392927574"） | 預設輸出會格式化（375 MB）且無法進行數值比較 |
created_time / modified_time / user_modified_time | 帶偏移的 RFC3339 | 預設輸出為截斷的本地 YYYY-MM-DD HH:MM 文字 |
medias[] | 完整陣列：media_id、media_name、resolution_name、link.url、video.{width,height,duration,bit_rate,frame_rate,video_codec,audio_codec,hdr_type}、audio.{artist,album,sample_rate,…} | 每個可播放的變體加上真實的編解碼器/HDR 中繼資料，而不僅僅是 play 選擇的那一個 |
audit | {status, message, title} | 偵測被封鎖/審查中的資源 |
apps、spell_name、tags、reference_events、thumbnail_link、icon_link、web_content_link、phase、starred、trashed、writable、folder_type、revision、user_id | 其餘 API 欄位 | 縮減形狀丟棄的任何內容，包括未來 API 版本新增的欄位 |
語意 — 使用前請閱讀：
- 逐字。 主體不會重新編碼：欄位順序是 API 的順序，且已簽署連結中的
&會保持為 字面&（絕不會變成\u0026）。可直接輸入jq。 - 始終為結構化。
--raw即使沒有-F也隱含 JSON 輸出；-F yaml會轉換相同的主體。 此模式下不會有可讀的表格。 ls --raw是每個頁面一個請求，而非每個檔案一個請求。 相同的-p/-l/-t/--type旗標以及 與一般ls相同的伺服器端過濾器（未進入垃圾桶、PHASE_TYPE_COMPLETE）。分頁 不變：從原始主體讀取next_page_token並將其與-t一起傳回。提高-l（例如-l 500）以一次呼叫涵蓋大型資料夾，而不是迴圈get。--type可與--raw結合使用。 它是一個伺服器端kind過濾器（drive#file/drive#folder），因此透傳的主體已經僅包含要求的種類，且一個頁面 仍最多包含-l個項目。不再需要用戶端jq過濾.files[] | select(.kind == …)。get --raw總是請求usage=ALL— 最完整的回應 — 因此--url-type會被忽略 且不再需要：medias[].link.url和web_content_link已在主體中。它也會跳過 下載 URL 的活性探測，因此它始終保持為單一讀取請求，且絕不會新增衍生的download_url/play_url/play_resolution金鑰。- 命名與縮減形狀不同。 Raw 使用 API 自己的金鑰：
kind是drive#file/drive#folder（而非file/folder），modified_time（而非modified），starred（而非star）。 - 欄位存在性不保證。
params對於資料夾和非媒體檔案而言不存在或部分存在；medias通常為[]，直到伺服器完成轉碼。請使用select(.params.duration != null)或// "0"預設值進行防護。 - 請勿根據
file_category過濾原始輸出，也請勿依賴mime_type。 API 經常省略file_category（即使是影片也是如此，縮減的ls -F json形狀會推導出它），且mime_type在相當一部分媒體檔案中會回傳為""，因此select(.file_category == "video")和select(.mime_type | startswith("video"))都會 靜態地遺漏真實的影片。原始輸出中可靠的影片測試是params.duration的存在。
使用範例：
# 長度超過一小時的影片（僅需 ONE API 呼叫 — 絕不要對資料夾迴圈使用 `get`）
pikpak ls --raw | jq -r '.files[] | select((.params.duration // "0" | tonumber) > 3600)
| "\(.name)\t\(.params.duration)s"'
# 4K 檔案
...
[輸出已截斷以利翻譯]
雲端下載
pikpak task create <uri> # 從磁力連結、種子或 HTTP URL 建立離線下載任務
pikpak task create <uri> --name <name> # 為任務命名
pikpak task create <uri> --parent <folderID> # 指定儲存目標資料夾
pikpak task create <uri> --mode full # 完整下載模式（預設）
pikpak task create <uri> --mode zipped # 壓縮後下載
pikpak task create <uri> --mode open # 開放下載模式
pikpak task ls # 列出所有任務
pikpak task ls -l 50 # 每頁任務數（--limit）
pikpak task ls -t <token> # 分頁（--token）
pikpak task get <taskID> # 任務詳細資訊
pikpak task get <taskID> -F json # JSON 格式的任務詳細資訊
pikpak task retry <taskID> # 重試失敗的任務
pikpak task delete <taskID> # 刪除任務
pikpak task clear # 清除所有已完成/已失敗的任務
任務建立後會立即回傳，但可能不會立即顯示在 task ls 中。使用 task get <taskID> 檢查狀態。
上傳
pikpak upload <local_path> # 上傳檔案或資料夾
pikpak upload <local_path> --parent <folderID> # 指定目標資料夾
pikpak upload <local_path> --name <name> # 重新命名上傳的檔案
pikpak upload <local_path> --resume # 續傳中斷的上傳
pikpak upload <local_path> --overwrite # 覆蓋同名檔案
pikpak upload <local_path> -F json # JSON 格式的上傳結果
下載
pikpak download <fileID> # 下載檔案
pikpak download <fileID> --dir <path> # 指定下載目錄
pikpak download <fileID> --name <name> # 重新命名下載的檔案
pikpak download <fileID> --resume # 續傳中斷的下載
pikpak download <folderID> # 下載整個資料夾（壓縮為 ZIP 檔案）
檔案管理
pikpak mv <fileID> <folderID> # 移動檔案或資料夾
pikpak cp <fileID> <folderID> # 複製檔案或資料夾
pikpak rename <fileID> <new_name> # 重新命名
pikpak rm <fileID> # 移動到垃圾桶
pikpak rm <fileID> --forever # 永久刪除
pikpak mkdir <folder_name> # 建立資料夾
pikpak mkdir <folder_name> --parent <folderID> # 在指定位置建立資料夾
分享
pikpak share create <fileID> # 建立分享連結
pikpak share create <fileID> --expires <days> # 設定過期天數
pikpak share list # 列出我的分享
pikpak share delete <shareID> # 刪除分享
pikpak share save <share_url_or_code> # 儲存/還原他人的分享
pikpak share save <share_url_or_code> --parent <folderID> # 儲存到指定資料夾
帳號
pikpak account info # 帳號資訊
pikpak account storage # 儲存空間使用情況
pikpak account vip # VIP 狀態與到期日
設定
pikpak config list # 列出目前設定
pikpak config get <key> # 取得特定設定值
pikpak config set <key> <value> # 設定設定值