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

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

pip install -e .          # For editable development install

# OR

pip install agent-reach

Run the environment setup to auto-detect required tools:

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:

pipx install bilibili-cli

# OR

uv tool install bilibili-cli

Verify the installation is available on your system PATH:

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:

agent-reach doctor | grep Bilibili

Expected output:

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

The 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 expose these capabilities to AI agents.

Search for Videos

Search Bilibili content without login:

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:

bili ranking --type hot -f yaml
bili hot -f yaml

Fetch Video Details

Extract metadata for specific videos using their BV or URL:

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:

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

How the Backend Selection Works

The agent_reach/channels/bilibili.py file implements the Channel base class from 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.
• 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 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. 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), 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}