anime-sh

Watch anime from your terminal.

Type a title. It finds a source, picks a mirror that works, and plays it in mpv.
Providers, mirrors and resolvers are plumbing you never have to think about.

🚀 One line, from nothing

Both of these work on a machine with nothing on it. No Python, no administrator, no editing PATH by hand. mpv is installed alongside, because without it nothing plays.

Windows — paste into a normal PowerShell, not an administrator one:

irm https://raw.githubusercontent.com/Anime123450/anime-sh/master/install.ps1 | iex

macOS and Linux:

curl -LsSf https://raw.githubusercontent.com/Anime123450/anime-sh/master/install.sh | sh

Then run anime.

irm https://raw.githubusercontent.com/Anime123450/anime-sh/master/install.ps1 -OutFile install.ps1
.\install.ps1 -DryRun

curl -LsSf https://raw.githubusercontent.com/Anime123450/anime-sh/master/install.sh -o install.sh
sh install.sh --dry-run

📖 Contents

⚡ Install · 🔌 PATH · ▶️ A minute with it · 🎬 What you get · 🚀 First run · ⌨️ Keys · 🎨 Themes · 🔗 AniList · 📋 Commands · ⚙️ Config · 🩺 Troubleshooting · 🛠️ Develop

⚡ Install

Prefer to drive your own package manager? Each of these is live.

🥄 Scoop — the quickest route on Windows

# Skip these two if you already have Scoop.
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

scoop bucket add extras
scoop bucket add anime-sh https://github.com/Anime123450/scoop-anime-sh
scoop install anime-sh

Use a normal PowerShell. Scoop installs per-user and refuses to run elevated.

The first line is what stops Windows refusing the second one with a message about running scripts being disabled. It applies to your account only, and RemoteSigned still requires downloaded scripts to be signed — it is what Microsoft ships on Windows Server. Answer Y when it asks.

The extras bucket is not optional. mpv lives there, a fresh Scoop has only main, and anime-sh declares mpv as a dependency — so without that bucket the install stops on something it cannot resolve.

Scoop's shims directory went on your PATH when you installed Scoop, so anime works immediately in the same window.

🍫 Chocolatey

choco install anime-sh

mpv comes with it. For downloads, choco install ffmpeg.

Chocolatey edits the machine PATH, which your current terminal read when it started. Open a new one.

🍺 Homebrew — macOS and Linux

brew tap Anime123450/anime-sh
brew install anime-sh

mpv comes with it. For downloads, brew install ffmpeg.

This builds from source: 10–20 minutes. Two CI runs of 0.2.89 measured 11m and 12m on macOS, 14m and 20m on Linux — runner speed is most of the spread. A tap carries no prebuilt bottles, so Homebrew builds anime-sh and any dependency it cannot pour — pydantic-core is Rust, and it is most of that time. Upgrades reuse what is already built.

It used to be closer to an hour, almost all of it compiling Pillow; 0.2.89 pours Homebrew's instead.

If that is still unappealing, the one-liner at the top uses uv and finishes in seconds.

🐍 uv — any OS, no Python needed

uv is one standalone binary that brings its own Python, so this works on a machine with no Python at all.

# 1. uv, and mpv
curl -LsSf https://astral.sh/uv/install.sh | sh    # macOS / Linux
brew install mpv                                   # or apt / dnf / pacman

# 2. anime-sh
uv tool install "anime-sh[tui]"

# 3. put it on PATH, once
uv tool update-shell

On Windows the same thing, with winget install astral-sh.uv and winget install shinchiro.mpv for step 1.

Do not drop the [tui]. Without it anime still installs and anime --version still answers, so a missing extra is easy to miss until the interface refuses to start.

uv tool update-shell edits the right profile for your shell. Open a new terminal afterwards, or export PATH="$HOME/.local/bin:$PATH" for this one.

📦 pipx

pipx install "anime-sh[tui]"
pipx ensurepath

pipx is itself a Python package, so it cannot be the first thing installed on a clean machine. Already have it? Then this is fine.

🐧 Arch

yay -S anime-sh    # or: paru -S anime-sh

git clone https://github.com/Anime123450/anime-sh.git && cd anime-sh
uv sync --extra tui
uv run anime

🔌 Will anime be on my PATH?

Yes, with every method except the bare .exe. The longer answer earns its space, because "command not found straight after installing" is the most common thing people hit and it is almost never a broken install.

Why it happens. A program is found by searching the directories in PATH. An installer adds its directory to the stored PATH, but a terminal reads that value once, when it opens. Your terminal is still holding the old copy. The install worked. The window has not heard about it.

Repair the window you already have, without restarting it:

# Windows
$env:Path = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' +
            [Environment]::GetEnvironmentVariable('Path','User')

# macOS / Linux
export PATH="$HOME/.local/bin:$PATH"

Two copies? Install with two managers and anime exists twice, with PATH order quietly deciding which runs — so upgrading one can look like it did nothing at all. where.exe anime on Windows, which -a anime on Unix, lists every match. The Windows one-line installer warns about this rather than silently adding a second.

What you need alongside it

anime doctor checks all of them and prints the exact command for whichever package manager you actually have. anime doctor --streams goes further and plays something through each provider from your own connection, which answers "is it broken, or is it me?"

▶️ A minute with it

_{Home · search-as-you-type · a show's episodes, in two of the three layouts}

Every frame is the real application, rendered and captured from the app itself. Not a mockup of it.

🎬 What you get

🚀 First run

anime            # the TUI

One show leads, large, at the top: its cover art beside what it is, how far into the episode you got, when the next one airs, and what Enter will do.

Under it are shelves of cover art you walk sideways — Continue Watching, Favourites, This Season, Trending. ← → move along a shelf, ↑ ↓ change shelves, and a digit jumps straight to one. Whatever the cursor lands on becomes the show at the top, so the detail is always for exactly one thing and never for all of them at once. Each poster carries its own one line of state underneath — ep 8 · 18%, 3 eps ready, ep 9 in 1d 4h. The bottom row always says what the poster under the cursor can do.

It fits what it is given. Posters stay 14 cells wide at every size, so a wider terminal means more shows on a shelf rather than bigger ones; the panel at the top grows its poster from 16 cells to 24 across the breakpoints, and drops out below 30 rows, where the shelves need every row there is. v tightens the spacing if you would rather have one more shelf than the air between them.

Covers are cached on disk after the first fetch, so every launch after the first paints the whole wall in one frame. anime cache info says how much that is, and anime cache clear takes it back.

Prefer one-shot commands? anime "Frieren" searches, takes the best match and plays episode 1. anime play "Frieren" -e 18 --dub -q 1080p spells it all out.

Shell tab-completion is one command: anime --install-completion.

⌨️ Keys

🎨 Themes

Press t. Moving the cursor applies each theme to the whole app at once, so you choose by looking at anime-sh rather than at a list of names. Enter keeps it, Esc restores the one you arrived with.

Three are anime-sh's own — midnight (the default), ember and paper — next to tokyo-night, nord, gruvbox, dracula, catppuccin-mocha and solarized-light.

Cover art is drawn with unicode block sextants, so no special terminal is required — a poster on a shelf is 14 cells wide and the one at the top is 24. On Sixel or kitty terminals the large one sharpens to a true bitmap automatically.

🔗 Linking AniList (optional)

Everything works without an account. Linking one adds two-way sync: finish an episode here and your phone knows, and anime sync pull brings in whatever you have been watching elsewhere.

anime-sh ships no API credentials, and there is no shared app to sign in through. You create your own client. It takes about a minute, and it means the token belongs to you:

1. Open AniList → Settings → Developer and create a client.
2. Name: anything. Redirect URL: https://anilist.co/api/v2/oauth/pin
3. Link it:

anime auth login --client-id <YOUR_ID> --secret <YOUR_SECRET>

The token is written to your own config directory with 0600 permissions, goes nowhere but AniList, and anime auth logout deletes it. Nothing about your account is stored in this project.

📋 Command reference

# ▶️  Watch
anime                          # the TUI
anime "Frieren"                # search, best match, play episode 1
anime play "Frieren" -e 18     # a specific episode
anime play "Frieren" --dub -q 1080p
anime resume                   # pick up the show you watched most recently
anime continue                 # what to watch next in every show you have going
anime sources "Frieren"        # every provider entry that matches
anime next "Frieren"           # find and play the sequel

# 🔭  Discover
anime search "frieren"         # AniList search, no providers touched
anime trending
anime seasonal                 # defaults to the current season
anime calendar                 # what is airing, and when
anime random
anime recommend "Frieren"
anime related "Frieren"

# 📚  Library and tracking
anime history
anime stats                    # what you watched here, plus your tracker's total
anime wrapped                  # your year, with a shareable SVG card
anime favorite add "Frieren"
anime favorite list
anime unmark "Frieren"         # clear local progress for a show

# 🔗  AniList
anime auth login --client-id <ID> --secret <SECRET>
anime auth logout
anime list --status watching
anime rate "Frieren" 9
anime status "Frieren" completed
anime sync push                # episodes you finished  ->  AniList
anime sync pull                # AniList  ->  local library

# ⬇️  Downloads
anime download "Frieren" -e 1-12
anime downloads                # what is already on disk
anime prefetch                 # next episode of everything you are watching

# 🎨  Appearance
anime themes

# 🧹  Housekeeping
anime doctor                   # player, ffmpeg, cover art, config, database, plugins
anime doctor --streams         # actually play through each provider
anime providers health         # circuit-breaker state per provider
anime config get ui.theme
anime config set ui.theme ember
anime --install-completion

⚙️ Config

anime config set <section>.<key> <value> writes one; anime config get reads it back. Only keys you set are stored, so defaults can keep improving without your file pinning them in place.

anime config set playback.audio dub
anime config set playback.quality 1080p
anime config set ui.episodes grid
anime config set downloads.dir ~/Videos/anime

Any of them can be set by environment variable instead, which is the easier route for one-off runs and for scripts that should not touch your config file. The name is ANIME_SH_, the section, two underscores, then the key — and it wins over the file for that one setting, leaving the rest of your config alone.

ANIME_SH_PLAYBACK__AUDIO=dub anime play "Frieren"
ANIME_SH_UI__THEME=nord anime

When more than one of them sets the same thing, the winner is, highest first: a flag on the command line, an environment variable, your config file, the built-in default.

🩺 Troubleshooting

🛠️ Develop

git clone https://github.com/Anime123450/anime-sh.git && cd anime-sh
uv sync --extra dev --extra tui
uv run pytest -q          # the full suite
uv run lint-imports       # layering contracts
uv run anime

The architecture is layered, and the layering is enforced rather than aspirational: cli > tui > app > domain, with infra, providers and resolvers as adapters. uv run lint-imports fails the build when a layer reaches somewhere it should not.

Providers and resolvers are found through entry points (anime_sh.providers, anime_sh.resolvers), so a new one is just a package that declares one.

A nightly canary plays a real episode through every provider and opens an issue when one breaks. It fails the run only when nothing can play, because a single provider dying is the normal operating state here, and an alert that fires every night is one nobody reads.

📄 Architecture · Writing a plugin · Engineering standards · Contributing · Packaging

The engineering standards are worth a read even if you never contribute — every rule names the bug that caused it.

⚖️ Legal

anime-sh is a client, not a content library. It bundles no media, mirrors nothing, and bypasses no DRM. Providers read public pages and are expected to break; a broken provider is a degraded experience rather than an outage, and provider plugins are separable from the core, so the project outlives any one of them.

mpv and ffmpeg are declared as dependencies and never redistributed. Both are GPL-licensed, and shipping their binaries inside an MIT release would carry obligations that depending on them does not.

Not affiliated with AniList, mpv, or any provider.