JavDB CLI Operator
Drive the installed javdb binary, not a guessed API or a source checkout. Read only the reference needed for the user's operation; no repository-maintenance skill or personal agent configuration is required.
Preflight
- Run
javdb --version. If missing or not executable, report the blocker. Install only on an explicit installation/repair request using install.md. - Inspect the relevant
javdb COMMAND --helpbefore execution. Do not list accounts on every turn; useauth listonly for an account decision or explicit request. A stored account is not proof of a valid token. - Use networked
javdb auth check --jsononly when identity validation is needed. Normal discovery does not authorize login, configuration repair, or host changes.
Safety and authorization
~/.javdb-cli/auth.jsoncontains usernames, passwords, and JWTs. Never read, print, upload, quote, or summarize its contents. Supported POSIX systems use private0600permissions.- For login and credential handling, read auth.md. Do not launch a hidden prompt in an agent terminal the user cannot type into. Never request an undisclosed password in chat as a workaround.
- Account/config changes,
mark/unmark, cache clearing/refresh, updates, and file downloads require the user's explicit current target and action. Prior authorization does not extend to a new target. Reuse an already explicit instruction rather than asking the same question again. - Use the App API. Do not substitute browser cookies or scraping after an error. Public queries retain anonymous access. Saved credentials follow the shared, explicitly configured
auto_reloginpolicy; additional recovery steps require authorization. - Image search uploads the image to AVScan or a configured provider. Explain that privacy effect and use only an authorized source. Media assets are previews/thumbnails, not full movies or magnet-target downloads.
Choose the operation
| Task | Commands and scope |
|---|---|
| Read discovery/details | search, detail, comments, magnets, entity commands, rankings, tags, browse; see discover.md |
| Read authenticated lists | top250, watched, want, recent, collections, default lists; require the selected local account |
| Diagnose identity | auth list, auth check; only when needed |
| Change remote/local state | mark, unmark, auth login/use/remove, config set/unset; see state.md |
| Save media assets | assets list then a scoped pipe into assets download; see media.md |
| Inspect/update installation | update --check --json is read-only; actual update requires explicit authorization |
| Manage caches | tags --refresh rebuilds tags; cache reverse-search --clear clears only reverse-search cache; use only for the requested cache task |
All JavDB business commands use the saved default account token when available.
Public queries may run anonymously; rejected anonymous requests provide a sign-in
instruction. Rejected saved credentials prompt re-login unless auto_relogin=true
explicitly enables one shared re-login. Personal lists and writes require credentials.
Image downloads/providers receive no JavDB token. See auth.md.
Output and input contracts
Use the user's requested scope. Supply a positive --limit only when supported and appropriate to that scope; never add an arbitrary limit, page cap, timeout, or retry to save context. --all is command-specific and only for an explicit exhaustive traversal. comments reads one selected page (default page 1, limit 20), not an automatic all-pages loop.
TTY stdout defaults to human-readable text. Piped stdout normally uses stable text references/URIs; explicit --ndjson selects javdb.pipeline/v1 envelopes. --json retains the command's aggregate/legacy shape where applicable and is mutually exclusive with --ndjson. Inspect exit status before parsing: failures may leave stdout empty. Diagnostics use stderr with --log-format text|json (default text) and --log-level debug|info|warning|error (default info). Help/prompts follow system locale: English or Simplified Chinese. lang controls API responses separately; keep machine field names and codes unchanged.
Most data commands accept non-TTY batch input. Explicit positional arguments plus non-empty stdin are ambiguous and fail. Login, password prompts, and config set are outside this generic pipeline path. Batch failures can preserve successful items and still exit nonzero; report both rather than calling them empty results.
Movie/list/entity envelopes carry their actual kind and stable ID; list/entity payloads live in data.list/data.entity. Missing stable IDs fail, while a missing display name can use the ID as ref. A known movie ID bypasses number resolution; never infer one from a title. Assets use a separate TYPE<TAB>URL stream.
javdb search "ABC-123" --json
javdb search "QUERY" --type actor --json
javdb detail ABC-123 --json
javdb detail MOVIE_ID --id --json
javdb comments ABC-123 --page 1 --limit 20 --json
javdb lists search "QUERY" --zone all --ndjson
javdb list LIST_ID --json
javdb lists related ABC-123 --ndjson
javdb search ABC --ndjson | javdb detail
javdb rankings movies --type fc2 --period week
javdb update --check --json
Replace placeholders only with verified values. Examples illustrate syntax, not permission to perform extra requests.
Image search and integrated magnet search
javdb search IMAGE_OR_URL [--source NAME] [--no-cache] accepts JPEG/PNG/WEBP up to the existing 8 MiB limit and uploads to the selected provider. Candidates are resolved to JavDB through strict movie-number matching; one failed candidate can leave other output and a nonzero exit. Do not hide the failed candidate.
Reverse-search caching defaults to 30 days, keyed by source and original-image SHA-256. --no-cache bypasses it for one search. javdb cache reverse-search [--source NAME] [--clear] addresses that cache only; do not delete unrelated local state.
javdb search QUERY --magnets N combines movie search, filtering, sorting, and magnet lookup. --cnsub, --hd, and non-negative --min-size filter before sorting; zero is valid and negative fractional sizes fail. N=0 requests all and positive N selects the first N. Text output contains magnet URIs; NDJSON contains kind=magnet. This option does not download the targets and is only for movie search.
Configuration and routing
Precedence is CLI flags, environment, config.toml, then defaults. --proxy URL and --host auto|mirror|main|URL affect one invocation. Supported proxy schemes are HTTP/HTTPS/SOCKS4/SOCKS4A/SOCKS5/SOCKS5H; a host is required and SOCKS needs an explicit port. An explicitly blank proxy is an error, not a direct-connection override.
CLI host=auto verifies and reuses route.json; when invalid, it discovers startup candidates and selects a route. Fixed mirror, main, or absolute URLs bypass discovery. Do not confuse the CLI default with the SDK constructor's mirror default or persist an unreviewed URL.
Actual update resolves its own Release transport, ignoring data host selectors. It detects Homebrew, go install, or Release-archive installation; development builds refuse self-update. Use --prerelease only on request, and not for Homebrew. See install.md for verification boundaries and troubleshooting.md for failures.
- Downloads
- 1.1kAll time
- Security audit
- Pass
- Last updated
- 1d ago
- Current version
- v0.8.5
- License
- MIT-0
