How pystardust/ani-cli works
Purpose and Entry Point
ani-cli is a Bash-based terminal application for searching, selecting, streaming, and downloading anime scraped from HiAnime. The executable implementation is the repository-root script at ani-cli; its user-facing interface and options are documented in README.md and the Unix manual page ani-cli.1.
Runtime Model
The application runs in a Unix-compatible shell, including Git Bash on Windows and Termux on Android. It is intentionally a single-script architecture: orchestration, scraping, interactive selection, URL extraction, playback, download, and update behavior are concentrated in ani-cli. This makes shell command availability and platform behavior a primary operational boundary.
Discovery and Selection Pipeline
The core flow begins from CLI arguments or an interactive search, retrieves and parses HiAnime content, then presents titles and episodes through fzf. Text extraction and request handling rely on shell utilities such as curl, grep, and sed; Cloudflare-compatible access may require curl-impersonate. The single script ani-cli owns this scrape-to-selection control flow.
Playback Boundary
After an episode/provider stream is resolved, ani-cli delegates media handling to an external player rather than embedding playback. mpv is the main target; IINA is the macOS-compatible mpv replacement, and VLC is an optional alternative. Player invocation must carry stream metadata such as the required referrer, notably on Android. Optional intro/outro skipping is delegated through mpv’s Lua integration to external ani-skip tooling. Relevant user contract: README.md, ani-cli.
Download Boundary
For -d download operations, the script hands stream acquisition to yt-dlp, with ffmpeg as a fallback for m3u8 content. Download location is controlled externally through ANI_CLI_DOWNLOAD_DIR; episode-range selection supports bulk downloading. The downloader/player dependency boundary keeps media protocol handling outside the Bash implementation. Core path: ani-cli.
Distribution and Self-Maintenance
The root script is installed directly by source-based instructions and packaged by OS ecosystems. Formula/ani-cli.rb provides the Homebrew formula. Self-update behavior (-U) depends on Git/network retrieval and patch, so updates are an operational capability of the executable rather than a separate release client. ani-cli.1 is the packaged/manual-facing CLI specification.
Automation and Governance
GitHub Actions provide repository maintenance automation rather than runtime functionality: inverse-ani.yml and inverse-md.yml likely validate synchronization or inversions between the script and docs, while version.yml governs version-related checks. Contribution and ownership controls reside in .github/CODEOWNERS, CONTRIBUTING.md, and workflow definitions under .github/workflows/.
Main entry points: ani-cli ani-cli · README.md README and manual · ani-cli.1 ani-cli.1 · ani-cli.rb Homebrew formula
Components 20
Runtime pipeline
Single Bash script owns discovery through media delegation.
- ani-cli · Single-script CLI orchestrator.
ani-cli - CLI arguments / search
- HiAnime discovery · Searches and parses titles and episode data.
ani-cli - Interactive selection · Chooses titles and episodes.
ani-cli - Provider stream resolution · Resolves episode streams and referrer metadata.
ani-cli - Playback delegation · Invokes an external player with stream metadata.
ani-cli - Download delegation · Handles -d and episode-range downloads.
ani-cli
External services & tools
Network, shell utilities, and media clients are operational dependencies.
- HiAnime
- curl, grep, sed
- curl-impersonate · May be needed for Cloudflare-compatible access.
- fzf
- mpv / IINA / VLC · mpv is primary; IINA and VLC are alternatives.
- ani-skip tooling · Optional intro and outro skipping.
- yt-dlp / ffmpeg · ffmpeg is an m3u8 fallback.
Distribution & maintenance
Installation, update, documentation, and repository automation.
- README and manual · User-facing options and usage documentation.
README.md - ani-cli.1
ani-cli.1 - Homebrew formula
Formula/ani-cli.rb - Self-update (-U) · Uses Git, network retrieval, and patch.
ani-cli - GitHub governance
CONTRIBUTING.md - GitHub Actions · Documentation synchronization and version checks.
Connections 20
- CLI arguments / search → ani-cli: invokes
- ani-cli → HiAnime discovery: searches
- HiAnime discovery → HiAnime: requests content
- HiAnime discovery → curl, grep, sed: uses
- HiAnime discovery → curl-impersonate: optionally uses
- HiAnime discovery → Interactive selection: produces choices
- Interactive selection → fzf: presents via
- Interactive selection → Provider stream resolution: selects episode
- Provider stream resolution → Playback delegation: stream mode
- Provider stream resolution → Download delegation: -d mode
- Playback delegation → mpv / IINA / VLC: launches
- mpv / IINA / VLC → ani-skip tooling: optional Lua integration
- Download delegation → yt-dlp / ffmpeg: acquires media
- README and manual → ani-cli: documents
- ani-cli.1 → ani-cli: specifies
- Homebrew formula → ani-cli: packages
- ani-cli → Self-update (-U): -U triggers
- GitHub governance → GitHub Actions: maintained by
- GitHub Actions → README and manual: validates synchronization
- GitHub Actions → ani-cli: checks versions and inversions