pixiv-cli

Pixiv CLI · MCP stdio server · Go SDK

English · 简体中文

Install · Quick start · Interfaces · Documentation · Contributing

pixiv-cli brings the Pixiv ecosystem to the terminal: discover works and creators, manage accounts and collections, follow artists, bookmark artworks, and download visual works. It is an independent, unofficial third-party CLI, MCP server, and public Go SDK; it is not affiliated with or endorsed by Pixiv Inc. The CLI and MCP server both call the same public Go SDK, with the Pixiv App API as the authenticated source of truth. Use it in accordance with Pixiv's terms and applicable law.

Why pixiv-cli?

• One capability surface — keyword search, details, rankings, recommendations, users, bookmarks, follows, downloads, and ugoira across CLI, MCP, and SDK; reverse-image search is integrated into the CLI/MCP surface.
• Read-only FANBOX access — authenticate with FANBOXSESSID, inspect creators, posts, home/supporting feeds, tags, and first-party file resources through the CLI, MCP, or sdk/fanbox.
• Composable visual pipelines — visual lists automatically emit canonical NDJSON when piped; use --filter for typed local artwork rules and pass matching records straight to download.
• Local account pools — enable database-backed scheduling for read workloads with pixiv auth pool status|enable|disable; selection honors Pixiv Retry-After responses without exposing credentials.
• Guided account sign-in — complete browser OAuth with pixiv auth login, then use auth list, auth use, and auth check to manage local multi-account access.
• Ugoira output modes — choose GIF or APNG; invalid or empty filename templates use a stable default and remain observable as warnings.
• Explicit download reporting — select image quality and closed page ranges, use allowlisted Pixiv CDN URLs as direct sources, and keep completed files, warnings, and failures observable.
• Authenticated App API discovery — read R18 details, pages, ugoira metadata, and all 16 ranking modes through the App API.
• Useful search filters — rating, content type, AI mode, aspect ratio, resolution, and a versioned drawing-tool catalog; reverse-image search can query SauceNAO or ascii2d from a local file or URL.
• Direct Pixiv references — paste supported artwork URLs into detail or download; authenticated profile and artworks URLs expand to that creator's visual works.
• Local multi-account OAuth — browser login, account selection, refresh-token rotation, and an optional cross-machine callback relay.
• Automation-ready integration — typed SDK errors, JSON output, clean MCP stdio, signed release updates, and complete result reporting.

Install

Installer scripts (Windows, Linux, and macOS)

Linux/macOS (sh):

curl -fsSLo /tmp/pixiv-install.sh https://github.com/FlanChanXwO/pixiv-cli/releases/latest/download/install.sh && sh /tmp/pixiv-install.sh --add-to-path

Windows Command Prompt (cmd.exe, no PowerShell):

curl.exe -fsSLo "%TEMP%\pixiv-install.cmd" https://raw.githubusercontent.com/FlanChanXwO/pixiv-cli/main/scripts/install.cmd && call "%TEMP%\pixiv-install.cmd" --add-to-path

Both scripts detect AMD64/ARM64, select the latest stable official Release archive, verify its published SHA-256, preflight the staged binary, and install per-user before changing PATH. Use --no-path to leave PATH untouched or --install-dir DIR to choose another destination. You can inspect the downloaded script before running it.

Versioned installers keep checksums.txt on the official GitHub HTTPS path. Embedded free source candidates are probed only for the platform archive, must return the same checksum content, and the downloaded archive still has to pass SHA-256 verification. This changes transport availability, never Release identity or integrity.

Docker (Linux amd64/arm64)

Official images are published to GHCR as ghcr.io/flanchanxwo/pixiv-cli and Docker Hub as docker.io/flanchanxwo/pixiv-cli. Both registries carry the same native linux/amd64 and linux/arm64 release images. Pull an exact release from either registry when reproducibility matters:

docker pull ghcr.io/flanchanxwo/pixiv-cli:v1.2.3
docker pull docker.io/flanchanxwo/pixiv-cli:v1.2.3

latest follows stable releases only; Prerelease tags never move latest. To track the current stable release, pull either ghcr.io/flanchanxwo/pixiv-cli:latest or docker.io/flanchanxwo/pixiv-cli:latest. Images are built natively for linux/amd64 and linux/arm64. The container runs the same pixiv binary and uses the same ~/.pixiv-cli state namespace as other installations.

Keep account state persistent and expose a download workspace:

docker run --rm \
  -v pixiv-cli-state:/home/pixiv/.pixiv-cli \
  -v "$PWD:/work" \
  ghcr.io/flanchanxwo/pixiv-cli:v1.2.3 \
  --version

Use /work for downloaded files with an explicit output path; it is the container's working directory, not a separate product mode.

Bind mounts preserve host ownership. If the host directory is not writable by image UID 1000, run as the host identity, give the container an ephemeral HOME, and choose an explicit output path:

docker run --rm \
  --user "$(id -u):$(id -g)" \
  -e HOME=/tmp/pixiv-cli \
  -v "$PWD:/work" \
  ghcr.io/flanchanxwo/pixiv-cli:v1.2.3 \
  download URL --output /work/downloads

For persistent state with that same host identity, bind a host directory you own instead of the default named volume:

mkdir -p "$PWD/pixiv-cli-state"
docker run --rm \
  --user "$(id -u):$(id -g)" \
  -e HOME=/tmp/pixiv-cli \
  -v "$PWD/pixiv-cli-state:/home/pixiv/.pixiv-cli" \
  ghcr.io/flanchanxwo/pixiv-cli:v1.2.3 \
  auth list

Import a refresh token through stdin instead of passing it as an argv value. For manual import, allocate a TTY so the hidden prompt can suppress echo: run the command, paste the opaque token, and send EOF (Ctrl-D).

docker run --rm -it \
  -v pixiv-cli-state:/home/pixiv/.pixiv-cli \
  ghcr.io/flanchanxwo/pixiv-cli:v1.2.3 \
  auth import

For automation, pipe your secret manager's stdout directly into stdin with -i, not -it. The container writes only to the persistent state volume:

secret-manager print-token | docker run --rm -i \
  -v pixiv-cli-state:/home/pixiv/.pixiv-cli \
  ghcr.io/flanchanxwo/pixiv-cli:v1.2.3 \
  auth import

This uses the existing pixiv auth import behavior; it does not add a Docker-specific OAuth callback flow for auth login.

For MCP, the transport remains docker run --rm -i ghcr.io/flanchanxwo/pixiv-cli mcp, and stdout stays reserved for MCP JSON-RPC. Pin a release as shown below:

docker run --rm -i ghcr.io/flanchanxwo/pixiv-cli:v1.2.3 mcp

Add -v pixiv-cli-state:/home/pixiv/.pixiv-cli when the MCP server should reuse persisted accounts.

Upgrade by pulling a newer image and redeploying with the same state volume. This workflow does not make pixiv update container-aware.

Install with an AI agent

Copy this single prompt into Codex, Claude Code, Cursor, or another local AI agent with terminal access:

Install the latest stable pixiv-cli from https://github.com/FlanChanXwO/pixiv-cli for this machine: inspect the repository's scripts/install.sh or scripts/install.cmd first, choose the script matching the detected OS and architecture (the Windows path must use cmd.exe and must not invoke PowerShell), download only official GitHub Release assets, require the published SHA-256 check to pass before replacing anything, install per-user without administrator or root privileges, add only the chosen install directory to the user PATH, ask before installing any missing prerequisite, never read or output Pixiv credentials, verify with pixiv --version, and report the installed version plus every file and PATH change.

Also install the `pixiv-cli` Skill that matches the same stable release tag (not main): download the full skills/pixiv-cli/ directory from that tag into the agent skills directory the user confirms. Do not guess the skills path and do not follow the main branch for skill content.

Install the pixiv-cli Skill from SkillHub

Agents with SkillHub support can install the published pixiv-cli Skill directly from SkillHub. Each Skill version matches the CLI release it teaches; always use pixiv <cmd> --help as the final source of command syntax.

Install the pixiv-cli Skill from ClawHub

Agents using ClawHub can install the published pixiv-cli Skill with clawhub install pixiv-cli; pin the installed skill to the matching published release version rather than following an unversioned latest tag.

Homebrew (recommended on macOS and Linux)

brew install FlanChanXwO/tap/pixiv-cli

Upgrade later with:

brew update
brew upgrade pixiv-cli

Go

Use an exact published tag. A source install requires Go, cgo, a C linker, and the committ