# How to Set Up Bili-cli for Bilibili Hot Search and Video Details with Agent Reach

> Learn to set up Bili-cli for Bilibili hot search and video details using Agent Reach. Install the CLI, verify backend, and get instant access to Bilibili data.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-14

---

**To set up Bili-cli for Bilibili hot search and video details with Agent Reach, install the `bilibili-cli` binary via pipx, verify the backend activation with `agent-reach doctor`, and invoke commands through the Agent Reach channel which automatically routes requests to the CLI.**

The **Agent Reach** repository (`Panniantong/Agent-Reach`) provides a plug-in architecture that enables AI agents to interact with internet platforms through specialized channel classes. The Bilibili channel implementation in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) leverages **bili-cli** as its primary backend for login-free access to hot searches, rankings, and video metadata.

## Understanding the Bilibili Channel Backend Architecture

Agent Reach implements a **prioritized fallback system** for Bilibili operations, defined in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py). The channel probes three distinct backends and activates the first one reporting *ok* or *warn* status.

### The Three-Tier Backend Priority System

1. **bili-cli** — The primary backend for searching, hot-list retrieval, and video details. This CLI tool operates without requiring Bilibili login credentials and remains stable despite Bilibili's 412-blocking mechanisms that affect tools like `yt-dlp`.

2. **OpenCLI** — A fallback option specifically for subtitle extraction. This backend reuses an existing browser login session via the `opencli` command, activating only when `bili-cli` is unavailable or when authenticated access is required.

3. **B站搜索 API** — A zero-dependency HTTP fallback that provides basic search functionality via simple GET requests. This backend cannot retrieve video details and serves only as a last-resort option.

The `check` method (lines 46-73 in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py)) executes `probe_command` calls against each candidate, selecting the first operational backend and surfacing diagnostic messages for any failures.

## Installing Bili-cli for Agent Reach

### Step 1: Install Agent Reach

First, install the Agent Reach framework which provides the channel infrastructure and CLI wrapper.

```bash
pip install -e .          # For editable development install

# OR

pip install agent-reach

```

Run the environment setup to auto-detect required tools:

```bash
agent-reach install --env=auto

```

### Step 2: Install the Bili-cli Binary

Install the **bili-cli** tool using `pipx` (recommended for isolated binaries) or `uv`:

```bash
pipx install bilibili-cli

# OR

uv tool install bilibili-cli

```

Verify the installation is available on your system PATH:

```bash
bili --version
bili status

```

### Step 3: Verify Backend Activation

Run the diagnostic command to confirm the Bilibili channel recognizes `bili-cli` as the active backend:

```bash
agent-reach doctor | grep Bilibili

```

Expected output:

```

Bilibili → ok: bili-cli 可用（搜索/热门/排行/视频详情/音频，无需登录…）

```

The [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) module executes the health-check probes defined in the channel's `check` method, validating that the CLI responds correctly to test commands.

## Querying Bilibili Hot Search and Video Details

Once `bili-cli` is active, Agent Reach routes all Bilibili commands through this backend. The skill definitions in [`agent_reach/skill/SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/skill/SKILL.md) expose these capabilities to AI agents.

### Search for Videos

Search Bilibili content without login:

```bash
bili search "AI 教程" -f yaml

```

This returns structured YAML data containing video IDs, titles, authors, and view counts.

### Retrieve Hot Search and Rankings

Get the daily hot-list (热门) or specific rankings:

```bash
bili ranking --type hot -f yaml
bili hot -f yaml

```

### Fetch Video Details

Extract metadata for specific videos using their BV or URL:

```bash
bili video https://www.bilibili.com/video/BV1xK4y1Y7M7 -f yaml

```

This command retrieves the video title, description, upload date, view statistics, and direct media URLs without requiring authentication.

### Optional: Subtitle Extraction via OpenCLI

If you need subtitles and have a browser login session, use the OpenCLI fallback:

```bash
opencli bilibili subtitle https://www.bilibili.com/video/BV1xK4y1Y7M7 -f yaml

```

## How the Backend Selection Works

The [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) file implements the `Channel` base class from [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py), defining the `can_handle`, `read`, `search`, and `check` methods.

When an agent requests Bilibili data, the channel executes the following logic:

1. **Probe Phase**: The `check` method runs `probe_command` against `bili-cli`, `opencli`, and the HTTP API in sequence.
2. **Selection Phase**: The first backend returning *ok* or *warn* status becomes the active handler for the session.
3. **Execution Phase**: All subsequent `search` or `read` calls route through the selected backend's command interface.

If `bili-cli` is installed but returns errors, the diagnostic output from `agent-reach doctor` specifies the exact failure point, allowing targeted remediation.

## Summary

- **Agent Reach** uses a **three-tier backend system** for Bilibili, prioritizing `bili-cli` for login-free operations.
- Install `bili-cli` via `pipx install bilibili-cli` to enable hot search and video detail queries.
- Verify activation using `agent-reach doctor`, which probes the channel's `check` method in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py).
- Execute searches with `bili search`, rankings with `bili ranking`, and metadata extraction with `bili video`.
- The system automatically falls back to **OpenCLI** or the **B站搜索 API** if the primary CLI is unavailable.

## Frequently Asked Questions

### What is the difference between bili-cli and OpenCLI backends?

**bili-cli** is the primary backend that handles searching, hot-lists, and video details without requiring Bilibili login credentials. **OpenCLI** serves as a fallback specifically for subtitle extraction when you have an existing browser login session, as it can reuse authenticated cookies from your browser.

### Why does Agent Reach prefer bili-cli over yt-dlp for Bilibili?

According to the [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py) implementation, Bilibili aggressively blocks `yt-dlp` with 412 precondition failed errors, making it unreliable. The `bili-cli` tool remains stable against these blocks and provides structured output formats (YAML/JSON) that integrate cleanly with the Agent Reach channel architecture.

### How do I troubleshoot when bili-cli is not detected?

Run `agent-reach doctor` to execute the diagnostic probes defined in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py). The output shows whether the `check` method found `bili-cli` on your PATH. If missing, ensure the binary location is in your shell's PATH environment variable, or reinstall using `pipx install bilibili-cli --force`.

### Can I use Bilibili features without installing bili-cli?

Yes, but with limited functionality. If `bili-cli` is unavailable, the channel automatically falls back to the **B站搜索 API** (lines 12-20 in [`agent_reach/channels/bilibili.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/bilibili.py)), which supports basic search via HTTP GET requests but cannot retrieve video details. For full functionality including hot-lists and video metadata, `bili-cli` is required.