Pixiv CLI Operator
Use the installed pixiv binary. This bundle describes operation, privacy, and semantic traps, not repository development. It works without a source checkout or personal maintenance skills.
Preflight and routing
Run pixiv --version and require a successful pixiv VERSION line. A missing or non-executable binary is a blocker, not authorization to install it. Inspect the relevant command's --help before execution and read only the needed reference:
| Task | Reference |
|---|---|
| Explicit installation or repair | install.md |
| Login, import/export, backup/restore, account pool | auth.md |
| Search, reverse image, detail, users, feeds, rankings, bookmarks | discover.md |
| Single, multi-page, batch, or animated downloads | download.md |
| Authentication, proxy, output, or incomplete results | troubleshooting.md |
Do not enumerate accounts on every turn. Use pixiv auth list --json only when an account/authentication decision requires it; both accounts: null and accounts: [] mean none. Stored credentials do not prove current validity. Run networked auth check only when needed; auth refresh rotates credentials and refreshes profile/Premium metadata, so requires an explicit maintenance request.
Secrets and side effects
Refresh tokens and export bundles are plaintext secrets. Keep them out of commentary, results, logs, and diagnostics. Before any import/export or browser login, follow auth.md: an explicitly requested bare stdout export has a narrow disclosure/confirmation workflow; every other export uses a private output or direct consumer pipeline. Do not inspect credential-store contents to debug an account.
Do not ask for an undisclosed token in chat or launch a hidden prompt in an agent terminal the user cannot type into. If the user already disclosed a token and explicitly requests positional import, first explain the additional tool/process-record exposure, safely quote it, and never repeat it in results. Non-TTY import reads stdin automatically; there is no --stdin flag. Strict bundle decoding must not fall back to OAuth.
| Operation | Required scope |
|---|---|
| Discovery and read commands | Execute only as needed for the task; do not add account probes or extra result traversal |
auth list/check |
Only an account decision or needed validation |
auth refresh |
Explicit account-maintenance request |
| Bookmark/follow/comment mutations | Explicit current targets, types, and action; state the scope before execution |
download |
Confirm exact targets and destination for each invocation; a user URL expands the whole supported visual listing |
auth use/remove, pool enable/disable, config set/unset, actual update |
Explicit current state-change authorization; it does not carry to later targets |
auth login |
Explicit request and a user present for browser OAuth; follow the documented desktop/remote handoff |
mcp or fanbox mcp |
Explicit server-start request; these are long-lived stdio servers, not preflight probes |
config path can create baseline configuration if missing. A successful read-looking command is not necessarily filesystem-side-effect-free. update --check --json checks only; actual installation does not emit JSON and requires authorization.
Output and complete results
Use the requested scope and command-specific flags. A supported positive --limit N requests N logical results; reaching N is not proof that only N exist. Use --limit 0 only for an explicit exhaustive request. --page requires positive --limit; an omitted limit normally means one logical batch, not the entire corpus. Local filters can skip empty upstream batches; do not invent request caps.
Use text for a small display-only result. Visual listing commands emit canonical NDJSON automatically when stdout is piped; --ndjson makes that explicit. --json is one complete result document where supported and cannot combine with --ndjson. Check status before parsing; failed commands may produce ordinary stderr and empty stdout. Do not install processing tools merely to format output.
pixiv search "landscape" --type artwork --limit 20 --ndjson | pixiv detail
pixiv search ./image.png --provider all --ndjson | pixiv detail --ndjson
pixiv detail ARTWORK_ID --json
pixiv search "fantasy" --type novel --limit 10 --json
pixiv user search "NAME" --limit 10 --json
pixiv ranking --type novel --mode week --limit 10
pixiv recommended --type artwork --limit 10
Use these examples only for the requested operation and inspect selected records before any downstream action. Aggregate search --json is not a record stream. In detail record mode, record types choose artwork/novel/user endpoints; explicit --type is only a compatibility constraint. Record --json produces an array, not a single-object promise.
Public positional commands can fill one missing value from non-TTY stdin. Only a final newline is removed; an explicit positional value wins, and two missing required values do not trigger generic stdin reading. For detail, download, and bookmark/follow actions, an initial non-whitespace { selects strict record input; failures do not switch to raw ID input. - is ordinary text, not a universal stdin sentinel.
Authentication and service boundaries
Pixiv content is App-only. Use the selected local auth use account or an eligible database-managed account when the pool is enabled. There is no anonymous Web fallback and no per-command --uid/--refresh-token selection or PIXIV_REFRESH_TOKEN credential shortcut. The public SDK and MCP have their own explicit runtime credential contracts.
Pool enabled/strategy settings are configuration; schedulable accounts are managed by auth pool status|enable|disable. Reads/downloads may use the pool, but mutations must not be silently assigned to a different account. Removed settings fail explicitly; use the authorized cleanup described in auth.md, not an automatic account migration.
FANBOX is separate: use pixiv fanbox --help and its read-only creator/post/tag/feed/resource capabilities. Importing FANBOXSESSID with pixiv fanbox auth import or selecting an account with pixiv fanbox auth use --auto/an explicit UID is a separately authorized credential/state action, not automatic preflight. FANBOX MCP does not reuse the Pixiv pool. Its optional challenge-only solver does not carry ordinary API/resource traffic or receive the session; never send the session to a non-first-party host.
Search and identity traps
- Artwork
--rating sfw|r18|r18g|mature|allfilters normalizedx_restrictlocally and binds the filter to its cursor. It is not an upstream request field and is not supported for novel search. Artwork subtype, AI, resolution, aspect, and exact drawing-tool filters have their own validated scope. - Bookmark counts are not likes.
auto/localfilter candidates locally,best_effortis explicitly partial, andserverfails without verified upstream support. Premium is not a local hard gate. Do not present partial candidates as a complete site-wide result. recommendedneeds an entity kind and authentication; local artwork subtype filtering is not an upstream query. Rankings and feeds have command-specific kinds/modes; do not substitute a failed extended ranking withday.- User detail/list routes take numeric user IDs where documented; not every command accepts a user URL. Follow writes accept a positive numeric ID or canonical user record, and
--restrictispublic|privatewith public default. Use only verified IDs and supported URL namespaces. detail --type novel --contentis a compatibility flag whose unavailable App content endpoint returnscontent_unavailable; it is not permission to scrape a WebView. Plain novel detail remains metadata.
Comment operations
Comment reads preserve optional total and access_control, including numeric upstream comment_access_control; do not invent boolean permission fields. comment create|reply|stamp|delete requires an explicit artwork/novel type and positive numeric IDs, not URLs or all. Create/reply needs non-empty --comment; reply also needs --parent-comment-id, and stamp needs --stamp-id with optional text. Confirm the user's exact content and target before writing.
Create/reply/stamp return the upstream comment ID. Delete returns a success status without an automatic read-back. comment stamps is a non-paginated read with safe opaque stamp references. Bookmark/follow actions retain empty-success stdout; do not invent a JSON report.
Reverse search, proxies, and delivery
Reverse-search image sources are existing regular files or explicit HTTP(S) URLs; an invalid explicit URL is an error, never a keyword fallback. Binary image bytes on stdin do not select image mode. Provider/output/proxy flags apply; keyword filters, entity type, and pagination do not.
Providers are SauceNAO, ascii2d color/BoVW, and all. reverse_search_pixiv_only controls canonical Pixiv identities. Configure saucenao_api_key only through non-TTY stdin or SAUCENAO_API_KEY; reads redact it. Upload only authorized images and preserve provider privacy boundaries. One successful provider plus another failure can be a successful partial result with a warning; single/all-provider failure is nonzero. Generic reverse-search type=artwork records do not prove a Pixiv subtype.
--proxy and --no-proxy are mutually exclusive invocation overrides. Pixiv, FANBOX, reverse-search transport, and solver-browser settings have distinct scopes; the browser's proxy is not automatically inherited. Do not assume a private maintainer's loopback proxy exists. Read troubleshooting.md before changing persistent settings or solver configuration.
Downloads write files and have empty successful stdout; inspect exit status and the requested destination, following download.md. A legitimate long encode/download is not a timeout failure. Share generated files only through an available attachment API; otherwise report the source artwork URL and do not claim an image was sent.
