gukebox 0.9.0__tar.gz → 1.0.0.dev2__tar.gz

{gukebox-0.9.0 → gukebox-1.0.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: gukebox
-Version: 0.9.0
+Version: 1.0.0.dev2
 Summary: A Jukebox to play music on speakers using 'CD' with NFC tag
 Keywords: jukebox,discstore,music,nfc
 Author: Gudsfile
@@ -36,6 +36,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: pydantic==2.12.5
 Requires-Dist: soco==0.30.14
+Requires-Dist: typer==0.23.2 ; python_full_version < '3.10'
+Requires-Dist: typer==0.24.1 ; python_full_version >= '3.10'
 Requires-Dist: fastapi==0.128.7 ; python_full_version < '3.10' and extra == 'api'
 Requires-Dist: fastapi==0.135.1 ; python_full_version >= '3.10' and extra == 'api'
 Requires-Dist: uvicorn==0.39.0 ; python_full_version < '3.10' and extra == 'api'
@@ -146,7 +148,7 @@ pip install "gukebox[nfc]"
 - For non-system Python 3.13+, you can still install via pip/uv/poetry/etc. but you must build the `lgpio` package from source and it may require other system packages.
 - All releases can be downloaded and installed from the [GitHub releases page](https://github.com/Gudsfile/jukebox/releases).
 
-### Developer setup
+### Installation for development
 
 For development read the [Developer setup](#developer-setup) section.
 
@@ -158,9 +160,7 @@ uv sync
 
 ## First steps
 
-Set the `JUKEBOX_SONOS_HOST` environment variable with the IP address of your Sonos Zone Player (see [Available players and readers](#players)).
-
-Initialize the library file with `discstore` or manually create it at `~/.jukebox/library.json`.
+Initialize the library file with `discstore` or manually create it at `~/.config/jukebox/library.json`.
 
 ### Manage the library with the discstore
 
@@ -176,6 +176,16 @@ discstore add --from-current --uri /path/to/media.mp3
 
 Other commands are available, use `--help` to see them.
 
+### Admin CLI
+
+Use `jukebox-admin` for admin workflows such as settings inspection and the
+admin API/UI servers.
+
+```shell
+jukebox-admin settings show
+jukebox-admin settings show --effective
+```
+
 To use the `api` and `ui` commands, additional packages are required. You can install the `package[extra]` syntax regardless of the package manager you use, for example:
 
 ```shell
@@ -189,13 +199,15 @@ uv tool install gukebox[ui]
 When running from this repository with `uv`, include the extra on the command as well:
 
 ```shell
-uv run --extra api discstore api
-uv run --extra ui discstore ui
+uv run --extra api jukebox-admin api
+uv run --extra ui jukebox-admin ui
 ```
 
+`discstore settings ...`, `discstore api`, and `discstore ui` remain available as compatibility commands, but `jukebox-admin` is the preferred CLI for admin flows.
+
 ### Manage the library manually
 
-Complete your `~/.jukebox/library.json` file with each tag id and the expected media URI.
+Complete your `~/.config/jukebox/library.json` file with each tag id and the expected media URI.
 Take a look at `library.example.json` and the [The library file](#the-library-file) section for more information.
 
 ## Usage
@@ -213,7 +225,7 @@ Optional Parameters
 | Parameter | Description |
 | --- | --- |
 | `--help` | Show help message. |
-| `--library` | Path to the library file, default: `~/.jukebox/library.json`. |
+| `--library` | Path to the library file, default: `~/.config/jukebox/library.json`. |
 | `--pause-delay SECONDS` | Grace period before pausing when the NFC tag is removed. Fractional values such as `0.5` or `0.2` are supported, with a minimum of `0.2` seconds to avoid pausing on brief missed reads. Default: 0.25 seconds. |
 | `--pause-duration SECONDS` | Maximum duration of a pause before resetting the queue. Default: 900 seconds (15 minutes). |
 | `--verbose` | Enable verbose logging. |
@@ -242,9 +254,13 @@ Displays the events that a real speaker would have performed (`playing …`, `pa
 
 **Sonos** (`sonos`) [![SoCo](https://img.shields.io/badge/based%20on-SoCo-000)](https://github.com/SoCo/SoCo)
 Play music through a Sonos speaker.
-`JUKEBOX_SONOS_HOST` environment variable must be set with the IP address of your Sonos Zone Player.
-You could set the environment varible with `export JUKEBOX_SONOS_HOST=192.168.0.???` to use this speaker through the `jukebox` command.
-Or set it in a `.env` file to use the `uv run --env-file .env <command to run>` version.
+Three ways to select the speaker (mutually exclusive):
+
+| Option | CLI flag | Environment variable | Behaviour |
+| --- | --- | --- | --- |
+| By IP | `--sonos-host 192.168.0.x` | `JUKEBOX_SONOS_HOST` | Connect directly, no discovery |
+| By name | `--sonos-name "Living Room"` | `JUKEBOX_SONOS_NAME` | Discover, then filter by name (case-sensitive) |
+| Auto | *(omit both)* | *(omit both)* | Discover, pick the first speaker alphabetically |
 
 ## The library file
 
@@ -252,7 +268,7 @@ The `library.json` file is a JSON file that contains the artists, albums and tag
 It is used by the `jukebox` command to find the corresponding metadata for each tag.
 And the `discstore` command help you to managed this file with a CLI, an interactive CLI, an API or an UI (see `discstore --help`).
 
-By default, this file should be placed at `~/.jukebox/library.json`. But you can use another path by creating a `JUKEBOX_LIBRARY_PATH` environment variable or with the `--library` argument.
+By default, this file should be placed at `~/.config/jukebox/library.json`. But you can use another path by creating a `JUKEBOX_LIBRARY_PATH` environment variable or with the `--library` argument.
 
 ```json
 {
@@ -291,7 +307,7 @@ It is also possible to use the `shuffle` key to play the album in shuffle mode:
     }
 ```
 
-To summarize, for example, if you have the following `~/.jukebox/library.json` file:
+To summarize, for example, if you have the following `~/.config/jukebox/library.json` file:
 
 ```json
 {
@@ -324,7 +340,8 @@ uv sync
 
 Add `--all-extras` to install dependencies for all extras (`api` and `ui`).
 
-Set the `JUKEBOX_SONOS_HOST` environment variable with the IP address of your Sonos Zone Player (see [Available players and readers](#players)).
+If needed, set `JUKEBOX_SONOS_HOST` (IP) or `JUKEBOX_SONOS_NAME` (speaker name) to select your Sonos speaker (see [Players](#players)).
+If neither is set, the jukebox will auto-discover a speaker on the network.
 To do this you can use a `.env` file and `uv run --env-file .env <command to run>`.
 A `.env.example` file is available, you can copy it and modify it to use it.
 
@@ -344,9 +361,23 @@ Start the discstore `uv` and use `--help` to show help message
 uv run discstore --help
 ```
 
-For the server-backed commands, include the matching extra:
+Use `jukebox-admin` for admin commands:
 
 ```shell
+uv run jukebox-admin settings show
+```
+
+For the server-backed admin commands, include the matching extra:
+
+```shell
+uv run --extra api jukebox-admin api
+uv run --extra ui jukebox-admin ui
+```
+
+Legacy compatibility commands remain available during the transition:
+
+```shell
+uv run discstore settings show
 uv run --extra api discstore api
 uv run --extra ui discstore ui
 ```
@@ -360,6 +391,15 @@ Other commands are available:
 | `uv run ruff check --fix` | Fix the code. |
 | `uv run pytest` | Run the tests. |
 
+### Pre-commit
+
+[prek](https://github.com/j178/prek) is configured; you can [install it](https://github.com/j178/prek?tab=readme-ov-file#installation) to automatically run validations on each commit.
+
+```shell
+uv tool install prek
+prek install
+```
+
 ## Contributing
 
 Contributions are welcome! Feel free to open an issue or a pull request.

{gukebox-0.9.0 → gukebox-1.0.0.dev2}/README.md

@@ -91,7 +91,7 @@ pip install "gukebox[nfc]"
 - For non-system Python 3.13+, you can still install via pip/uv/poetry/etc. but you must build the `lgpio` package from source and it may require other system packages.
 - All releases can be downloaded and installed from the [GitHub releases page](https://github.com/Gudsfile/jukebox/releases).
 
-### Developer setup
+### Installation for development
 
 For development read the [Developer setup](#developer-setup) section.
 
@@ -103,9 +103,7 @@ uv sync
 
 ## First steps
 
-Set the `JUKEBOX_SONOS_HOST` environment variable with the IP address of your Sonos Zone Player (see [Available players and readers](#players)).
-
-Initialize the library file with `discstore` or manually create it at `~/.jukebox/library.json`.
+Initialize the library file with `discstore` or manually create it at `~/.config/jukebox/library.json`.
 
 ### Manage the library with the discstore
 
@@ -121,6 +119,16 @@ discstore add --from-current --uri /path/to/media.mp3
 
 Other commands are available, use `--help` to see them.
 
+### Admin CLI
+
+Use `jukebox-admin` for admin workflows such as settings inspection and the
+admin API/UI servers.
+
+```shell
+jukebox-admin settings show
+jukebox-admin settings show --effective
+```
+
 To use the `api` and `ui` commands, additional packages are required. You can install the `package[extra]` syntax regardless of the package manager you use, for example:
 
 ```shell
@@ -134,13 +142,15 @@ uv tool install gukebox[ui]
 When running from this repository with `uv`, include the extra on the command as well:
 
 ```shell
-uv run --extra api discstore api
-uv run --extra ui discstore ui
+uv run --extra api jukebox-admin api
+uv run --extra ui jukebox-admin ui
 ```
 
+`discstore settings ...`, `discstore api`, and `discstore ui` remain available as compatibility commands, but `jukebox-admin` is the preferred CLI for admin flows.
+
 ### Manage the library manually
 
-Complete your `~/.jukebox/library.json` file with each tag id and the expected media URI.
+Complete your `~/.config/jukebox/library.json` file with each tag id and the expected media URI.
 Take a look at `library.example.json` and the [The library file](#the-library-file) section for more information.
 
 ## Usage
@@ -158,7 +168,7 @@ Optional Parameters
 | Parameter | Description |
 | --- | --- |
 | `--help` | Show help message. |
-| `--library` | Path to the library file, default: `~/.jukebox/library.json`. |
+| `--library` | Path to the library file, default: `~/.config/jukebox/library.json`. |
 | `--pause-delay SECONDS` | Grace period before pausing when the NFC tag is removed. Fractional values such as `0.5` or `0.2` are supported, with a minimum of `0.2` seconds to avoid pausing on brief missed reads. Default: 0.25 seconds. |
 | `--pause-duration SECONDS` | Maximum duration of a pause before resetting the queue. Default: 900 seconds (15 minutes). |
 | `--verbose` | Enable verbose logging. |
@@ -187,9 +197,13 @@ Displays the events that a real speaker would have performed (`playing …`, `pa
 
 **Sonos** (`sonos`) [![SoCo](https://img.shields.io/badge/based%20on-SoCo-000)](https://github.com/SoCo/SoCo)
 Play music through a Sonos speaker.
-`JUKEBOX_SONOS_HOST` environment variable must be set with the IP address of your Sonos Zone Player.
-You could set the environment varible with `export JUKEBOX_SONOS_HOST=192.168.0.???` to use this speaker through the `jukebox` command.
-Or set it in a `.env` file to use the `uv run --env-file .env <command to run>` version.
+Three ways to select the speaker (mutually exclusive):
+
+| Option | CLI flag | Environment variable | Behaviour |
+| --- | --- | --- | --- |
+| By IP | `--sonos-host 192.168.0.x` | `JUKEBOX_SONOS_HOST` | Connect directly, no discovery |
+| By name | `--sonos-name "Living Room"` | `JUKEBOX_SONOS_NAME` | Discover, then filter by name (case-sensitive) |
+| Auto | *(omit both)* | *(omit both)* | Discover, pick the first speaker alphabetically |
 
 ## The library file
 
@@ -197,7 +211,7 @@ The `library.json` file is a JSON file that contains the artists, albums and tag
 It is used by the `jukebox` command to find the corresponding metadata for each tag.
 And the `discstore` command help you to managed this file with a CLI, an interactive CLI, an API or an UI (see `discstore --help`).
 
-By default, this file should be placed at `~/.jukebox/library.json`. But you can use another path by creating a `JUKEBOX_LIBRARY_PATH` environment variable or with the `--library` argument.
+By default, this file should be placed at `~/.config/jukebox/library.json`. But you can use another path by creating a `JUKEBOX_LIBRARY_PATH` environment variable or with the `--library` argument.
 
 ```json
 {
@@ -236,7 +250,7 @@ It is also possible to use the `shuffle` key to play the album in shuffle mode:
     }
 ```
 
-To summarize, for example, if you have the following `~/.jukebox/library.json` file:
+To summarize, for example, if you have the following `~/.config/jukebox/library.json` file:
 
 ```json
 {
@@ -269,7 +283,8 @@ uv sync
 
 Add `--all-extras` to install dependencies for all extras (`api` and `ui`).
 
-Set the `JUKEBOX_SONOS_HOST` environment variable with the IP address of your Sonos Zone Player (see [Available players and readers](#players)).
+If needed, set `JUKEBOX_SONOS_HOST` (IP) or `JUKEBOX_SONOS_NAME` (speaker name) to select your Sonos speaker (see [Players](#players)).
+If neither is set, the jukebox will auto-discover a speaker on the network.
 To do this you can use a `.env` file and `uv run --env-file .env <command to run>`.
 A `.env.example` file is available, you can copy it and modify it to use it.
 
@@ -289,9 +304,23 @@ Start the discstore `uv` and use `--help` to show help message
 uv run discstore --help
 ```
 
-For the server-backed commands, include the matching extra:
+Use `jukebox-admin` for admin commands:
 
 ```shell
+uv run jukebox-admin settings show
+```
+
+For the server-backed admin commands, include the matching extra:
+
+```shell
+uv run --extra api jukebox-admin api
+uv run --extra ui jukebox-admin ui
+```
+
+Legacy compatibility commands remain available during the transition:
+
+```shell
+uv run discstore settings show
 uv run --extra api discstore api
 uv run --extra ui discstore ui
 ```
@@ -305,6 +334,15 @@ Other commands are available:
 | `uv run ruff check --fix` | Fix the code. |
 | `uv run pytest` | Run the tests. |
 
+### Pre-commit
+
+[prek](https://github.com/j178/prek) is configured; you can [install it](https://github.com/j178/prek?tab=readme-ov-file#installation) to automatically run validations on each commit.
+
+```shell
+uv tool install prek
+prek install
+```
+
 ## Contributing
 
 Contributions are welcome! Feel free to open an issue or a pull request.

{gukebox-0.9.0 → gukebox-1.0.0.dev2}/discstore/adapters/inbound/api_controller.py

@@ -1,4 +1,6 @@
-from typing import Dict
+from typing import Any, Dict, cast
+
+from pydantic import BaseModel, RootModel
 
 from jukebox.shared.dependency_messages import optional_extra_dependency_message
 
@@ -15,6 +17,9 @@ from discstore.domain.use_cases.edit_disc import EditDisc
 from discstore.domain.use_cases.get_current_tag_status import GetCurrentTagStatus
 from discstore.domain.use_cases.list_discs import ListDiscs
 from discstore.domain.use_cases.remove_disc import RemoveDisc
+from jukebox.settings.errors import SettingsError
+from jukebox.settings.service_protocols import SettingsService
+from jukebox.settings.types import JsonObject
 
 
 class DiscInput(Disc):
@@ -29,6 +34,14 @@ class CurrentTagStatusOutput(CurrentTagStatus):
     pass
 
 
+class SettingsResetInput(BaseModel):
+    path: str
+
+
+class SettingsPatchInput(RootModel[Dict[str, Any]]):
+    pass
+
+
 class APIController:
     def __init__(
         self,
@@ -37,12 +50,14 @@ class APIController:
         remove_disc: RemoveDisc,
         edit_disc: EditDisc,
         get_current_tag_status: GetCurrentTagStatus,
+        settings_service: SettingsService,
     ):
         self.add_disc = add_disc
         self.list_discs = list_discs
         self.remove_disc = remove_disc
         self.edit_disc = edit_disc
         self.get_current_tag_status = get_current_tag_status
+        self.settings_service = settings_service
         self.app = FastAPI(
             title="DiscStore API",
             description="API for managing Jukebox disc library",
@@ -68,6 +83,38 @@ class APIController:
 
             return CurrentTagStatusOutput(**current_tag_status.model_dump())
 
+        @self.app.get("/api/v1/settings")
+        def get_settings():
+            try:
+                return self.settings_service.get_persisted_settings_view()
+            except Exception as err:
+                raise HTTPException(status_code=500, detail=f"Server error: {str(err)}")
+
+        @self.app.get("/api/v1/settings/effective")
+        def get_effective_settings():
+            try:
+                return self.settings_service.get_effective_settings_view()
+            except Exception as err:
+                raise HTTPException(status_code=500, detail=f"Server error: {str(err)}")
+
+        @self.app.patch("/api/v1/settings")
+        def patch_settings(patch: SettingsPatchInput):
+            try:
+                return self.settings_service.patch_persisted_settings(cast(JsonObject, patch.root))
+            except SettingsError as err:
+                raise HTTPException(status_code=400, detail=str(err))
+            except Exception as err:
+                raise HTTPException(status_code=500, detail=f"Server error: {str(err)}")
+
+        @self.app.post("/api/v1/settings/reset")
+        def reset_settings(payload: SettingsResetInput):
+            try:
+                return self.settings_service.reset_persisted_value(payload.path)
+            except SettingsError as err:
+                raise HTTPException(status_code=400, detail=str(err))
+            except Exception as err:
+                raise HTTPException(status_code=500, detail=f"Server error: {str(err)}")
+
         @self.app.post("/api/v1/disc", status_code=201)
         def add_or_edit_disc(tag_id: str, disc: DiscInput):
             try:
@@ -85,7 +132,7 @@ class APIController:
             try:
                 self.remove_disc.execute(tag_id)
                 return {"message": "Disc removed"}
-            except ValueError as valueErr:
-                raise HTTPException(status_code=404, detail=str(valueErr))
+            except ValueError as value_err:
+                raise HTTPException(status_code=404, detail=str(value_err))
             except Exception as err:
                 raise HTTPException(status_code=500, detail=f"Server error: {str(err)}")

{gukebox-0.9.0 → gukebox-1.0.0.dev2}/discstore/adapters/inbound/cli_controller.py

@@ -2,7 +2,7 @@ import logging
 from typing import Union
 
 from discstore.adapters.inbound.cli_display import display_library_line, display_library_table
-from discstore.adapters.inbound.config import (
+from discstore.commands import (
     CliAddCommand,
     CliEditCommand,
     CliGetCommand,

gukebox-1.0.0.dev2/discstore/adapters/inbound/config.py

@@ -0,0 +1,250 @@
+import argparse
+import logging
+import sys
+from typing import Optional, Union
+
+from pydantic import BaseModel, ValidationError
+
+from discstore.commands import (
+    CliAddCommand,
+    CliEditCommand,
+    CliGetCommand,
+    CliListCommand,
+    CliListCommandModes,
+    CliRemoveCommand,
+    CliSearchCommand,
+    InteractiveCliCommand,
+)
+from jukebox.admin.commands import ApiCommand, SettingsResetCommand, SettingsSetCommand, SettingsShowCommand, UiCommand
+from jukebox.shared.config_utils import add_verbose_arg, add_version_arg
+
+LOGGER = logging.getLogger("discstore")
+
+__all__ = [
+    "ApiCommand",
+    "CliAddCommand",
+    "CliEditCommand",
+    "CliGetCommand",
+    "CliListCommand",
+    "CliListCommandModes",
+    "CliRemoveCommand",
+    "CliSearchCommand",
+    "DiscStoreConfig",
+    "InteractiveCliCommand",
+    "SettingsResetCommand",
+    "SettingsSetCommand",
+    "SettingsShowCommand",
+    "UiCommand",
+    "add_from_current_arg",
+    "parse_config",
+]
+
+
+class DiscStoreConfig(BaseModel):
+    library: Optional[str] = None
+    verbose: bool = False
+
+    command: Union[
+        ApiCommand,
+        InteractiveCliCommand,
+        CliAddCommand,
+        CliListCommand,
+        CliRemoveCommand,
+        CliEditCommand,
+        CliGetCommand,
+        CliSearchCommand,
+        SettingsResetCommand,
+        SettingsSetCommand,
+        SettingsShowCommand,
+        UiCommand,
+    ]
+
+
+def add_from_current_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--from-current",
+        dest="use_current_tag",
+        action="store_true",
+        help="Resolve the tag ID from shared current-tag.txt state",
+    )
+
+
+def _build_library_command(command_name: str, args: argparse.Namespace):
+    if command_name == "add":
+        return CliAddCommand(
+            type="add",
+            tag=args.tag,
+            use_current_tag=args.use_current_tag,
+            uri=args.uri,
+            track=args.track,
+            artist=args.artist,
+            album=args.album,
+        )
+    if command_name == "list":
+        if args.positional_mode is not None:
+            print(
+                "warning: positional mode argument is deprecated; use --mode instead",
+                file=sys.stderr,
+            )
+        # if args.positional_mode is not None and args.mode is not None:
+        #    raise ValueError("You must provide exactly one of: mode OR --mode argument")
+        return CliListCommand(type="list", mode=args.positional_mode if args.positional_mode else args.mode)
+    if command_name == "remove":
+        return CliRemoveCommand(type="remove", tag=args.tag, use_current_tag=args.use_current_tag)
+    if command_name == "edit":
+        return CliEditCommand(
+            type="edit",
+            tag=args.tag,
+            use_current_tag=args.use_current_tag,
+            uri=args.uri,
+            track=args.track,
+            artist=args.artist,
+            album=args.album,
+        )
+    if command_name == "get":
+        return CliGetCommand(type="get", tag=args.tag, use_current_tag=args.use_current_tag)
+    if command_name == "search":
+        return CliSearchCommand(type="search", query=args.query)
+    if command_name == "interactive":
+        return InteractiveCliCommand(type="interactive")
+    raise ValueError(f"Unsupported command: {command_name}")
+
+
+def _build_admin_command(args: argparse.Namespace):
+    if args.command == "api":
+        return ApiCommand(type="api", port=args.port)
+    if args.command == "ui":
+        return UiCommand(type="ui", port=args.port)
+    if args.command != "settings":
+        raise ValueError(f"Unsupported admin command: {args.command}")
+
+    if args.settings_command == "show":
+        return SettingsShowCommand(type="settings_show", effective=args.effective, json_output=args.json_output)
+    if args.settings_command == "set":
+        return SettingsSetCommand(
+            type="settings_set",
+            dotted_path=args.dotted_path,
+            value=args.value,
+            json_output=args.json_output,
+        )
+    if args.settings_command == "reset":
+        return SettingsResetCommand(
+            type="settings_reset",
+            dotted_path=args.dotted_path,
+            json_output=args.json_output,
+        )
+    raise ValueError(f"Unsupported settings command: {args.settings_command}")
+
+
+def parse_config() -> DiscStoreConfig:
+    parser = argparse.ArgumentParser(
+        prog="discstore",
+        description="Manage your disc collection for jukebox",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    parser.add_argument(
+        "-l",
+        "--library",
+        default=None,
+        help="override the library JSON path for this process",
+    )
+    add_verbose_arg(parser)
+    add_version_arg(parser)
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # CLI commands
+    add_parser = subparsers.add_parser("add", help="Add a disc")
+    add_from_current_arg(add_parser)
+    add_parser.add_argument("tag", nargs="?", help="Tag to be associated with the disc")
+    add_parser.add_argument("--uri", required=True, help="Path or URI of the media file")
+    add_parser.add_argument("--track", required=False, help="Name of the track")
+    add_parser.add_argument("--artist", required=False, help="Name of the artist or band")
+    add_parser.add_argument("--album", required=False, help="Name of the album")
+    add_parser.add_argument("--opts", required=False, help="Playback options for the discs")
+
+    list_parser = subparsers.add_parser("list", help="List all discs")
+    list_parser.add_argument("positional_mode", nargs="?", choices=["line", "table"], help=argparse.SUPPRESS)
+    list_parser.add_argument(
+        "--mode", choices=["line", "table"], default="table", help="Displaying mode (default: table)"
+    )
+
+    remove_parser = subparsers.add_parser("remove", help="Remove a disc")
+    add_from_current_arg(remove_parser)
+    remove_parser.add_argument("tag", nargs="?", help="Tag to remove")
+
+    edit_parser = subparsers.add_parser("edit", help="Edit a disc (partial updates supported)")
+    add_from_current_arg(edit_parser)
+    edit_parser.add_argument("tag", nargs="?", help="Tag to be edited")
+    edit_parser.add_argument("--uri", required=False, help="Path or URI of the media file")
+    edit_parser.add_argument("--track", required=False, help="Name of the track")
+    edit_parser.add_argument("--artist", required=False, help="Name of the artist or band")
+    edit_parser.add_argument("--album", required=False, help="Name of the album")
+    edit_parser.add_argument("--opts", required=False, help="Playback options for the discs")
+
+    get_parser = subparsers.add_parser("get", help="Get a disc by tag ID")
+    add_from_current_arg(get_parser)
+    get_parser.add_argument("tag", nargs="?", help="Tag to retrieve")
+
+    search_parser = subparsers.add_parser("search", help="Search discs by query")
+    search_parser.add_argument("query", help="Search query (matches artist, album, track, playlist, or tag)")
+
+    # API commands
+    api_parser = subparsers.add_parser("api", help="Start an API server")
+    api_parser.add_argument("--port", type=int, default=None, help="override the configured API port")
+
+    # UI commands
+    ui_parser = subparsers.add_parser("ui", help="Start an UI server")
+    ui_parser.add_argument("--port", type=int, default=None, help="override the configured UI port")
+
+    # Interactive commands
+    _ = subparsers.add_parser("interactive", help="Run interactive CLI")
+
+    settings_parser = subparsers.add_parser("settings", help="Inspect application settings")
+    settings_subparsers = settings_parser.add_subparsers(dest="settings_command", required=True)
+    settings_show_parser = settings_subparsers.add_parser("show", help="Show persisted settings")
+    settings_show_parser.add_argument(
+        "--effective",
+        action="store_true",
+        help="show merged effective settings with provenance",
+    )
+    settings_show_parser.add_argument(
+        "--json",
+        dest="json_output",
+        action="store_true",
+        help="print the raw machine-readable payload",
+    )
+    settings_set_parser = settings_subparsers.add_parser("set", help="Set a persisted setting override")
+    settings_set_parser.add_argument("dotted_path", help="canonical dotted path to update")
+    settings_set_parser.add_argument("value", help="value to persist for the given path")
+    settings_set_parser.add_argument(
+        "--json",
+        dest="json_output",
+        action="store_true",
+        help="print the raw machine-readable payload",
+    )
+    settings_reset_parser = settings_subparsers.add_parser("reset", help="Remove a persisted setting override")
+    settings_reset_parser.add_argument("dotted_path", help="canonical dotted path to reset")
+    settings_reset_parser.add_argument(
+        "--json",
+        dest="json_output",
+        action="store_true",
+        help="print the raw machine-readable payload",
+    )
+
+    args = parser.parse_args()
+
+    # Build command config
+    try:
+        command = (
+            _build_admin_command(args)
+            if args.command in {"api", "ui", "settings"}
+            else _build_library_command(args.command, args)
+        )
+        config = DiscStoreConfig(library=args.library, verbose=args.verbose, command=command)
+    except (ValidationError, ValueError) as err:
+        LOGGER.error("Config error: %s", err)
+        exit(1)
+
+    return config