Pixiv CLI · MCP stdio server · Go SDK
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.
- 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, orsdk/fanbox. - Composable visual pipelines — visual lists automatically emit canonical NDJSON when piped; use
--filterfor typed local artwork rules and pass matching records straight todownload. - Local account pools — enable database-backed scheduling for read workloads with
pixiv auth pool status|enable|disable; selection honors PixivRetry-Afterresponses without exposing credentials. - Guided account sign-in — complete browser OAuth with
pixiv auth login, then useauth list,auth use, andauth checkto manage local multi-account access. - Four ugoira output modes — choose GIF, APNG, lossless ZIP, or extracted frames.
- Reliable, organized downloads — revalidate
.pixiv-cachemetadata, resume verified partials, retry eligible resource failures, optionally archive completed artwork IDs, write sidecars, and show exact terminal progress when available. - 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.
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-pathWindows 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-pathBoth 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.
Official images are published to GHCR as ghcr.io/flanchanxwo/pixiv-cli. Pull an exact release when reproducibility matters:
docker pull ghcr.io/flanchanxwo/pixiv-cli:v1.2.3latest follows stable releases only; Prerelease tags never move latest. To track the current stable release, pull ghcr.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 \
--versionUse /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/downloadsFor 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 listImport 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 importFor 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 importThis 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 mcpAdd -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.
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.
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.
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.
brew install FlanChanXwO/tap/pixiv-cliUpgrade later with:
brew update
brew upgrade pixiv-cliUse an exact published tag. A source install requires Go, cgo, a C linker, and the committed Rust static library for your target.
go install github.com/FlanChanXwO/pixiv-cli/cmd/pixiv@vX.Y.ZDownload a supported archive from GitHub Releases, or build the checkout:
sh scripts/build.shDirect downloads include checksums and a signed manifest. See the CLI reference for platform and trust details.
# Save a Pixiv account through browser OAuth.
pixiv auth login
# Save a FANBOX session through hidden input, then inspect FANBOX content.
pixiv fanbox auth import
pixiv fanbox post 123456
# Search with App-side filters.
pixiv search "初音ミク" --type illust --ai-mode exclude --resolution high
pixiv novel search "初音ミク" --rating sfw --min-text-length 1000
# Reverse-search a local image or HTTP(S) image URL. Results can be JSON or NDJSON.
pixiv search ./image.png --provider ascii2d-color --json
pixiv search https://your-image-url.example/image.png --provider all --ndjson
# Follow creators and build your collection.
pixiv follow add 12345678
pixiv bookmark add 123456
# Inspect, discover recommendations, and download.
pixiv detail https://www.pixiv.net/artworks/123456
pixiv recommended all --limit 10
pixiv timeline latest --type illust --limit 20
pixiv download https://www.pixiv.net/artworks/123456 --pages 1,3-5 --quality regular
pixiv download 123456 https://i.pximg.net/img-original/example.jpg --concurrency 8
# Batch-download every visual work from a creator.
pixiv download https://www.pixiv.net/users/12345678/artworksRun pixiv --help or open the complete CLI reference for every command, flag, configuration key, environment variable, fallback rule, and update behavior.
Use the default text output interactively and --json where the command supports machine output:
pixiv ranking --mode day --json
pixiv user search "miku" --limit 10 --json
pixiv user detail 12345678
pixiv timeline latest --type illust --limit 10 --jsonReverse-image search is available through the CLI/MCP integration; the public Go SDK remains unchanged.
Start the stdio server explicitly. stdout remains reserved for JSON-RPC; tool failures are returned as structured results with isError=true. No project-level or daily log files are created by default.
pixiv mcp
# FANBOX tools use their own runtime credential selection.
pixiv fanbox mcpSee the MCP tool contract for tools, parameters, structured output, and authentication behavior. Fixed MCP status, error, and display text is English; Pixiv metadata and user-supplied text are preserved verbatim.
The reverse_search tool accepts a regular local file or HTTP(S) URL and may upload
that source to third-party providers. Because trusted local MCP clients may request
private files and private/loopback/link-local URLs, run it only from a client you
trust; see the reverse-search MCP contract.
The public SDK receives credentials explicitly and does not read the CLI's local account store or process environment. Obtain the credential from your application's secret store and persist the rotated credentials returned by Open:
package main
import (
"context"
"fmt"
"log"
pixiv "github.com/FlanChanXwO/pixiv-cli/sdk/pixiv"
)
func main() {
ctx := context.Background()
refreshToken := "replace-with-a-refresh-token-from-your-secret-store"
client, _, err := pixiv.Open(ctx, refreshToken)
if err != nil {
log.Fatal(err)
}
result, err := client.SearchArtworks(ctx, pixiv.SearchArtworksRequest{Word: "初音ミク"})
if err != nil {
log.Fatal(err)
}
for _, artwork := range result.Items {
fmt.Printf("%d %s\\n", artwork.ID, artwork.URL)
}
}The import path is github.com/FlanChanXwO/pixiv-cli/sdk/pixiv. sdk/fanbox accepts a FANBOXSESSID explicitly and supports native Chrome 146 TLS routing with the built-in Firefox 148 HTTP User-Agent baseline, with optional service-scoped proxy, user-agent, and challenge-only FlareSolverr options. Download/DownloadAll use documented beginner defaults; DownloadWith/DownloadAllWith expose paths, naming, pages, quality, and concurrency. The SDK guide documents models, cursors, resources, errors, caller responsibilities, and the explicit DTO boundary used by CLI/MCP JSON output; media resources cross those boundaries only as opaque references.
pixiv auth login is the recommended setup. It saves raw Pixiv App OAuth refresh tokens by UID in the local account store.
Account names, IDs, membership signals, and the active local-account selection are convenience information from the local store and Pixiv responses. Treat them as convenience data rather than proof of account ownership, entitlement, or current Pixiv status. Verify important account details in Pixiv and use only accounts you are authorized to manage.
On macOS, Windows, and desktop Linux, pixiv prepares the current-user pixiv:// callback handler for the installed binary. When a server has login_relay_public_url and login_relay_listen_addr, pixiv auth login prints a one-time remote hand-off URL. Opening it transfers the session directly to the installed desktop handler, which starts OAuth and returns its callback to the server. Remote login therefore uses a desktop with pixiv-cli installed; it has no project confirmation page or callback-copy form. See the CLI reference.
pixiv auth list
pixiv auth pool status
pixiv auth use 12345678
pixiv auth check| Guide | Use it for |
|---|---|
| CLI reference | Commands, flags, auth, configuration, fallback, downloads, and updates |
| Go SDK | Public client, models, pagination, resources, and typed errors |
| MCP tools | Tool schemas and output semantics |
| Architecture | Package boundaries and runtime flow |
| Development | Toolchain, tests, builds, and releases |
| Changelog | User-visible changes |
Bug reports, documentation fixes, tests, and focused features are welcome. Read CONTRIBUTING.md before opening a pull request; discuss large or public-interface changes first.
MIT © FlanChanXwO