Metadata-Version: 2.4
Name: anime-ctl
Version: 0.1.1
Summary: CLI for managing and watching anime
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: platformdirs
Requires-Dist: windows-curses; platform_system == "Windows"
Requires-Dist: httpx
Requires-Dist: requests

# 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:

```bash
sudo pacman -S vlc python-pipx
```

Then make sure `pipx` applications are available on your `PATH`:

```bash
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:

```bash
pipx install anime-cli
```

After installation, run:

```bash
anime
```

The command works regardless of your current directory.

### From a local wheel

To install a locally built version:

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

You can then use:

```bash
anime
```

from any directory.

## Usage

### Open the anime menu

```bash
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

```bash
anime "anime name"
```

For example:

```bash
anime nisekoi
```

### Play an episode

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

```bash
anime nisekoi ep1
```

### Add a series directory

Move a series directory into the configured anime collection:

```bash
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:

```bash
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:

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

## Directory Structure

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

```text
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:

```bash
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:

```bash
anime --rename /path/to/anime
```

For example:

```bash
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:

```json
{
    "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:

```text
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:

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

Then point the CLI at the local server:

```bash
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:

```text
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:

```text
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:

```gitignore
*.db
```

## Updating

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

```bash
pipx upgrade anime-cli
```

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

## Uninstalling

To remove `anime-cli`:

```bash
pipx uninstall anime-cli
```

## Development

Clone the repository:

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

Create a development virtual environment:

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

Install the project in editable mode:

```bash
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:

```bash
python -m pip install build
```

Build the package:

```bash
python -m build
```

This creates the distribution files in `dist/`:

```text
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:

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

Then test the application from outside the repository:

```bash
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:

```bash
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:

```gitignore
.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

```text
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.
