# Bilibili Backend Options in Agent Reach: Migrating from yt-dlp to bili-cli

> Agent Reach now uses bili-cli for Bilibili downloads. Learn why we switched from yt-dlp and how to update your Agent Reach integration for uninterrupted access.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: migration-guide
- Published: 2026-07-07

---

**Agent Reach replaced yt-dlp with bili-cli and OpenCLI backends for Bilibili integration after yt-dlp began receiving HTTP 412 errors from Bilibili's risk-control system.**

The `Panniantong/Agent-Reach` repository provides a dedicated `BilibiliChannel` for extracting content from the Chinese video platform Bilibili. Understanding the **Bilibili backend options in Agent Reach** helps developers migrate from the deprecated yt-dlp approach to the current multi-tier backend architecture.

## Why yt-dlp Was Removed

The original `BilibiliChannel` implementation relied on `yt-dlp` to fetch video streams. Bilibili's risk-control system started returning **HTTP 412 (Precondition Failed)** for every `yt-dlp` request, even when using warmed cookies, proxies, or the latest version. According to the module docstring in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) (lines 4-9), the maintainers therefore **removed yt-dlp** entirely and replaced it with more reliable alternatives.

## The Three Backend Tiers

The channel now supports three mutually exclusive backends, probed in order of preference. The first backend reporting "ok" becomes the `active_backend`.

### bili-cli (Primary)

The **bili-cli** backend uses the [`bilibili-cli`](https://github.com/hanxi/bili-cli) binary installed via `pipx install bilibili-cli`. It provides search, hot-list retrieval, video details, and audio extraction without requiring a logged-in session.

Availability is probed using `probe_command("bili", ["--version"], …)` in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) (lines 82-94). If the command is missing, the backend is skipped; otherwise, the probe result determines *ok / warn / error* status.

### OpenCLI (Subtitle Support)

The **OpenCLI** backend reuses the user's Chrome session via the OpenCLI bridge. This enables subtitle extraction and other features requiring a logged-in browser that `bili-cli` cannot provide.

The channel queries `opencli_status()` from [`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py) (lines 96-110). This function probes the Chrome extension on disk to avoid false negatives when the extension is idle, reporting whether the extension is installed, connected, or sleeping.

### B站搜索 API (Fallback)

A zero-dependency **Bilibili Search API** fallback supports only keyword search via the public HTTP endpoint `https://api.bilibili.com/x/web-interface/search/all/v2?keyword=test&page=1`.

The `_search_api_ok()` method (lines 24-32) sends a test request and verifies the JSON response contains `code == 0`. If reachable, the backend reports *ok*, allowing basic search functionality even without installed binaries.

## How Backend Selection Works

The `check()` method in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) (lines 46-72) iterates through backends using `ordered_backends()`, respecting user configuration. It collects error messages from failed backends while continuing to probe subsequent options. If a later backend succeeds, the error messages append to the success message, informing users which backend is active and which alternatives failed.

## Installation and Migration Guide

To transition from yt-dlp to the supported architecture:

1. **Install bili-cli** – Run `pipx install bilibili-cli` for full functionality (search, hot list, video detail, audio) without login requirements.
2. **Optionally install OpenCLI** – Required for subtitle extraction; the Chrome extension state is detected automatically.
3. **Verify fallback availability** – If neither binary is present, the channel automatically degrades to the public search API for basic keyword lookup.

## Practical Code Example

```python
from agent_reach.channels.bilibili import BilibiliChannel

# Initialize and probe backends

chan = BilibiliChannel()
status, message = chan.check()
print(f"Active backend: {chan.active_backend}")
print(message)

# Search using the selected backend

results = chan.search("Python programming")

# Fetch video metadata (routes to bili-cli or OpenCLI)

video_info = chan.read("https://www.bilibili.com/video/BV1xx411y7Zt")

```

When `bili-cli` is installed, the channel invokes it internally (e.g., `bili search …`). If only OpenCLI is available, it routes through `opencli bilibili …` instead.

## Summary

- **yt-dlp is deprecated** in Agent Reach due to Bilibili HTTP 412 blocking; use `bili-cli` or OpenCLI instead.
- **Three backends** exist: `bili-cli` (full features, no login), OpenCLI (subtitles, needs Chrome), and the public Search API (basic fallback).
- **Selection logic** in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) (lines 46-72) probes `bili --version`, `opencli_status()`, and `_search_api_ok()` in that order.
- **Migration requires** installing `bilibili-cli` via pipx and optionally configuring OpenCLI for subtitle support.

## Frequently Asked Questions

### Why does yt-dlp no longer work with Bilibili in Agent Reach?

Bilibili's risk-control system now returns HTTP 412 for all `yt-dlp` requests, effectively blocking the tool regardless of cookies or proxy configurations. The maintainers removed yt-dlp support entirely from [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) and replaced it with `bili-cli` and OpenCLI integrations that bypass these restrictions.

### Do I need a Bilibili account to use Agent Reach?

No, if you install `bili-cli` via pipx, you gain search, hot-list, video detail, and audio extraction capabilities without authentication. However, **subtitle extraction requires OpenCLI**, which uses your logged-in Chrome session to access authenticated features.

### How does Agent Reach choose which backend to use?

The `check()` method probes backends in the order defined by `ordered_backends()`: first `bili-cli`, then OpenCLI, then the public API. The first backend returning "ok" becomes active. If earlier backends fail with errors but a later one succeeds, you receive both the success confirmation and error details for the failed alternatives.