bili23-cli 0.2.0

Headless CLI for downloading Bilibili videos — reuses the Bili23-Downloader GUI login session, no separate login required.

bili23-cli

Headless CLI for downloading Bilibili videos — reuses the Bili23-Downloader GUI login session, so the CLI never asks you to log in.

Give it a Bilibili URL, get an .mp4. That's it.

bili23-cli "https://www.bilibili.com/video/BV1GE411Q7Ew/"

Why this exists

The official Bili23-Downloader is a Qt GUI app — great for clicking around, but not scriptable. The author's separate CLI repo was last published to PyPI in 2022 and is now stale (missing modern Bilibili auth: Wbi signing, buvid/ticket cookies, etc.).

bili23-cli is a modern, dependency-light rewrite that:

• 🍪 Reuses your GUI login — reads the cookie the GUI already stored, so you get your account's quality (1080P / 4K / VIP) without logging in again.
• 🔐 Implements current Bilibili auth — Wbi signature (w_rid), full cookie set (SESSDATA / buvid3/4 / bili_ticket / …), correct UA & Referer.
• 🪶 Minimal dependencies — only httpx + system ffmpeg. No PySide6 / Qt.
• 🧵 Multi-threaded — 4 MB chunked Range downloads.
• 🎛️ Selectable quality / codec — -q 1080P -c HEVC, or auto for best-available.

Prerequisites

1. The GUI app installed & logged in — Bili23-Downloader. Log in once; bili23-cli reads its session cookie.
   • This is how you get high quality. Anonymous use (--no-cookie) works but is limited to ~480P and some videos 403.
2. ffmpeg on your PATH (for merging audio + video):
   • macOS: brew install ffmpeg
   • Linux: sudo apt install ffmpeg
   • Windows: https://ffmpeg.org/download.html
3. Python ≥ 3.9.

Installation

As a standalone tool (recommended)

# with uv
uv tool install bili23-cli

# or with pipx
pipx install bili23-cli

This installs the bili23-cli command globally, in an isolated environment.

From source

git clone https://github.com/1WorldCapture/bili23-cli.git
cd bili23-cli
uv tool install .     # or: pipx install .

Usage

bili23-cli <URL-or-BVid> [options]

Examples

# Simplest: download to current dir, auto best quality
bili23-cli "https://www.bilibili.com/video/BV1GE411Q7Ew/"

# Bare BV id works too
bili23-cli BV1GE411Q7Ew

# Choose quality + codec, output dir
bili23-cli BV1GE411Q7Ew -o ~/Downloads -q 1080P -c HEVC

# Multi-part video: pick part 3
bili23-cli "https://www.bilibili.com/video/BVxxxxx/" -p 3

# More threads
bili23-cli BV1GE411Q7Ew -t 16

Options

Option	Description
url	Bilibili video URL or bare BV id (positional)
-o, --output DIR	Output directory (default: current dir)
-q, --quality	auto / 8K / 杜比视界 / HDR / 4K / 1080P60 / 1080P+ / 1080P / 720P / 480P / 360P (default: auto)
-c, --codec	auto / AVC / HEVC / AV1 (default: auto, prefers AVC > HEVC > AV1)
-p, --page N	Part number, 1-based (default: 1)
-t, --thread N	Download threads (default: 8)
--no-merge	Don't merge; keep video.m4s / audio.m4s
--no-cookie	Skip the GUI login cookie (anonymous; quality limited)
--keep-parts	Keep .m4s parts after merge

How it works

Auth reuse (the key trick)

The GUI stores your login in (macOS) ~/Library/Application Support/Bili23 Downloader/config.json under the Cookie key. bili23-cli reads it and rebuilds the exact cookie dict the GUI sends — including SESSDATA, bili_jct, buvid3/4, bili_ticket, and the CURRENT_FNVAL=4048 flag — so the CLI looks indistinguishable from the GUI to Bilibili's servers.

On each run it also calls /x/web-interface/nav to fetch fresh Wbi signing keys (img_key / sub_key) — it does not trust the cached values, which silently expire.

Download pipeline

Only two API calls are needed:

1. GET /x/web-interface/wbi/view?bvid=… (+ Wbi sig) → title, cid, parts
2. GET /x/player/wbi/playurl?bvid=…&cid=…&qn=…&fnval=4048&fourk=1 (+ Wbi sig) → DASH video[] / audio[] CDN URLs

Then: multi-threaded Range download of video.m4s + audio.m4s, followed by ffmpeg -c copy into .mp4.

See docs/research-notes.md for the full reverse-engineering writeup of the GUI's internals.

Scope (v0.1)

Supported: user-uploaded videos (BV/av) — parse, quality/codec selection, multi-threaded download, merge.

Not yet: bangumi / movies / courses / audio / favorites (different APIs), danmaku / subtitles / cover / metadata, batch download, cross-process resume, login flow (by design — reuse the GUI).

Acknowledgements

This project is an independent CLI companion to — and not affiliated with — ScottSloan/Bili23-Downloader. The auth and download logic is a clean-room reimplementation based on studying that project's source.

Bilibili is a trademark of Shanghai Kuoyu Network Technology Co., Ltd. This tool is for personal use; please respect Bilibili's Terms of Service and copyright.

License

GPL-3.0