Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/flanchanxwo--pixiv-cli/badge.svg)](/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

i

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.

  1. <div align="center">
  2. # pixiv-cli
  3. **Pixiv CLI · MCP server (stdio / HTTP)**
  4. [English](README.md) · [简体中文](README.zh-CN.md)
  5. <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&amp;label=views"></p>
  6. [Install](#install) · [Quick start](#60-second-quick-start) · [Interfaces](#choose-your-interface) · [Documentation](#documentation) · [Contributing](CONTRIBUTING.md)
  7. </div>
  8. 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).
  9. > Not affiliated with or endorsed by Pixiv Inc. Follow Pixiv's terms and applicable law.
  10. ```mermaid
  11. flowchart LR
  12. U["You / scripts"] --> CLI["pixiv CLI"]
  13. A["AI agents"] --> MCP["pixiv mcp<br/>stdio · HTTP+OAuth"]
  14. CLI --> SDK["public Go SDK<br/>(account-bound API objects)"]
  15. MCP --> SDK
  16. SDK --> PX["Pixiv App API<br/>(authenticated only)"]
  17. SDK -.-> FB["Pixiv Fanbox<br/>(read-only, FANBOXSESSID)"]
  18. CLI -.->|"search IMAGE"| RS["SauceNAO · ascii2d"]
  19. MCP -.->|"reverse search"| RS
  20. ```
  21. ## What you get
  22. | Area | Highlights |
  23. | --- | --- |
  24. | 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 |
  25. | Reverse search | Local image or URL → SauceNAO / ascii2d → canonical Pixiv records |
  26. | Download | Artwork IDs/URLs, creator and public-bookmark URLs, allowed CDN URLs; page ranges, quality, GIF/APNG Ugoira; full success/warning/failure report |
  27. | Account actions | Bookmarks, follows, comments and stamps |
  28. | Accounts | Browser OAuth login, multi-account, token rotation, optional cross-machine relay, opt-in account pool honoring `Retry-After` |
  29. | MCP | Same features as tools; image and Ugoira bytes; MCP Apps gallery over HTTP |
  30. | Pipelines | Piped lists emit canonical NDJSON that `detail`, `download`, `bookmark` and `follow` consume |
  31. | Pixiv Fanbox | Read-only creators, posts, feeds, tags and first-party files with a separate `FANBOXSESSID` |
  32. ```mermaid
  33. flowchart LR
  34. S["pixiv search miku"] -->|"NDJSON (auto when piped)"| D["pixiv detail"]
  35. S -->|NDJSON| DL["pixiv download"]
  36. R["pixiv ranking"] -->|NDJSON| B["pixiv bookmark add"]
  37. ```
  38. ## Install
  39. | Channel | Command |
  40. | --- | --- |
  41. | Homebrew (macOS/Linux, recommended) | `brew install FlanChanXwO/tap/pixiv-cli` · upgrade: `brew update && brew upgrade pixiv-cli` |
  42. | 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` |
  43. | 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` |
  44. | Docker (linux amd64/arm64) | `docker pull ghcr.io/flanchanxwo/pixiv-cli:v1.2.3` (also `docker.io/flanchanxwo/pixiv-cli`) |
  45. | Go | `go install github.com/FlanChanXwO/pixiv-cli/cmd/pixiv@vX.Y.Z` (exact tag) |
  46. | Archive / source | [GitHub Releases](https://github.com/FlanChanXwO/pixiv-cli/releases) · `sh scripts/build.sh` (`CGO_ENABLED=0`, no Rust/C toolchain) |
  47. - 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.
  48. - 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).
  49. <details>
  50. <summary>Install with an AI agent (copy this prompt)</summary>
  51. ```text
  52. 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.
  53. 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.
  54. ```
  55. 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.
  56. </details>
  57. ## 60-second quick start
  58. ```bash
  59. pixiv auth login # browser OAuth, saved by UID
  60. pixiv search "初音ミク" --content-type illust --ai-mode exclude --resolution high
  61. pixiv search "初音ミク" --type novel --search-by tag-exact
  62. pixiv search ./image.png --provider ascii2d-color --json # reverse image search
  63. pixiv detail https://www.pixiv.net/artworks/123456
  64. pixiv download https://www.pixiv.net/artworks/123456 --pages 1,3-5 --quality regular
  65. pixiv download https://www.pixiv.net/users/12345678/artworks # whole creator
  66. pixiv search "miku" --limit 20 | pixiv download # pipeline
  67. pixiv bookmark add 123456 && pixiv follow add 12345678
  68. pixiv recommended --type all --limit 10
  69. pixiv timeline latest --type artwork --limit 20
  70. pixiv fanbox auth import && pixiv fanbox post 123456 # FANBOX (hidden input)
  71. ```
  72. `pixiv --help` and the [CLI reference](docs/en/cli-reference.md) cover every command, flag, config key and environment variable.
  73. ## Choose your interface
  74. ### CLI
  75. Text by default, `--json` for one document, `--ndjson` (or a pipe) for record streams.
  76. ```bash
  77. pixiv ranking --mode day --json
  78. pixiv user detail 12345678
  79. ```
  80. ### MCP
  81. ```mermaid
  82. flowchart LR
  83. Host["MCP host / agent"] -->|"stdio (default)"| L["pixiv mcp<br/>local CLI accounts"]
  84. Host -->|"HTTP + OAuth bearer"| H["pixiv mcp --port 1270<br/>remote / cloud connectors"]
  85. ```
  86. Local (stdio) — add to your MCP client config:
  87. ```json
  88. {
  89. "mcpServers": {
  90. "pixiv": {
  91. "command": "pixiv",
  92. "args": ["mcp"]
  93. }
  94. }
  95. }
  96. ```
  97. Remote (authenticated HTTP):
  98. ```bash
  99. pixiv mcp auth init # once; prints the owner secret once
  100. pixiv mcp --port 1270 # http://127.0.0.1:1270/mcp
  101. pixiv mcp --port 1270 --base-url https://mcp.example.com # behind an HTTPS reverse proxy
  102. ```
  103. 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).
  104. ## Documentation
  105. | Guide | For |
  106. | --- | --- |
  107. | [Installation](docs/en/install.md) | Channels, Docker, trust, `pixiv update` |
  108. | [Authentication](docs/en/authentication.md) | Login, remote hand-off, token import/export |
  109. | [CLI reference](docs/en/cli-reference.md) | Commands, flags, config, downloads, MCP startup |
  110. | [MCP tools](docs/en/mcp-tools.md) · [MCP Apps gallery](docs/en/mcp-gallery.md) | Tool schemas, output, HTTP authorization, Gallery UI |
  111. | [Go SDK](docs/en/sdk.md) | API objects, caller-owned credentials, reverse search and page downloads in Go |
  112. | [Architecture](docs/en/maintainers/architecture.md) · [MCP server](docs/en/maintainers/architecture-mcp.md) | Package boundaries and runtime flow |
  113. | [Coding standards](docs/en/maintainers/coding-standards.md) | Go conventions for contributors |
  114. | [Development](docs/en/maintainers/development.md) · [CI](docs/en/maintainers/ci.md) · [Release](docs/en/maintainers/release.md) | Toolchain, tests, PR gates, releases |
  115. | [Changelog](changelog/README.md) | User-visible changes |
  116. ## Contributing
  117. 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.
  118. Thank you to everyone who helps improve pixiv-cli.
  119. <a href="https://github.com/FlanChanXwO/pixiv-cli/graphs/contributors">
  120. <img src="https://contrib.rocks/image?repo=FlanChanXwO/pixiv-cli" alt="Contributors to pixiv-cli">
  121. </a>
  122. [View all contributors](https://github.com/FlanChanXwO/pixiv-cli/graphs/contributors)
  123. ## License
  124. [MIT](LICENSE) © FlanChanXwO. Release archives contain only the executable.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.