pixiv-cli

Pixiv CLI / MCP / Go SDK

Go 版 Pixiv 工具集：默认作为 pixiv CLI 使用，需要 MCP 时显式运行 pixiv mcp；Go 程序可导入公开 pkg/pixiv。

它优先复用 Pixiv App API，支持搜索、详情、排行、推荐、下载、多账号 refresh token 管理，以及 MCP stdio server。未配置 refresh token 时，默认对搜索、详情、排行、用户搜索和下载启用匿名 Pixiv web/ajax API fallback。它不是 HTTP 服务，也不提供 Discover、Probe、Capabilities、RSS 或 crawler。

源码按 CLI controller、application services、bootstrap、public SDK、config、Pixiv facade/source、download、MCP server 分包；账号存储在 internal/storage/auth，基础工具按 internal/utils/* 子包组织。公开 SDK 是具体 *pixiv.Client，内部协议实现分为 internal/pixiv/appapi、webapi、oauth、resource。

用户可感知变化记录在 CHANGELOG.md。SDK 契约见 pixiv-sdk-interface.md，架构边界见 ADR 0009。

安装与构建

发布状态：受支持 binary 的 Ed25519 公钥、key ID 与 fingerprint 已提交到 internal/bootstrap/release_trust.go；公开 source/tap repositories、 受保护 release Environment 与隔离 credentials 已配置。v0.1.1 已作为正式 GitHub Release 发布，包含六个 平台 archive、checksum 与签名清单；stable Homebrew formula 已推送。后续版本仍必须通过同一套 tag、签名、资产与 Homebrew 门禁后才可作为可用下载来源。

从源码构建

sh scripts/build.sh

受支持的源码构建需要 Go 1.26.3、CGO_ENABLED=1、目标平台可用的 C linker，以及与 目标匹配的 Rust ugoira staticlib。它会输出 build/pixiv 或 build/pixiv.exe。Windows 可通过 Git Bash、MSYS2 或 WSL 运行构建命令。

当前工作树已保存 darwin/linux/windows × amd64/arm64 的六个 runner-verified staticlib 与同源 manifest.json；scripts/build.sh 会先校验 source digest、target/path 与每个库的 SHA-256，再构建 本机 binary。完整要求、证据回填流程和失败含义见开发流程。

Go 安装

正式 tag 发布后，使用精确 tag 安装：

go install github.com/FlanChanXwO/pixiv-cli/cmd/pixiv@vX.Y.Z

它仍使用本机 Go、cgo、C linker 和该 target 的 committed staticlib。六目标库与 manifest 已完整， 例如当前正式版本可使用 @v0.1.1；后续版本始终使用其精确 tag，而不是分支名。

Homebrew

正式 stable Release 和真实 tap 均通过 audit/安装验证后，macOS/Linux 用户可安装：

brew install FlanChanXwO/tap/pixiv-cli

未来 beta/pre-release 通道使用：

brew install FlanChanXwO/tap/pixiv-cli-beta

两个 formula 都安装同名 pixiv，因此相互冲突；它们只下载已验证的 macOS/Linux Release 资产，不引入 ffmpeg 依赖。当前 stable pixiv-cli formula 已在公开 tap；beta formula 只随 后续 pre-release 发布。

直接下载

发布流程会为 darwin、linux、windows 的 amd64/arm64 生成六个固定名称的 archive： pixiv-cli_<version>_<os>_<arch>.tar.gz（Windows 为 .zip），以及 checksums.txt 与 Ed25519 签名的 checksums.json。v0.1.1 已提供完整资产；后续版本只有在同一发布门禁完成后才应作为 可供信任的直接下载来源。

当前 Release 不包含 Apple notarization 或 Windows Authenticode。即使从已验证 Release 下载，macOS Gatekeeper 或 Windows SmartScreen 仍可能显示系统信誉提示；请只从项目的 GitHub Release 页面取得资产，核对版本、checksum 和签名说明，切勿绕过不明来源的警告。

Go SDK

外部 Go 程序直接使用具体 *pixiv.Client，并在自己的 adapter 中定义业务窄接口：

client, err := pixiv.OpenDefault(pixiv.Options{})
if err != nil { /* handle local auth/config failure */ }
result, err := client.SearchIllust(ctx, pixiv.SearchIllustRequest{Word: "初音ミク"})
_ = result

NewClient 只使用显式 transport/token/options，不读取本地状态；OpenDefault 每个公开操作读取一次当前 auth/config snapshot。调用方负责采集模式、budget、filter、cursor 持久化、入库、调度和自己的 HTTP API。完整模型、资源流、错误与分页契约见 SDK 接口。

获取 refresh token

PIXIV_REFRESH_TOKEN 必须是 Pixiv App API OAuth refresh token。网页 Cookie 里的 PHPSESSID、device_token 不能直接用。

推荐用 CLI 浏览器 OAuth 登录，并直接保存到本地账号：

pixiv auth login

auth login 流程：

默认浏览器打开时，macOS 会优先安装/注册一个本地 PixivCLIURLHandler.app，只把 Pixiv 返回的 pixiv://account/login?... URL 转交给本轮 CLI loopback，不读取 cookie、token 或浏览器存储。若本机无法注册该 helper，CLI 才退回专用 Chromium/Edge 用户资料目录并通过 DevTools 只监听 Pixiv OAuth 请求 URL；该 fallback 不安装扩展、不点击页面、不读取 cookie 或 token。macOS 仍保留 Microsoft Edge、Chrome、Chromium 与 Safari 标签页/浏览器状态文件的只读观察；遇到 Pixiv post-redirect 授权接力页时，会校验其 return_to 属于本轮 OAuth，然后等待 Pixiv 触发 pixiv:// handoff，不再自动重开白页。浏览器可能停留在白色 relay 页，是否成功以终端最终输出为准。若手动粘贴 Pixiv relay URL，CLI 会打开该 relay URL 一次。若 Pixiv 未生成 callback，CLI 不会伪造成功，仍可使用终端或本地页面手动回填。

浏览器使用的系统代理不会自动传给 Go CLI。若 Pixiv token 端点在当前网络下需要代理，请先配置：

pixiv config set https_proxy http://127.0.0.1:7890

也可以只给本次网络命令临时覆盖代理：

pixiv auth login --proxy http://127.0.0.1:7890

--proxy URL 与 --no-proxy 都只影响当前命令，不写入 config.toml；两者不能同时使用。--no-proxy 会清空本次命令的代理，即使环境变量或配置里存在 https_proxy。

真实登录依赖 Pixiv OAuth 网页流程可用；自动化测试使用 fake OAuth server，不访问真实 Pixiv。

CLI 使用

先登录并保存一个账号：

pixiv auth login

高级/脚本场景也可以导入已有 token：

printf '%s\n' 'YOUR_REFRESH_TOKEN' | pixiv auth add

也可以直接传 token，但 --token 参数可能进入 shell history：

pixiv auth add --token 'YOUR_REFRESH_TOKEN'

常用命令：

pixiv auth list
pixiv auth use 12345678
pixiv auth check
pixiv config path
pixiv config get download_path
pixiv config set download_path ~/Downloads/pixiv
pixiv config unset https_proxy

pixiv version
pixiv version --json
pixiv --version
pixiv update --check
pixiv update --check --json

pixiv search "初音ミク"
pixiv search "初音ミク" --json
pixiv detail 123456
pixiv ranking --mode day
pixiv recommended
pixiv download 123456 789012

账号认证保存到 os.UserConfigDir()/pixiv/auth.json，账号 key 是 Pixiv UID；全局配置保存到 os.UserConfigDir()/pixiv/config.toml，两个文件权限都固定为 0600。输出默认给人读；加 --json 输出机器可解析 JSON。 CLI 使用 Cobra/pflag，选项可以写在位置参数前后，例如 pixiv auth check 12345678 --json 和 pixiv search "初音ミク" --json 都是正式支持的写法。

CLI 命令表

auth login 参数

数据命令参数

通用参数

config 支持的键

环境变量

认证优先级：--refresh-token > --uid/deprecated --profile > PIXIV_REFRESH_TOKEN > auth.json.default_user_id。

设置类字段优先级：命令行 flag > 环境变量 > config.toml > 默认值。代理的命令行覆盖只支持 --proxy URL / --no-proxy，且不会持久化。

匿名 web fallback

当 --refresh-token、PIXIV_REFRESH_TOKEN 和默认账号都没有提供 refresh token，且 web_fallback_enabled=true 时，下列能力自动走 Pixiv web/ajax API：search、detail、ranking、download，以及 MCP tools search_illust、illust_detail、illust_ranking、search_user、download、get_thumbnail_base64。

有 refresh token 时仍优先使用 App API；token 无效、App API 网络错误或服务端错误不会自动 fallback，会直接暴露真实错误。

匿名 fallback 的差异：

• search_user 不是 Pixiv 官方用户搜索；它通过 web 作品搜索结果按 userId 去重，返回“相关作品作者”。
• 静态单页/多页下载使用 /ajax/illust/{id}/pages 的 original URL。
• ugoira 下载使用 /ajax/illust/{id}/ugoira_meta 的 originalSrc zip 和 frames；受支持的发行构建通过内置 Rust encoder 生成 GIF/APNG，运行时不依赖 ffmpeg。
• web fallback 不新增专用代理环境变量，继续使用 --proxy / --no-proxy、https_proxy / HTTPS_PROXY 或 pixiv config set https_proxy ...。

关闭方式：

pixiv config set web_fallback_enabled false

版本与更新

pixiv version 输出可读的版本、commit 与构建日期；pixiv version --json 的 stdout 是只含 version、commit、build_date 的 JSON。根 pixiv --version 适合快速检查版本。

pixiv version
pixiv version --json
pixiv --version

显式更新先检查再安装；检查可使用 JSON，而实际安装不接受 --json：

pixiv update --check
pixiv update --check --json
pixiv update --check --prerelease
pixiv update --proxy http://127.0.0.1:7890

开发构建显示 dev 并拒绝自更新。正式安装时，更新器会识别 Homebrew stable/beta、go install 或 Release binary：stable/beta 按 --prerelease 在两个相互冲突的 formula 间切换；若切换 安装失败，会显式尝试恢复原 formula 并报告原错误和恢复结果。go install 使用精确 Release tag；Release binary 在下载前校验 Ed25519 签名的 checksum 清单和 archive SHA-256，再预检 pixiv version --json 并原子替换可执行文件。

受支持 binary 已内置 production Ed25519 public key/key ID/fingerprint；私钥只保存在受保护的 release Environment 与受控 macOS Keychain 恢复副本。v0.1.1 是已发布的受签名 Release； pixiv update --check 仍只是只读检查，不能替代对选中版本资产、checksum 与签名的安装验证。

普通 CLI 命令成功后会尽力检查 stable 更新。它跳过 MCP、help、version、update 与开发构建， 对同一用户 cache 最多每 24 小时查询一次，并为自动检查设定最多 3 秒的等待时间。发现新版本或 检查失败只写 stderr（失败为 warning），不改变业务命令退出码，也不会污染 JSON stdout 或 MCP JSON-RPC stdout。可关闭自动检查：

pixiv config set update_check_enabled false

MCP 使用

MCP stdio server 需要显式启动：

PIXIV_REFRESH_TOKEN=... \
DOWNLOAD_PATH=./downloads \
FILENAME_TEMPLATE="{author} - {title}_{id}" \
./build/pixiv mcp

MCP 的代理覆盖是启动期设置：

./build/pixiv mcp --proxy http://127.0.0.1:7890
./build/pixiv mcp --no-proxy

未设置 PIXIV_REFRESH_TOKEN 时，pixiv mcp 会先回退到 auth.json.default_user_id；如果仍没有 refresh token 且 web_fallback_enabled=true，支持匿名 fallback 的 MCP tools 会直接使用 Pixiv web/ajax API。真实 token 写在 inline 环境变量里也可能进入 shell history；长期使用建议通过 MCP client 的私密环境配置或本地账号管理。

日志写入 stderr，stdout 保留给 MCP JSON-RPC。

MCP client 配置示例：

{
  "mcpServers": {
    "pixiv-server": {
      "command": "/absolute/path/to/pixiv-cli/build/pixiv",
      "args": ["mcp"],
      "env": {
        "PIXIV_REFRESH_TOKEN": "your refresh token or cookie with refresh_token=...",
        "DOWNLOAD_PATH": "./downloads",
        "FILENAME_TEMPLATE": "{author} - {title}_{id}"
      }
    }
  }
}

命令概览

CLI 命令：

• auth add/login/list/remove/use/check
• config path/get/set/unset
• version
• update
• search
• detail
• ranking
• recommended
• download
• mcp

MCP tools：

set_download_path, download, refresh_token, set_refresh_token, download_random_from_recommendation, search_illust, illust_detail, illust_related, illust_ranking, search_user, illust_recommended, trending_tags_illust, illust_follow, user_bookmarks, user_following, and get_thumbnail_base64.

开发验证

go test ./...
sh scripts/build.sh
./build/pixiv --help
./build/pixiv mcp --help
PIXIV_E2E_WEB_API=1 PIXIV_WEB_API_PROXY=http://127.0.0.1:7890 go test ./test/e2e -run WebAPIFallbackReal -count=1 -v

真实 Pixiv web fallback e2e 默认跳过；只有设置 PIXIV_E2E_WEB_API=1 时才会联网。