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 为每次安装维护一个稳定的设备 ID，存储在 ~/.pikpak/.device.json 中（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                          # 设备流（二维码 + 验证 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 和代码（或二维码）

使用 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 驱动的注册，请运行不带 -F 的 pikpak auth register（它会交互式轮询），或者让用户在浏览器中注册，然后使用 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 的值返回 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`	文件来源：torrent 的 `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 意味着 JSON 输出，即使没有 -F；-F yaml 将相同的响应体转换为 YAML。此模式没有人类可读的表格。
ls --raw 是每个页面的一个请求，而不是每个文件。 与普通 ls 相同的 -p / -l / -t / --type 标志和服务端过滤器（未删除，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 键。
命名与简化格式不同。 原始格式使用 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 的存在。

使用技巧：

# 时长超过一小时的视频（一次 API 调用——绝不对文件夹循环使用 `get`）
pikpak ls --raw | jq -r '.files[] | select((.params.duration // "0" | tonumber) > 3600)
  | "\(.name)\t\(.params.duration)s"'

# 4K 文件

…

PikPak CLI 云存储操作技能