anipy-cli — Anime Streaming via Claude Code

Overview

anipy-cli is a Python CLI tool for searching, streaming, and downloading anime. This skill enables Claude Code to act as a natural language interface for anipy-cli on Windows, handling dependency management, player routing, and all CLI operations non-interactively.

Dependency Repair Chain

When a command fails due to a missing dependency, diagnose and repair using this chain. Do NOT run these checks upfront — only when a failure occurs. Each installation requires AskUserQuestion confirmation — never install silently.

Repair order:

uv — uv --version → if missing, install (see references/setup-guide.md section 1). If both pwsh.exe and powershell.exe install methods fail, STOP and tell the user to install PowerShell 7 from the Microsoft Store, then restart their terminal.
anipy-cli — anipy-cli --version → if missing, uv tool install anipy-cli
Video player — check mpv (where.exe mpv), then vlc (where.exe vlc + common paths) → if neither found, ask user which to install (see references/setup-guide.md sections 3-5)
Config player_path — run anipy-cli --config-path to get the path, then verify the config file exists. If not, run anipy-cli --version 2>&1 to attempt generation; if config still missing, run a search command like anipy-cli -s "test:1:sub" 2>&1 to trigger full initialization. Then verify player_path matches an installed player, update if needed

Important: After installing scoop or any tool, the current shell session may not have updated PATH. Use full paths or pwsh.exe to invoke scoop commands. For exact install commands, see references/setup-guide.md.

Non-Interactive CLI Usage

anipy-cli supports non-interactive mode via the -s flag, which is essential for Claude Code integration since Claude cannot interact with terminal prompts.

Search and Play

anipy-cli -s "query:episode:sub/dub"

Format: {search_term}:{episode_or_range}:{sub|dub} (default: sub when user doesn't specify)

Examples:

anipy-cli -s "frieren:1:sub" — Play Frieren episode 1, subbed
anipy-cli -s "steins gate:1:sub" — Play Steins;Gate episode 1
anipy-cli -s "one piece:1-10:dub" — Binge One Piece episodes 1-10, dubbed
anipy-cli -s "spy x family:3:dub" — Play Spy x Family episode 3, dubbed

Modes

| Flag | Mode | Description | |------|------|-------------| | (none) | Default | Interactive search and play | | -s | Search | Non-interactive search with query:ep:type | | -D | Download | Download mode, combine with -s | | -B | Binge | Binge mode for episode ranges | | -H | History | Show watch history (interactive — will hang, read history.json instead) | | -S | Seasonal | Seasonal anime tracking (interactive — will hang, do not use) | | -A | AniList | AniList integration (interactive — will hang, do not use) | | -M | MAL | MyAnimeList integration (interactive — will hang, do not use) |

Common Options

| Flag | Purpose | |------|---------| | -p mpv\|vlc\|syncplay\|mpvnet\|mpv-controlled | Override player | | -q best\|worst\|720\|1080 | Set quality | | -v | Show version | | -h | Show help | | -VVV | Verbose debug output (-V = fatal only, -VVV = full info) | | --config-path | Print config file path | | --delete-history | Clear history |

Download Mode

Combine -D with -s for downloading:

anipy-cli -D -s "frieren:1-5:sub"

Download location is set in config.yaml under download_folder_path.

Binge Mode

Combine -B with -s for binge watching:

anipy-cli -B -s "frieren:1-5:sub"

History

To view history non-interactively, read history.json from the user_files_path directory specified in config.yaml. Do NOT use the -H flag — it is interactive and will hang in Claude Code's Bash tool. Always discover the config path dynamically via anipy-cli --config-path.

If history.json does not exist, tell the user "No watch history found."

Continue Watching

To resume where the user left off:

Read history.json from user_files_path (discover via anipy-cli --config-path → read config → get user_files_path)
Find the entry for the requested anime (match by title)
Get the last watched episode number and increment by 1
Play the next episode: anipy-cli -s "title:next_ep:sub" 2>&1

If the user says "next episode" without specifying an anime, show recent history entries and ask which one to continue.

Search Tips

The -s flag auto-selects the first search result via fuzzy matching. To improve accuracy:

Use specific titles: steins gate not gate, my hero academia not hero
Romaji titles often match better: boku no hero academia
Include distinguishing words for common titles

Player Routing

Priority order for player detection and configuration:

mpv (preferred) — better subtitle rendering, hardware decoding, scriptable
vlc — widely installed, good fallback
mpvnet — mpv fork with GUI, Windows-native
mpv-controlled — reuses existing mpv windows
syncplay — synchronized playback with others

Note: iina is also supported but macOS-only (not relevant for Windows).

When updating config.yaml player_path:

If player is on PATH: use just the name (mpv, vlc)
If not on PATH: use full path (C:\Program Files\VideoLAN\VLC\vlc.exe)
Always verify the path resolves before writing config

Configuration

Always discover the config path dynamically via anipy-cli --config-path (typically C:\Users\<username>\AppData\Local\anipy-cli\config.yaml).

Key fields:

player_path — video player executable or path
download_folder_path — download directory
preferred_type — sub or dub. Warning: if set to null, anipy-cli will prompt interactively for sub/dub choice, which hangs in Claude Code. Always specify :sub or :dub in the -s search string, or set this config value to sub or dub
providers — anime source providers per mode (default: allanime)
mpv_commandline_options — extra mpv flags
vlc_commandline_options — extra vlc flags

Safe Execution

Always use PYTHONIOENCODING=utf-8 prefix to avoid encoding crashes
Always add 2>&1 to capture stderr
Set reasonable timeouts (60s for search/play, 120s for downloads)
Never run anipy-cli with sudo or admin privileges — it doesn't need them

For Windows-specific errors and solutions, see references/troubleshooting.md.

Additional Resources

Reference Files

references/setup-guide.md — Step-by-step dependency installation flows with exact commands
references/troubleshooting.md — Windows-specific issues, error catalog, and solutions