Pixiv CLI

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:

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.

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.