JavDB CLI · Public Go SDK · Agent skill
Install · Quick start · Interfaces · Documentation · Contributing
javdb-cli is an independent, unofficial command-line client and Go SDK for the
JavDB App JSON API. It gives people, coding agents, and Go
applications one consistent capability surface for search, catalog navigation,
movie details, review pages, selected media downloads, magnets, rankings, and
authenticated user lists. It is not a
website scraper, does not include MCP, and is not affiliated with, endorsed by,
or related to JavDB or its operators. Use it only in accordance with JavDB's
terms and the laws that apply to you.
- CLI and public Go SDK — the CLI and importable
javdbpackage cover search, detail, review pages, selected thumbnail/preview downloads, tags, browsing, entity filmographies, magnets, rankings, TOP250, collections, and authenticated watch/want data. - API client, not a scraper — commands use the App JSON API with explicit host and proxy selection; failures remain visible rather than becoming fabricated empty results.
- Useful agent navigation — JSON output, stable graph IDs from
detail, and an included operator skill support safe, multi-step automation. - Local multi-account credentials — username/password/token data stays in
~/.javdb-cli/auth.jsonwith mode0600on POSIX platforms; normal command output never prints the JWT. - Deliberate state changes — watch/want marks, default-account changes, configuration writes, and tag-cache refreshes are explicit CLI operations.
- Native release evidence — macOS, Linux, and Windows on amd64 and arm64 are built, packaged, extracted, and smoke-tested by CI.
brew install FlanChanXwO/tap/javdb-cliUpgrade later with:
brew update
brew upgrade javdb-cliThe Formula is updated after a verified release when tap deployment is enabled.
Use an exact published tag:
go install github.com/FlanChanXwO/javdb-cli/cmd/javdb@v0.2.0Download the archive for your platform from
GitHub Releases, verify it
against the accompanying checksums.txt, and place javdb (javdb.exe on
Windows) in a directory on your PATH.
To build the checkout, install the Go version declared in go.mod and run:
sh scripts/build.sh
./build/javdb version --jsonThe release contract covers macOS, Linux, and Windows on amd64 and arm64. See the development guide for reproducible target builds and archive contents.
Published installations can check for a newer release and install it with:
javdb update --check
javdb updateupdate detects whether javdb is managed by Homebrew, go install, or a
Release archive, then uses that matching channel. Archive updates fetch only the
current OS/architecture asset, verify its SHA-256 against the same Release's
checksums.txt, validate the downloaded binary's version, and then replace the
executable. --check --json is the machine-readable, no-write form;
--prerelease includes prerelease tags. A Homebrew installation supports stable
releases only. The existing --proxy URL setting also applies to Release checks;
update resolves that proxy independently and ignores JavDB host settings.
Copy this prompt into Codex, Claude Code, Cursor, or another local coding agent with terminal access:
Install the latest stable javdb-cli from https://github.com/FlanChanXwO/javdb-cli for this machine. Detect the operating system and architecture, download only official GitHub Release assets, require the matching published SHA-256 from checksums.txt before installing, ask before creating or changing any PATH directory, never read or output ~/.javdb-cli/auth.json or credentials, verify with javdb version --json, and report the installed version plus every changed file.
Also install the complete skills/javdb-cli/ directory from the same stable release tag into the agent skills directory that I confirm. Do not guess that skills path, do not use the main branch for the skill, and preserve all reference files.
# Sign in interactively; the CLI never prints the JWT.
javdb auth login
javdb auth check --json
# Find a movie and inspect graph IDs for the next navigation step.
javdb search SSIS-589 --limit 5 --json
javdb detail SSIS-589 --json
javdb comments SSIS-589 --page 1 --limit 20 --json
# Browse a tag and request a filtered magnet list (works without login).
javdb browse --tag 巨乳 --main m --limit 20 --json
javdb magnets SSIS-589 --cnsub --hd --json
# Explicit local output paths; --preview-image downloads only the first preview.
javdb download SSIS-589 --thumbnail ./thumb.jpg --preview-image ./preview-0.jpg --preview-video ./preview.tsRun javdb --help or read the complete command reference for
all commands, flags, configuration keys, and authentication requirements.
Use tabular output interactively and --json when a command exposes it and an
agent or script needs stable fields:
javdb rankings movies --type fc2 --period week
javdb rankings movies --period week --json
javdb actor 山手梨愛 --main m --has-magnets --json
javdb lists search 巨乳 --zone all --jsonMovie and playback rankings accept censored, uncensored, western, or
fc2 as their zone selector; ranking periods use day, week, or month.
The global --proxy URL and --host auto|mirror|main|URL flags affect only that command.
The default auto host reuses the cached route immediately when validation succeeds.
Only a failed cache validation discovers the startup candidates, selects the fastest
App API host, and rewrites ~/.javdb-cli/route.json; a fixed host skips route discovery entirely.
Use javdb config get before relying on persisted settings.
package main
import (
"context"
"fmt"
"github.com/FlanChanXwO/javdb-cli/sdk"
)
func main() {
c, err := javdb.New(javdb.WithHost(javdb.HostMirror))
if err != nil {
panic(err)
}
res, err := c.Search(context.Background(), "SSIS-589", javdb.SearchOptions{Limit: 5})
if err != nil {
panic(err)
}
fmt.Println(len(res.Movies()))
}Import github.com/FlanChanXwO/javdb-cli/sdk; it declares package javdb, so
examples continue to use javdb. The SDK guide documents public
models, client options, and caller responsibilities.
The repository ships skills/javdb-cli, a dedicated
operator skill for coding agents. It defines credential handling, confirmation
boundaries, command-scoped flags, JSON/error handling, and search-to-detail
navigation. Load it only for explicit JavDB work, and verify each command's
flags with javdb <command> --help.
Agents using ClawHub can install the published javdb-cli Skill
with clawhub install javdb-cli; pin the installed skill to the matching
published release version, currently 0.5.2, rather than following an
unversioned latest tag.
javdb auth login is the recommended setup. It keeps the username, password,
and session token in the local multi-account store
~/.javdb-cli/auth.json (mode 0600 where POSIX permissions exist). Do not
commit, print, paste, or upload that file, passwords, or JWTs.
javdb auth list
javdb auth use USER_ID
javdb auth check --jsonjavdb auth check verifies the default token without printing it. Token expiry
is surfaced clearly by default. auto_relogin is opt-in and uses the saved
password for one re-login attempt; enable it only when you accept that behavior:
javdb config set auto_relogin trueMagnet commands work anonymously and use the saved token when available.
TOP250 and user-list commands need the default authenticated account.
mark/unmark, account changes, and config set/unset modify server or
local state and should be used deliberately. download writes selected media
to explicit new local paths; it never replaces an existing file.
| Guide | Use it for |
|---|---|
| CLI reference | Commands, flags, authentication, configuration, and common workflows |
| Agent operator skill | Safe agent routing, secrets, writes, discovery, and errors |
| Go SDK | Public client, models, and options |
| Architecture (Simplified Chinese) | Package boundaries and runtime flow |
| Development (Simplified Chinese) | Toolchain, tests, platform builds, packaging, and releases |
| Documentation map | Localized public contracts and maintainer guides |
| Contributing | Local quality gates and contribution rules |
| Changelog | Versioned bilingual release notes |
Bug reports, documentation fixes, tests, and focused features are welcome. Read CONTRIBUTING.md before opening a pull request; discuss large or compatibility-sensitive changes first.
MIT © FlanChanXwO