emby-cli 0.3.0__tar.gz → 0.4.1__tar.gz

{emby_cli-0.3.0 → emby_cli-0.4.1}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.4.1
+
+- README rewritten for end users (quick start, everyday workflows, responsible-use disclaimer).
+
+## 0.4.0
+
+Added:
+
+- `show`: detail view for `--item` / `--library` (QUERY or `--id`); multiple matches print a disambiguation table with IDs. Libraries include total item count and the last 10 added (`DateCreated`), limited to Movie/Episode/Audio (no Studio, etc.).
+- `search` / `download`: `--item QUERY` / `--library QUERY` (query on the mode flag); `--media-item` is an alias of `--item`. `--search` still works as an alternative selector.
+
 ## 0.3.0
 
 Breaking:

emby_cli-0.4.1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: emby-cli
+Version: 0.4.1
+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: 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 download:**
+
+```bash
+emby-cli search --item "matrix"
+emby-cli download --item "matrix" --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 50
+emby-cli search --item --id 123456
+emby-cli search --library "peliculas"
+emby-cli search --library --all
+```
+
+`--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 (counts, metadata, recently added):
+
+```bash
+emby-cli show --item "matrix"
+emby-cli show --item --id 123456
+emby-cli show --library "peliculas"
+```
+
+If several titles match, `show` lists them with IDs so you can pick one:
+
+```bash
+emby-cli show --item --id 123456
+```
+
+### Play
+
+Open a title in an external player (VLC, mpv, IINA, …):
+
+```bash
+emby-cli play --search "Pelicula (1980)" --pick-best-item
+emby-cli play --id 123456
+emby-cli play --id 123456 --player vlc --wait
+```
+
+Set `EMBY_PLAYER` if the player is not found automatically.
+
+### 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 "californication S01E01" --pick-best-item
+emby-cli download --library "PELICULAS 4K"
+emby-cli download --from-file titles.txt
+```
+
+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 download\|stream\|hls` | How to fetch the file (see below) |
+
+**Title lines** in `--item` / `--from-file` can look like:
+
+- `Movie (2010)`
+- `Show S01E05`
+- `Show S01` — whole season (with `--item` or `--from-file`)
+
+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).
+
+---
+
+## 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 |
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## For contributors
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -q
+python -m build && twine check dist/*
+```
+
+Releases: tag `vX.Y.Z` and push (or create a GitHub Release). CI publishes to PyPI via Trusted Publisher.
+
+## License
+
+[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) — free for non-commercial use.

emby_cli-0.4.1/README.md

@@ -0,0 +1,208 @@
+# 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 download:**
+
+```bash
+emby-cli search --item "matrix"
+emby-cli download --item "matrix" --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 50
+emby-cli search --item --id 123456
+emby-cli search --library "peliculas"
+emby-cli search --library --all
+```
+
+`--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 (counts, metadata, recently added):
+
+```bash
+emby-cli show --item "matrix"
+emby-cli show --item --id 123456
+emby-cli show --library "peliculas"
+```
+
+If several titles match, `show` lists them with IDs so you can pick one:
+
+```bash
+emby-cli show --item --id 123456
+```
+
+### Play
+
+Open a title in an external player (VLC, mpv, IINA, …):
+
+```bash
+emby-cli play --search "Pelicula (1980)" --pick-best-item
+emby-cli play --id 123456
+emby-cli play --id 123456 --player vlc --wait
+```
+
+Set `EMBY_PLAYER` if the player is not found automatically.
+
+### 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 "californication S01E01" --pick-best-item
+emby-cli download --library "PELICULAS 4K"
+emby-cli download --from-file titles.txt
+```
+
+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 download\|stream\|hls` | How to fetch the file (see below) |
+
+**Title lines** in `--item` / `--from-file` can look like:
+
+- `Movie (2010)`
+- `Show S01E05`
+- `Show S01` — whole season (with `--item` or `--from-file`)
+
+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).
+
+---
+
+## 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 |
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+---
+
+## For contributors
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest -q
+python -m build && twine check dist/*
+```
+
+Releases: tag `vX.Y.Z` and push (or create a GitHub Release). CI publishes to PyPI via Trusted Publisher.
+
+## License
+
+[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) — free for non-commercial use.

{emby_cli-0.3.0 → emby_cli-0.4.1}/src/emby_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.4.1'
+__version_tuple__ = version_tuple = (0, 4, 1)
 
 __commit_id__ = commit_id = None

{emby_cli-0.3.0 → emby_cli-0.4.1}/src/emby_cli/cli.py

@@ -21,6 +21,7 @@ from emby_cli.commands.login import cmd_login
 from emby_cli.commands.logout import cmd_logout
 from emby_cli.commands.play import cmd_play, validate_play_args
 from emby_cli.commands.search import cmd_search, validate_search_args
+from emby_cli.commands.show import cmd_show, validate_show_args
 from emby_cli.commands.version import cmd_version
 from emby_cli.constants import DEFAULT_OUTPUT, SEARCH_COUNT_DEFAULT
 from emby_cli.credentials import (
@@ -82,14 +83,23 @@ def build_parser() -> argparse.ArgumentParser:
     )
     mode = dl.add_mutually_exclusive_group(required=True)
     mode.add_argument(
+        "--item",
         "--media-item",
-        action="store_true",
-        help="Download media items; use with --id or --search",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="QUERY",
+        dest="item",
+        help="Download media items; optional QUERY, or use with --id "
+             "(--media-item is an alias)",
     )
     mode.add_argument(
         "--library",
-        action="store_true",
-        help="Download a library; use with --id or --search",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="QUERY",
+        help="Download a library; optional QUERY, or use with --id",
     )
     mode.add_argument(
         "--from-file",
@@ -105,7 +115,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     dl.add_argument(
         "--search",
-        help="Search query for media item or library",
+        help="Search query (alternative to QUERY on --item / --library)",
     )
     dl.add_argument(
         "--dry-run",
@@ -146,14 +156,23 @@ def build_parser() -> argparse.ArgumentParser:
     sr = sub.add_parser("search", help=_help_by_name["search"])
     sr_mode = sr.add_mutually_exclusive_group(required=True)
     sr_mode.add_argument(
+        "--item",
         "--media-item",
-        action="store_true",
-        help="Search media items; use with --id, --search, or --all",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="QUERY",
+        dest="item",
+        help="Search media items; optional QUERY, or use with --id / --all "
+             "(--media-item is an alias)",
     )
     sr_mode.add_argument(
         "--library",
-        action="store_true",
-        help="Search libraries; use with --id, --search, or --all",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="QUERY",
+        help="Search libraries; optional QUERY, or use with --id / --all",
     )
     sr.add_argument(
         "--id",
@@ -162,7 +181,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     sr.add_argument(
         "--search",
-        help="Search query for media item or library",
+        help="Search query (alternative to QUERY on --item / --library)",
     )
     sr.add_argument(
         "--all",
@@ -206,6 +225,37 @@ def build_parser() -> argparse.ArgumentParser:
              "(default: list matches and fail)",
     )
 
+    sh = sub.add_parser("show", help=_help_by_name["show"])
+    sh_mode = sh.add_mutually_exclusive_group(required=True)
+    sh_mode.add_argument(
+        "--item",
+        "--media-item",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="QUERY",
+        dest="item",
+        help="Show a media item; optional QUERY, or use with --id "
+             "(--media-item is an alias)",
+    )
+    sh_mode.add_argument(
+        "--library",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="QUERY",
+        help="Show a library; optional QUERY, or use with --id",
+    )
+    sh.add_argument(
+        "--id",
+        default=None,
+        help="Media item or library ID",
+    )
+    sh.add_argument(
+        "--search",
+        help="Search query (alternative to QUERY on --item / --library)",
+    )
+
     sub.add_parser("version", help=_help_by_name["version"])
     sub.add_parser("info", help=_help_by_name["info"])
 
@@ -249,6 +299,8 @@ def _validate_command_args(command: str, args: argparse.Namespace) -> str | None
         return validate_download_args(args)
     if command == "play":
         return validate_play_args(args)
+    if command == "show":
+        return validate_show_args(args)
     return None
 
 
@@ -293,6 +345,7 @@ def main() -> None:
         "download": cmd_download,
         "search": cmd_search,
         "play": cmd_play,
+        "show": cmd_show,
     }
     commands[args.command](client, args)
 

{emby_cli-0.3.0 → emby_cli-0.4.1}/src/emby_cli/client.py

@@ -458,15 +458,19 @@ class EmbyClient:
         recursive: bool = True,
         start: int = 0,
         limit: int = 200,
+        *,
+        sort_by: str = "SortName",
+        sort_order: str = "Ascending",
+        fields: str | None = None,
     ) -> dict:
         uid = self.resolve_user_id()
         params: dict = {
             "StartIndex": start,
             "Limit": limit,
             "Recursive": str(recursive).lower(),
-            "Fields": ITEM_FIELDS,
-            "SortBy": "SortName",
-            "SortOrder": "Ascending",
+            "Fields": fields or ITEM_FIELDS,
+            "SortBy": sort_by,
+            "SortOrder": sort_order,
         }
         if parent_id:
             params["ParentId"] = parent_id
@@ -493,11 +497,11 @@ class EmbyClient:
                 break
         return items
 
-    def get_item_info(self, item_id: str) -> dict:
+    def get_item_info(self, item_id: str, *, fields: str | None = None) -> dict:
         uid = self.resolve_user_id()
         resp = self._get(
             f"/Users/{uid}/Items/{item_id}",
-            params={"Fields": ITEM_FIELDS},
+            params={"Fields": fields or ITEM_FIELDS},
         )
         return resp.json()