EveryPublish/docs/superpowers/specs/2026-03-25-bilibili-cli-design.md

# Bilibili CLI Design

Date: 2026-03-25

## Summary

This design adds a `bilibili` platform branch under `sau` with the same user-facing shape as the existing `douyin` and `kuaishou` commands.

The key constraint is that users should not need to install `biliup` manually. The project will treat `biliup` as an internal runtime dependency:

- `sau bilibili ...` is the public entrypoint
- the program auto-downloads `biliup` when missing
- the program checks GitHub Releases on each run
- when a newer upstream release exists, the program auto-updates first and then continues

This design intentionally keeps the wrapper thin. It reuses the current Bilibili uploader semantics already present in the repository instead of inventing a brand-new parameter model.

## Goals

- Keep the user-facing CLI consistent with `sau douyin ...` and `sau kuaishou ...`
- Hide `biliup` installation from users
- Reuse current project concepts such as account files, `VideoZoneTypes`, scheduled publish, and existing example semantics
- Avoid over-abstracting the Bilibili integration

## Non-Goals

- Do not vendor `biliup` binaries into the repository
- Do not pin or maintain a local release manifest in the first version
- Do not add note/image publishing for Bilibili in the first version
- Do not redesign the existing Bilibili uploader domain model beyond what is needed for CLI integration

## Existing Project Context

The repository already has native Bilibili support:

- `uploader/bilibili_uploader/main.py` wraps `biliup.plugins.bili_webup`
- `examples/upload_video_to_bilibili.py` uses existing upload semantics
- `utils/constant.py` already defines `VideoZoneTypes`

The current local upload model is centered on:

- `file`
- `title`
- `desc`
- `tid`
- `tags`
- `dtime`

This design keeps that shape for the first CLI version.

## User-Facing CLI

### Supported commands

- `sau bilibili login`
- `sau bilibili check`
- `sau bilibili upload-video`

### Command contract

#### `sau bilibili login`

Purpose:

- ensure `biliup` is present and up to date
- trigger Bilibili login through `biliup`
- store account data using the project account-file convention

First version behavior:

- if `biliup` is missing, auto-download latest release
- if upstream has a newer release, auto-update first
- then invoke the login flow

#### `sau bilibili check`

Purpose:

- ensure `biliup` is present and up to date
- validate whether the configured Bilibili account is usable

First version behavior:

- combines local account-file presence with a practical `biliup`-based validation path
- keeps output simple and aligned with other platforms:
  - `valid`
  - `invalid`

#### `sau bilibili upload-video`

Purpose:

- ensure `biliup` is present and up to date
- upload one Bilibili video using the current repository semantics

First version parameters:

- `--account` required
- `--file` required
- `--title` required
- `--desc` required
- `--tid` required
- `--tags` optional
- `--schedule` optional

Decision:

- `tid` is required in v1
- this matches the current project model and avoids guessing a default zone

## Runtime Dependency Strategy

### Chosen strategy

`biliup` is not committed into this repository and is not a user-managed prerequisite.

Instead, `sau bilibili ...` automatically manages it at runtime:

1. locate local `biliup`
2. query upstream GitHub Release state
3. if missing or outdated, download latest release
4. replace local runtime copy
5. continue current command

### Why this strategy

- keeps repository size small
- removes manual installation burden from users
- preserves a single public entrypoint through `sau`
- avoids `git submodule`, which is not useful for release assets

### Trade-off accepted

This design intentionally accepts upstream instability risk:

- every run checks for updates
- a new upstream release may change CLI behavior
- the wrapper must therefore stay thin and resilient

This trade-off was explicitly accepted in exchange for lower maintenance overhead.

## Storage and Resolution

The implementation should use a local runtime tool cache instead of shipping binaries in git.

The exact cache directory can remain implementation-defined, but it should satisfy:

- writable by the current user
- reusable across commands
- isolated from source-controlled files

The resolver should be responsible for:

- discovering the current OS
- choosing the correct upstream release asset
- downloading and replacing the executable
- returning the resolved executable path

## Thin Wrapper Architecture

The wrapper should stay minimal and split responsibilities into only a few pieces:

### 1. Resolver

Responsibilities:

- check whether `biliup` exists locally
- query upstream release metadata
- download/update executable when needed
- return executable path

### 2. Runner

Responsibilities:

- invoke the resolved `biliup` executable
- collect exit code, stdout, and stderr
- convert obvious process failures into project-friendly runtime errors

### 3. CLI adapter in `sau_cli.py`

Responsibilities:

- parse `sau bilibili ...` arguments
- map them to the Bilibili runtime invocation
- keep help text consistent with existing platform subcommands

No deeper abstraction layers are required in v1.

## Mapping to Existing Project Concepts

The wrapper should align with existing repository behavior instead of inventing a second Bilibili model.

### Account files

The Bilibili branch should use the same account alias concept as other platforms:

- user passes `--account <name>`
- the project resolves the corresponding account file path

### Categories

`tid` remains a first-class parameter.

The existing `VideoZoneTypes` enum should stay reusable for:

- examples
- documentation
- future helper utilities

### Scheduling

`--schedule` should follow the same `sau` convention already used by other platforms:

- no `--schedule` means immediate publish
- providing `--schedule` means scheduled publish

The internal translation to Bilibili-specific runtime arguments happens inside the adapter layer.

## Error Handling

The wrapper should prefer simple, direct failure modes:

- download failure: clearly state that `biliup` auto-download failed
- update failure: clearly state that the latest release could not be prepared
- login failure: surface `biliup` login failure with project context
- check failure: return `invalid`
- upload failure: return non-zero and show the upstream error summary

The wrapper should not attempt to over-normalize all upstream error text in v1.

## Documentation Impact

When implemented, the following documentation should be updated:

- `README.md`
- `docs/CLI.md`
- install/update documentation
- a Bilibili skill similar to the Douyin/Kuaishou skills
- Bilibili example scripts

The user-facing messaging should consistently say:

- users interact with `sau bilibili ...`
- `biliup` is prepared automatically by the program

## Testing Strategy

Minimum verification expected once implemented:

- `sau bilibili login --account <name>`
- `sau bilibili check --account <name>`
- `sau bilibili upload-video ...`
- missing-runtime path triggers auto-download
- existing-runtime path reuses local binary
- outdated-runtime path updates before executing

Manual verification is acceptable for first integration because upstream login and upload are external-platform behaviors.

## Recommended Implementation Order

1. add `bilibili` subcommands to `sau_cli.py`
2. add a minimal resolver that can fetch/update `biliup`
3. add a minimal runner for subprocess execution
4. wire `login/check/upload-video`
5. update docs, examples, and skill definitions

## Final Decisions

- Public entrypoint stays `sau bilibili ...`
- First version supports `login`, `check`, and `upload-video`
- `tid` is required
- `biliup` is auto-downloaded
- every run checks GitHub Releases
- if a newer release exists, auto-update first and continue
- wrapper remains intentionally thin