anime-cli

A terminal-based anime manager and player for organizing and watching anime episodes.

anime-cli can organize episode files into the structure expected by the application, search MyAnimeList for anime information, and launch episodes through VLC.

Features

• Browse your anime collection from the terminal.
• Play episodes using VLC.
• Keep track of watched episodes.
• Organize episode filenames.
• Rename an existing series directory with --rename.
• Search MyAnimeList for anime information through the project's hosted API.
• Store application configuration outside the project directory.
• Terminal interface using curses.

Requirements

• Python 3.10 or newer
• VLC
• pipx
• Internet access for MAL-related features

VLC must be available as an executable on your system.

Linux

On Arch Linux:

sudo pacman -S vlc python-pipx

Then make sure pipx applications are available on your PATH:

pipx ensurepath

Restart your shell after running pipx ensurepath.

Windows

Install Python, VLC, and pipx. Make sure both Python and VLC are available to the application.

Installation

anime-cli is installed with pipx, which keeps the application's Python dependencies isolated while making the anime command available globally.

From PyPI

Once the package is published:

pipx install anime-cli

After installation, run:

anime

The command works regardless of your current directory.

From a local wheel

To install a locally built version:

pipx install ./dist/anime_cli-0.1.0-py3-none-any.whl

You can then use:

anime

from any directory.

Usage

Open the anime menu

anime

This opens the main menu where you can browse your configured anime directory.

Menu commands

Press : in a menu to open its internal command line. The following commands are currently available:

• open <entry> (or o) — open an entry by its one-based menu number or exact name; for example, open 2 or open Nisekoi. From an episode-selection menu, this switches to the named anime in the collection.
• play <anime> [episode] (or p) — from the anime-selection menu, play an anime from its first unwatched episode, or from an optional episode such as ep3. For example: play Nisekoi ep3.
• play [episode] (or p) — from an episode-selection menu, play the current anime from its first unwatched episode, or from the specified episode.
• rename <anime> — from the anime-selection menu, rename the named series' episode files into the application naming structure.
• rename [anime] — from an episode-selection menu, rename the current series' files, or a named series elsewhere in the collection.
• add <directory> — from the anime-selection menu, move a series directory into the collection; quote the path when it contains spaces. The Add series menu button opens a directory picker for the same action.
• move <anime> [destination] — from the anime-selection menu, move a named series out of the collection. When no destination is given, it moves to the current user's home directory.
• quit (or q) — exit anime-cli from the anime-selection menu, or return to that menu from an episode-selection menu.

Open an anime directly

anime "anime name"

For example:

anime nisekoi

Play an episode

An episode can be selected through the anime menu or specified after the anime name:

anime nisekoi ep1

Add a series directory

Move a series directory into the configured anime collection:

anime --add /path/to/Nisekoi

The source directory is moved rather than copied. The command will not overwrite an existing series with the same directory name.

Move a series out of the collection

Move a configured series to a destination directory:

anime --move "Nisekoi" /path/to/destination

When the destination is omitted, the series is moved to your home directory. On Windows, this uses the current user's home folder and accepts standard Windows paths:

anime --move "Nisekoi" "C:\Users\Jeff\Videos"

Directory Structure

anime-cli expects your anime collection to be organized approximately like this:

anime/
├── Nisekoi/
│   ├── ep1-...
│   ├── ep2-...
│   └── ep3-...
│
├── Naruto/
│   ├── ep1-...
│   ├── ep2-...
│   └── ep3-...
│
└── One Piece/
    ├── ep1-...
    ├── ep2-...
    └── ep3-...

The configured directory should contain the series folders, rather than being a single series folder.

Renaming Episodes

If your episodes aren't using the naming structure expected by anime-cli, use:

anime --rename

This opens a menu allowing you to:

1. Enter a directory path.
2. Select a directory using a file explorer.
3. Exit.

You can also provide the directory directly:

anime --rename /path/to/anime

For example:

anime --rename ~/Downloads/Nisekoi

The renamer converts the files into the episode naming scheme used by the application.

Make sure you have a backup if the directory contains files you don't want renamed.

Configuration

Application configuration is stored in the user's configuration directory rather than inside the project.

The application creates its configuration directory automatically when needed.

The configured anime directory is stored in a structure similar to:

{
    "anime_list": "/path/to/your/anime"
}

Personal configuration files should not be committed to the project repository.

MyAnimeList API

MAL requests are not made directly by the installed CLI.

The architecture is:

anime-cli
    │
    │ HTTPS
    ▼
Hosted anime-cli API
    │
    │ X-MAL-CLIENT-ID
    ▼
MyAnimeList API

The MAL client ID exists only on the hosted server. It is supplied through the server's MAL_CLIENT_ID environment variable and is never included in the CLI package.

Users therefore do not need to create a MyAnimeList developer application, configure a MAL client ID, or keep an API credential on their computer.

Running the API server locally

The API can also be run locally for development. From the repository root:

export MAL_CLIENT_ID="your_client_id"
uvicorn server.main:app --reload

Then point the CLI at the local server:

export ANIME_API_URL="http://127.0.0.1:8000"
anime

The production client defaults to the hosted API URL. ANIME_API_URL is only needed when overriding it, such as for local development or testing.

Deploying the server

The repository contains a server/Dockerfile and render.yaml for deployment. A Render deployment can use the repository's render.yaml configuration.

Set the following secret in the hosting provider:

MAL_CLIENT_ID=your_mal_client_id

Do not put the actual client ID in render.yaml, Dockerfiles, source code, or Git.

The server exposes only the operations needed by the CLI:

GET /anime/search?q=<name>
GET /anime/<id>

The server also keeps the existing SQLite API cache, so repeated MAL requests can be served without contacting MAL every time.

Cache

anime-cli maintains a local cache for application data, while the hosted API maintains its own cache for MAL responses.

Runtime cache databases should not be committed to the repository.

For example, a Git repository should ignore:

*.db

Updating

If anime-cli was installed with pipx, update it with:

pipx upgrade anime-cli

If a new release is available on PyPI, pipx will install the updated version.

Uninstalling

To remove anime-cli:

pipx uninstall anime-cli

Development

Clone the repository:

git clone https://github.com/jeff841/anime-cli
cd anime-cli

Create a development virtual environment:

python -m venv .venv
source .venv/bin/activate

Install the project in editable mode:

pip install -e .

This allows changes to the source code to be tested without rebuilding the package after every change.

Building

Install the Python build frontend:

python -m pip install build

Build the package:

python -m build

This creates the distribution files in dist/:

dist/
├── anime_cli-0.1.0-py3-none-any.whl
└── anime_cli-0.1.0.tar.gz

Test the built wheel with pipx

You can test the exact wheel that will be distributed:

pipx install ./dist/anime_cli-0.1.0-py3-none-any.whl

Then test the application from outside the repository:

cd ~
anime --help

This verifies that the installed package works independently of the source directory.

If the package is already installed, reinstall the newly built wheel:

pipx reinstall ./dist/anime_cli-0.1.0-py3-none-any.whl

Git

Generated files and local configuration should not be committed.

A suitable .gitignore includes:

.venv/
__pycache__/
*.py[cod]
build/
dist/
*.egg-info/
*.db
.env

Source code, pyproject.toml, documentation, and other files required to build and distribute the application should be committed.

Project Structure

anime-cli/
├── anime/
│   ├── __init__.py
│   ├── __main__.py
│   ├── remote_api.py
│   ├── cli.py
│   ├── episode.py
│   ├── extra.py
│   ├── kitty.py
│   ├── main.py
│   ├── picture.py
│   ├── play.py
│   ├── renamer.py
│   ├── reset_watched.py
│   └── watch_input.py
├── server/
│   ├── __init__.py
│   ├── config.py
│   ├── main.py
│   ├── mal.py
│   ├── Dockerfile
│   └── requirements.txt
├── render.yaml
├── README.md
├── pyproject.toml
└── .gitignore

License

Add your chosen license here before publishing the project.

Status

anime-cli is currently in early development.

The 0.1.0 release is an initial release while the application's interface and features continue to mature.