Metadata-Version: 2.5
Name: emby-cli
Version: 0.6.0
Summary: CLI to list, search, play, and download/backup original media from an Emby server via its REST API.
Project-URL: Homepage, https://github.com/soukron/emby-cli
Project-URL: Repository, https://github.com/soukron/emby-cli
Project-URL: Issues, https://github.com/soukron/emby-cli/issues
Author-email: Sergio Garcia <soukron@gmbros.net>
Maintainer-email: Sergio Garcia <soukron@gmbros.net>
License-Expression: CC-BY-NC-4.0
License-File: LICENSE
Keywords: backup,cli,download,emby,media
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: Free for non-commercial use
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.9
Requires-Dist: m3u8>=4.0
Requires-Dist: requests>=2.31
Requires-Dist: static-ffmpeg>=3.0
Requires-Dist: tqdm>=4.66
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# emby-cli

[PyPI](https://pypi.org/project/emby-cli/)
· [License: CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/)

Search, browse, play, and download media from your [Emby](https://emby.media/) server — from the terminal. Only HTTP access to the server is needed (typically port 8096). No SSH, no shared folders, no rsync.

```bash
pip install emby-cli
```

---

## Quick start

**1. Log in once** (username + password, or an API key):

```bash
emby-cli login --server http://emby:8096 --username you
# prompted for password if not set
```

Your session is saved locally. Later commands reuse it, so you usually do not need to pass `--server` again.

**2. Check the connection:**

```bash
emby-cli info
```

**3. Search and play:**

```bash
emby-cli search --item "matrix"
emby-cli play --item "matrix (1999)" --pick-best-item
```

Use `emby-cli help` for the command list, and `emby-cli <command> -h` for options.

---



## Everyday use



### Server info

```bash
emby-cli version    # CLI version (and Emby version when connected)
emby-cli info       # user, server, library count, content totals
```



### Search

Find movies, episodes, and other media — or list libraries:

```bash
emby-cli search --item "fast and furious"
emby-cli search --item "fast and furious" --count 5
emby-cli search --item "spider-man" --type Movie --year 2017
emby-cli search --item --id 123456
emby-cli search --library "peliculas"
emby-cli search --library --count all
emby-cli search --library --order-by items --desc --count 1
emby-cli search --item "matrix" --order-by resolution --desc --no-cache
```

`--item` and `--library` accept the search text directly. You can also pass `--id` when you already know the Emby ID.

### Show details

Inspect one title or one library by Emby ID (use `search` first if you need to find the ID):

```bash
emby-cli show --item --id 123456
emby-cli show --library --id 614156
emby-cli show --item --id 123456 --no-cache
```



### Play

Open a title in an external player (VLC, mpv, IINA, …):

```bash
emby-cli play --item "matrix (1999)" --pick-best-item
emby-cli play --id 123456
emby-cli play --id 111,222,333
emby-cli play --id 123456 --player vlc --wait
```

Set `EMBY_PLAYER` if the player is not found automatically. A comma-separated list of IDs works for `play --id` and `download --item --id` (not for `show` / `search`).

### Download

Download a single title, a whole library, or a list of titles from a file:

```bash
emby-cli download --item --id 123456
emby-cli download --item --id 111,222,333
emby-cli download --item "breaking bad S01E01" --pick-best-item
emby-cli download --library "peliculas 4k"
emby-cli download --from-file titles.txt
```

A comma-separated list of IDs (`a,b,c`) is supported for `download --item --id` and `play --id`. `show` and `search` accept a single `--id` each.

Useful options:


| Option             | Meaning                                           |
| ------------------ | ------------------------------------------------- |
| `-n` / `--dry-run` | Resolve titles only — do not write files          |
| `-o` / `--output`  | Output folder (default `./downloads`)             |
| `-f` / `--force`   | Re-download even if a matching local file exists  |
| `--pick-best-item` | When several versions match, pick the best ≤1080p |
| `-m` / `--method`  | Download method                                            |


**Title lines** in `--item` / `--from-file` can look like:

- `Movie (2010)`
- `Show S01E05`
- `Show S01` — whole season

By default, matching is **strict**: a wrong year or several ambiguous results stops with a table of candidates. Add `--pick-best-item` to choose automatically (best quality up to 1080p).

Library downloads match the library **name** (case-insensitive, unique match required).

### Data cache

Read-only commands (`search`, `show`, `play`, `info`) use a JSON disk cache under
`~/.cache/emby-cli/data` (or under `EMBY_CACHE_DIR/data`).

- Default TTL: **600 seconds** (`EMBY_DATA_CACHE_TTL` to override).
- `--no-cache`: do not read cache; call API directly and refresh cache on disk.
- Cache keys are isolated by **server URL + user ID** to prevent cross-server mixing.
- `download` never uses this data cache.

---



## Logging in and switching servers


| Approach         | When to use                                                        |
| ---------------- | ------------------------------------------------------------------ |
| `emby-cli login` | Recommended — saves a session and remembers the server             |
| API key          | `--api-key` / `EMBY_API_KEY` (keys are not stored by `login`)      |
| Flags / env      | `--server`, `--username`, `--password` or `EMBY_*` for one-off use |


Manage saved servers:

```bash
emby-cli config get-servers
emby-cli config current-server
emby-cli config use-server 'you@http://emby:8096'
emby-cli config view          # tokens redacted
emby-cli logout               # revoke and forget the current session
```

Sessions live under `~/.cache/emby-cli/auth.json` (override with `EMBY_CACHE_DIR`). Set `EMBY_NO_AUTH_CACHE=1` to never read or write the cache.

---



## Download methods

Choose with `-m` / `EMBY_METHOD`:


| Method               | Best for                                |
| -------------------- | --------------------------------------- |
| `download` (default) | Normal file download from Emby          |
| `stream`             | Direct stream URL (similar to Emby Web) |
| `hls`                | HLS remux to `.mkv`                     |


---



## Configuration reference

Flags override environment variables. Optional template: `.env.example` (export the vars yourself — the CLI does not load `.env` files).


| Variable                          | Description                                         |
| --------------------------------- | --------------------------------------------------- |
| `EMBY_SERVER`                     | Server URL                                          |
| `EMBY_API_KEY`                    | API key                                             |
| `EMBY_USERNAME` / `EMBY_PASSWORD` | Username / password                                 |
| `EMBY_OUTPUT`                     | Download directory (default `./downloads`)          |
| `EMBY_METHOD`                     | `download`, `stream`, or `hls`                      |
| `EMBY_PLAYER`                     | External player command or path                     |
| `EMBY_ITEM_ID`                    | Default `--id` for item download / play             |
| `EMBY_CACHE_DIR`                  | Credentials directory (default `~/.cache/emby-cli`) |
| `EMBY_NO_AUTH_CACHE`              | `1` = disable session cache                         |
| `EMBY_DATA_CACHE_TTL`             | Data-cache TTL in seconds (default `600`)           |


---



## Tips

- Prefer **search → show → download** when you are unsure of the exact title.
- Prefer **IDs** (`--id`) when you already have them — no ambiguity.
- Use `--dry-run` before a large library or file-list download.
- Content totals in `info` can count multiple versions of the same title separately.

---



## For contributors

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q
ruff check .
python -m build && twine check dist/*
```

Architecture, CLI contracts, testing rules, and release process: see **[AGENTS.md](AGENTS.md)** (for humans and AI agents). Releases: tag `vX.Y.Z` and push — CI publishes to PyPI only (no GitHub Releases).

---



## Responsible use

This tool talks to Emby over its normal HTTP API. Whether download or playback is allowed depends on **how that server is configured** and on **the terms set by whoever runs it**.

Use `emby-cli` only on servers you are authorized to access, and only in ways that comply with that server’s terms of use, policies, and applicable law. The authors provide the software as-is and are **not responsible** for misuse, for downloads from servers that disallow them, or for any consequences of using the tool.

---



## License

[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) — free for non-commercial use.