javdb-cli

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.

Why javdb-cli?

• CLI and public Go SDK — the CLI and importable javdb package 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.json with mode 0600 on 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.

Install

Homebrew (recommended on macOS and Linux)

brew install FlanChanXwO/tap/javdb-cli

Upgrade later with:

brew update
brew upgrade javdb-cli

The Formula is updated after a verified release when tap deployment is enabled.

Go

Use an exact published tag:

go install github.com/FlanChanXwO/javdb-cli/cmd/javdb@v0.2.0

Release archive or source build

Download 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 --json

The release contract covers macOS, Linux, and Windows on amd64 and arm64. See the development guide for reproducible target builds and archive contents.

Update

Published installations can check for a newer release and install it with:

javdb update --check
javdb update

update 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.

Install with a coding agent

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.

60-second quick start

# 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.ts

Run javdb --help or read the complete command reference for all commands, flags, configuration keys, and authentication requirements.

Choose your interface

CLI

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 --json

Movie 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.

Go SDK

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.

Agent skill

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.

Install the javdb-cli Skill from ClawHub

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.

Authentication and credential safety

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 --json

javdb 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 true

Magnet 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.

Documentation

Contributing

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.

License

MIT © FlanChanXwO