pixiv-cli
Pixiv, in your terminal — a CLI, MCP server, and Go SDK for discovery, accounts, creators, collections, and downloads.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/FlanChanXwO/pixiv-cli with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/FlanChanXwO/pixiv-cli'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/flanchanxwo--pixiv-cli)HTML
<a href="/listings/flanchanxwo--pixiv-cli"><img src="/api/listings/flanchanxwo--pixiv-cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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`.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 168 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <div align="center">
- # pixiv-cli
- **Pixiv CLI · MCP server (stdio / HTTP)**
- [English](README.md) · [简体中文](README.zh-CN.md)
- <p><a href="https://github.com/FlanChanXwO/pixiv-cli/actions/workflows/ci.yml"><img alt="Quality gate" src="https://github.com/FlanChanXwO/pixiv-cli/actions/workflows/ci.yml/badge.svg?event=push"></a> <a href="https://github.com/FlanChanXwO/pixiv-cli/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/FlanChanXwO/pixiv-cli?style=flat-square"></a> <a href="go.mod"><img alt="Go" src="https://img.shields.io/github/go-mod/go-version/FlanChanXwO/pixiv-cli?style=flat-square"></a> <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/FlanChanXwO/pixiv-cli?style=flat-square"></a> <img alt="Views" src="https://hits.sh/github.com/FlanChanXwO/pixiv-cli.svg?style=flat-square&label=views"></p>
- [Install](#install) · [Quick start](#60-second-quick-start) · [Interfaces](#choose-your-interface) · [Documentation](#documentation) · [Contributing](CONTRIBUTING.md)
- </div>
- Unofficial CLI and MCP server for Pixiv: search, browse, bookmark, follow and download from a terminal or an AI agent. It also reads Pixiv Fanbox content (read-only).
- > Not affiliated with or endorsed by Pixiv Inc. Follow Pixiv's terms and applicable law.
- ```mermaid
- flowchart LR
- U["You / scripts"] --> CLI["pixiv CLI"]
- A["AI agents"] --> MCP["pixiv mcp<br/>stdio · HTTP+OAuth"]
- CLI --> SDK["public Go SDK<br/>(account-bound API objects)"]
- MCP --> SDK
- SDK --> PX["Pixiv App API<br/>(authenticated only)"]
- SDK -.-> FB["Pixiv Fanbox<br/>(read-only, FANBOXSESSID)"]
- CLI -.->|"search IMAGE"| RS["SauceNAO · ascii2d"]
- MCP -.->|"reverse search"| RS
- ```
- ## What you get
- | Area | Highlights |
- | --- | --- |
- | Discover | Search artworks/novels/users; filter by rating, subtype, AI mode, aspect ratio, resolution, drawing tool, bookmark count; all 16 ranking modes; recommendations, timelines, series, comments |
- | Reverse search | Local image or URL → SauceNAO / ascii2d → canonical Pixiv records |
- | Download | Artwork IDs/URLs, creator and public-bookmark URLs, allowed CDN URLs; page ranges, quality, GIF/APNG Ugoira; full success/warning/failure report |
- | Account actions | Bookmarks, follows, comments and stamps |
- | Accounts | Browser OAuth login, multi-account, token rotation, optional cross-machine relay, opt-in account pool honoring `Retry-After` |
- | MCP | Same features as tools; image and Ugoira bytes; MCP Apps gallery over HTTP |
- | Pipelines | Piped lists emit canonical NDJSON that `detail`, `download`, `bookmark` and `follow` consume |
- | Pixiv Fanbox | Read-only creators, posts, feeds, tags and first-party files with a separate `FANBOXSESSID` |
- ```mermaid
- flowchart LR
- S["pixiv search miku"] -->|"NDJSON (auto when piped)"| D["pixiv detail"]
- S -->|NDJSON| DL["pixiv download"]
- R["pixiv ranking"] -->|NDJSON| B["pixiv bookmark add"]
- ```
- ## Install
- | Channel | Command |
- | --- | --- |
- | Homebrew (macOS/Linux, recommended) | `brew install FlanChanXwO/tap/pixiv-cli` · upgrade: `brew update && brew upgrade pixiv-cli` |
- | Script (Linux/macOS) | `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` |
- | Script (Windows `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` |
- | Docker (linux amd64/arm64) | `docker pull ghcr.io/flanchanxwo/pixiv-cli:v1.2.3` (also `docker.io/flanchanxwo/pixiv-cli`) |
- | Go | `go install github.com/FlanChanXwO/pixiv-cli/cmd/pixiv@vX.Y.Z` (exact tag) |
- | Archive / source | [GitHub Releases](https://github.com/FlanChanXwO/pixiv-cli/releases) · `sh scripts/build.sh` (`CGO_ENABLED=0`, no Rust/C toolchain) |
- - Scripts detect AMD64/ARM64, verify the Release SHA-256, preflight the binary and install per-user. `--no-path` leaves PATH alone; `--install-dir DIR` changes the destination. Inspect the script before running it.
- - Direct downloads ship checksums and an Ed25519-signed manifest. Details: [installation](docs/en/install.md), [Docker](docs/en/install.md#docker), [Go source](docs/en/install.md#go-source-installation).
- <details>
- <summary>Install with an AI agent (copy this prompt)</summary>
- ```text
- 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.
- ```
- The published Skill is also on [SkillHub](https://www.skillhub.cn/skills/pixiv-cli) and [ClawHub](https://clawhub.ai/flanchanxwo/skills/pixiv-cli) (`clawhub install pixiv-cli`). Pin it to the version matching your CLI; `pixiv <cmd> --help` remains the final source of syntax.
- </details>
- ## 60-second quick start
- ```bash
- pixiv auth login # browser OAuth, saved by UID
- pixiv search "初音ミク" --content-type illust --ai-mode exclude --resolution high
- pixiv search "初音ミク" --type novel --search-by tag-exact
- pixiv search ./image.png --provider ascii2d-color --json # reverse image search
- pixiv detail https://www.pixiv.net/artworks/123456
- pixiv download https://www.pixiv.net/artworks/123456 --pages 1,3-5 --quality regular
- pixiv download https://www.pixiv.net/users/12345678/artworks # whole creator
- pixiv search "miku" --limit 20 | pixiv download # pipeline
- pixiv bookmark add 123456 && pixiv follow add 12345678
- pixiv recommended --type all --limit 10
- pixiv timeline latest --type artwork --limit 20
- pixiv fanbox auth import && pixiv fanbox post 123456 # FANBOX (hidden input)
- ```
- `pixiv --help` and the [CLI reference](docs/en/cli-reference.md) cover every command, flag, config key and environment variable.
- ## Choose your interface
- ### CLI
- Text by default, `--json` for one document, `--ndjson` (or a pipe) for record streams.
- ```bash
- pixiv ranking --mode day --json
- pixiv user detail 12345678
- ```
- ### MCP
- ```mermaid
- flowchart LR
- Host["MCP host / agent"] -->|"stdio (default)"| L["pixiv mcp<br/>local CLI accounts"]
- Host -->|"HTTP + OAuth bearer"| H["pixiv mcp --port 1270<br/>remote / cloud connectors"]
- ```
- Local (stdio) — add to your MCP client config:
- ```json
- {
- "mcpServers": {
- "pixiv": {
- "command": "pixiv",
- "args": ["mcp"]
- }
- }
- }
- ```
- Remote (authenticated HTTP):
- ```bash
- pixiv mcp auth init # once; prints the owner secret once
- pixiv mcp --port 1270 # http://127.0.0.1:1270/mcp
- pixiv mcp --port 1270 --base-url https://mcp.example.com # behind an HTTPS reverse proxy
- ```
- An authorized HTTP connector acts on the **server's** files and network (e.g. reverse search can read server-side paths), so grant access only to clients you trust. Tools, transports and setup details: [MCP tools](docs/en/mcp-tools.md) · [HTTP startup](docs/en/cli-reference.md#mcp-http-server).
- ## Documentation
- | Guide | For |
- | --- | --- |
- | [Installation](docs/en/install.md) | Channels, Docker, trust, `pixiv update` |
- | [Authentication](docs/en/authentication.md) | Login, remote hand-off, token import/export |
- | [CLI reference](docs/en/cli-reference.md) | Commands, flags, config, downloads, MCP startup |
- | [MCP tools](docs/en/mcp-tools.md) · [MCP Apps gallery](docs/en/mcp-gallery.md) | Tool schemas, output, HTTP authorization, Gallery UI |
- | [Go SDK](docs/en/sdk.md) | API objects, caller-owned credentials, reverse search and page downloads in Go |
- | [Architecture](docs/en/maintainers/architecture.md) · [MCP server](docs/en/maintainers/architecture-mcp.md) | Package boundaries and runtime flow |
- | [Coding standards](docs/en/maintainers/coding-standards.md) | Go conventions for contributors |
- | [Development](docs/en/maintainers/development.md) · [CI](docs/en/maintainers/ci.md) · [Release](docs/en/maintainers/release.md) | Toolchain, tests, PR gates, releases |
- | [Changelog](changelog/README.md) | User-visible changes |
- ## Contributing
- Bug reports, docs fixes, tests and focused features are welcome — read [CONTRIBUTING.md](CONTRIBUTING.md) first and discuss large or public-interface changes before coding.
- Thank you to everyone who helps improve pixiv-cli.
- <a href="https://github.com/FlanChanXwO/pixiv-cli/graphs/contributors">
- <img src="https://contrib.rocks/image?repo=FlanChanXwO/pixiv-cli" alt="Contributors to pixiv-cli">
- </a>
- [View all contributors](https://github.com/FlanChanXwO/pixiv-cli/graphs/contributors)
- ## License
- [MIT](LICENSE) © FlanChanXwO. Release archives contain only the executable.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.