cave-cli 3.5.4__tar.gz → 3.6.0b1__tar.gz

{cave_cli-3.5.4/cave_cli.egg-info → cave_cli-3.6.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cave_cli
-Version: 3.5.4
+Version: 3.6.0b1
 Summary: CLI for creating and managing Docker-based CAVE web applications.
 Author-email: MIT-CAVE <cave-contact@mit.edu>
 License: Apache-2.0
@@ -13,6 +13,15 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE.md
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == "dev"
+Requires-Dist: autoflake>=2.3.1; extra == "dev"
+Requires-Dist: black>=25.1.0; extra == "dev"
+Requires-Dist: build>=1.4.0; extra == "dev"
+Requires-Dist: nox>=2026.4.10; extra == "dev"
+Requires-Dist: nox-uv>=0.8.0; extra == "dev"
+Requires-Dist: pdoc>=15.0.1; extra == "dev"
+Requires-Dist: twine>=6.2.0; extra == "dev"
 Dynamic: license-file
 
 # CAVE CLI
@@ -56,38 +65,42 @@ docker run hello-world
 
 ## Installation
 
-Install with [pipx](https://pipx.pypa.io/) (recommended — keeps the CLI isolated from your system Python):
+Install with [uv](https://docs.astral.sh/uv/) (required to run cave update and cave uninstall):
 
 ```sh
-pipx install cave_cli
+uv tool install cave_cli
 ```
 
-If you don't have pipx, install it first:
+If you don't have uv, install it first:
 
 <details>
 <summary>macOS</summary>
 
 ```sh
 # With Homebrew (recommended)
-brew install pipx
-pipx ensurepath
+brew install uv
 
-# Or with pip
-pip3 install --user pipx
-pipx ensurepath
+# Or with the official installer
+curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
 </details>
 <details>
-<summary>Other Linux / Windows</summary>
+<summary>Linux</summary>
 
 ```sh
-python3 -m pip install --user pipx
-pipx ensurepath
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+</details>
+<details>
+<summary>Windows</summary>
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 </details>
 
-For more options see the [pipx installation guide](https://pipx.pypa.io/stable/installation/).
+For more options see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
 
 Verify the installation and check your environment health:
 
@@ -116,7 +129,7 @@ cave --help
 |---|---|
 | `cave create <name>` | Create a new CAVE app from the template repository |
 | `cave run` | Build Docker image and run the app with a live TUI dashboard |
-| `cave doctor` | Check the health of your Docker, Git, and Pipx environment |
+| `cave doctor` | Check the health of your Docker, Git, and uv environment |
 
 ### Peripheral Commands
 
@@ -163,10 +176,10 @@ cave --help
 cave update
 ```
 
-Or directly via pipx:
+Or directly via uv:
 
 ```sh
-pipx upgrade cave_cli
+uv tool upgrade cave_cli
 ```
 
 ## License Notice

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/README.md

@@ -39,38 +39,42 @@ docker run hello-world
 
 ## Installation
 
-Install with [pipx](https://pipx.pypa.io/) (recommended — keeps the CLI isolated from your system Python):
+Install with [uv](https://docs.astral.sh/uv/) (required to run cave update and cave uninstall):
 
 ```sh
-pipx install cave_cli
+uv tool install cave_cli
 ```
 
-If you don't have pipx, install it first:
+If you don't have uv, install it first:
 
 <details>
 <summary>macOS</summary>
 
 ```sh
 # With Homebrew (recommended)
-brew install pipx
-pipx ensurepath
+brew install uv
 
-# Or with pip
-pip3 install --user pipx
-pipx ensurepath
+# Or with the official installer
+curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
 </details>
 <details>
-<summary>Other Linux / Windows</summary>
+<summary>Linux</summary>
 
 ```sh
-python3 -m pip install --user pipx
-pipx ensurepath
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+</details>
+<details>
+<summary>Windows</summary>
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 </details>
 
-For more options see the [pipx installation guide](https://pipx.pypa.io/stable/installation/).
+For more options see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
 
 Verify the installation and check your environment health:
 
@@ -99,7 +103,7 @@ cave --help
 |---|---|
 | `cave create <name>` | Create a new CAVE app from the template repository |
 | `cave run` | Build Docker image and run the app with a live TUI dashboard |
-| `cave doctor` | Check the health of your Docker, Git, and Pipx environment |
+| `cave doctor` | Check the health of your Docker, Git, and uv environment |
 
 ### Peripheral Commands
 
@@ -146,10 +150,10 @@ cave --help
 cave update
 ```
 
-Or directly via pipx:
+Or directly via uv:
 
 ```sh
-pipx upgrade cave_cli
+uv tool upgrade cave_cli
 ```
 
 ## License Notice

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/cave_cli/cli.py

@@ -38,6 +38,13 @@ def add_global_args(parser: argparse.ArgumentParser) -> None:
         default=False,
         help="Enable verbose logging output (shorthand for --loglevel DEBUG)",
     )
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        default=False,
+        help="Enable quiet mode (suppress most output, shorthand for --loglevel SILENT)",
+    )
     parser.add_argument(
         "--loglevel",
         "--ll",
@@ -162,6 +169,12 @@ def main():
         ),
     )
     add_global_args(p_reset)
+    p_reset.add_argument(
+        "--docker-args",
+        default="",
+        metavar="ARGS",
+        help="Additional arguments to pass to docker run",
+    )
 
     # ------------------------------------------------------------------ #
     # upgrade                                                              #
@@ -233,6 +246,12 @@ def main():
         help="Run tests in cave_api/tests/",
     )
     add_global_args(p_test)
+    p_test.add_argument(
+        "--docker-args",
+        default="",
+        metavar="ARGS",
+        help="Additional arguments to pass to docker run",
+    )
     p_test.add_argument(
         "remaining",
         nargs="*",
@@ -247,6 +266,12 @@ def main():
         help="Format code with autoflake and black",
     )
     add_global_args(p_prettify)
+    p_prettify.add_argument(
+        "--docker-args",
+        default="",
+        metavar="ARGS",
+        help="Additional arguments to pass to docker run",
+    )
 
     # ------------------------------------------------------------------ #
     # list                                                                 #
@@ -401,7 +426,9 @@ def main():
     # Configure logging
     from cave_cli.utils.logger import logger
 
-    if args.verbose:
+    if getattr(args, "quiet", False):
+        logger.set_level("SILENT")
+    elif args.verbose:
         logger.set_level("DEBUG")
     else:
         logger.set_level(args.loglevel)

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/cave_cli/commands/doctor.py

@@ -34,31 +34,35 @@ def check_git() -> tuple[bool, str]:
     )
 
 
-def check_pipx() -> tuple[bool, str]:
+def check_uv(return_path: bool = True) -> tuple[bool, str, str | None]:
     """
     Usage:
 
-    - Validates that pipx is installed
+    - Validates that uv is installed
 
     Returns:
 
     - ``success``: bool
     - ``message``: str remediation or version
+    - ``path``: str|None path to uv executable if found
     """
     import shutil
 
-    pipx = shutil.which("pipx")
-    if pipx:
+    uv_path = shutil.which("uv")
+    if uv_path:
         try:
-            result = run([pipx, "--version"])
+            result = run([uv_path, "--version"])
             if result.returncode == 0:
-                return True, f"pipx version {result.stdout.strip()}"
+                output = True, f"uv version {result.stdout.strip()}"
+                if return_path:
+                    return output + (uv_path,)
+                return output
         except Exception:
             pass
-    return (
-        False,
-        "pipx is not installed. Please install pipx: https://pipx.pypa.io/",
-    )
+    output = False, "uv is not installed. Please install uv: https://github.com/astral-sh/uv"
+    if return_path:
+        return output + (None,)
+    return output
 
 
 def check_docker() -> tuple[bool, str]:
@@ -126,7 +130,7 @@ def check_all(exit_on_fail: bool = True) -> dict[str, tuple[bool, str]]:
     results = {
         "Docker": check_docker(),
         "Git": check_git(),
-        "Pipx": check_pipx(),
+        "uv": check_uv(return_path=False),
     }
 
     if exit_on_fail:
@@ -145,7 +149,7 @@ def doctor(args: argparse.Namespace) -> None:
     """
     Usage:
 
-    - Checks the health of the CAVE environment (Docker, Git, Pipx)
+    - Checks the health of the CAVE environment (Docker, Git, uv)
     """
     print_section("CAVE Doctor")
 

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/cave_cli/commands/list_cmd.py

@@ -20,9 +20,11 @@ def list_cmd(args: argparse.Namespace) -> None:
 
     if show_all:
         print_section("CAVE App Containers (All)")
+        from cave_cli.utils.display import _QUIET
         for suffix in ("_django", "_db_host", "_redis_host", "_nginx_host"):
             for name in get_all_containers(suffix):
-                print(f"  ● {name}")
+                if not _QUIET:
+                    print(f"  ● {name}")
     else:
         apps = get_running_apps()
         if not apps:
@@ -40,4 +42,7 @@ def list_cmd(args: argparse.Namespace) -> None:
             else:
                 port = get_container_host_port(f"{app_name}_django")
                 print_key_value(app_name, f"http://localhost:{port}")
-    print("")
+    
+    from cave_cli.utils.display import _QUIET
+    if not _QUIET:
+        print("")

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/cave_cli/commands/list_versions.py

@@ -14,14 +14,11 @@ from cave_cli.utils.display import (
 )
 from cave_cli.utils.git import ls_remote_tags
 from cave_cli.utils.logger import logger
+from cave_cli.utils.version import version_tuple
 
 RECENT_LIMIT = 5
 
 
-def _version_sort_key(v: str) -> list[int]:
-    return [int(x) for x in re.findall(r"\d+", v)]
-
-
 def list_versions(args: argparse.Namespace) -> None:
     """
     Usage:
@@ -54,7 +51,7 @@ def list_versions(args: argparse.Namespace) -> None:
             v for v in set().union(*repo_tags.values())
             if not pattern or fnmatch.fnmatch(v, pattern)
         ),
-        key=_version_sort_key,
+        key=version_tuple,
         reverse=True,
     )
 
@@ -64,7 +61,7 @@ def list_versions(args: argparse.Namespace) -> None:
 
     by_major: dict[int, list[str]] = defaultdict(list)
     for v in all_versions:
-        major = _version_sort_key(v)[0]
+        major = version_tuple(v)[0]
         by_major[major].append(v)
 
     repos = list(VALID_REPOS)

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/cave_cli/commands/prettify.py

@@ -18,7 +18,7 @@ def prettify(args: argparse.Namespace) -> None:
         entrypoint="./utils/prettify.sh",
         interactive=False,
         it=False,
-        docker_args="",
+        docker_args=getattr(args, "docker_args", "") or "",
         ip_port=None,
         yes=True,
         verbose=getattr(args, "verbose", False),

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/cave_cli/commands/reset.py

@@ -40,7 +40,7 @@ def reset(
         entrypoint="./utils/reset_db.sh",
         interactive=False,
         it=False,
-        docker_args="",
+        docker_args=getattr(args, "docker_args", "") or "",
         ip_port=None,
         yes=True,
         verbose=getattr(args, "verbose", False),

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/cave_cli/commands/run.py

@@ -1,4 +1,5 @@
 import argparse
+import shlex
 import signal
 import sys
 import threading
@@ -8,12 +9,14 @@ from cave_cli.utils.display import (
     RunDashboard,
     print_section,
     step_done,
+    step_fail,
     step_start,
 )
 from cave_cli.utils.docker import (
     build_image,
     create_network,
     remove_containers,
+    run_and_log,
     run_detached,
     run_detached_logged,
     run_interactive,
@@ -49,10 +52,11 @@ def run_cave(
     show_all = getattr(args, "show_all", False) or getattr(args, "verbose", False) or getattr(args, "loglevel", "INFO").upper() == "DEBUG"
     entrypoint = getattr(args, "entrypoint", None) or "./utils/run_server.sh"
     docker_args_str = getattr(args, "docker_args", "") or ""
-    extra_docker_args = docker_args_str.split() if docker_args_str else []
+    extra_docker_args = shlex.split(docker_args_str) if docker_args_str else []
     ip_port_arg = getattr(args, "ip_port", None)
     command_args = getattr(args, "command_args", []) or []
     extra_env = getattr(args, "extra_env", {}) or {}
+    quiet = getattr(args, "quiet", False) or getattr(args, "loglevel", "INFO").upper() == "SILENT"
 
     is_server_run = entrypoint == "./utils/run_server.sh" and not interactive
     use_tui = is_server_run and not show_all
@@ -136,6 +140,50 @@ def run_cave(
 
     django_volumes = [f"{app_dir}:/app"]
 
+    # Check if database needs initialization
+    if is_server_run and "postgres" in db_image.lower():
+        from cave_cli.utils.docker import is_container_ready, is_db_initialized
+        from cave_cli.utils.validate import confirm_action
+
+        db_container = f"{app_name}_db_host"
+        db_user = f"{app_name}_user"
+        db_name = f"{app_name}_name"
+
+        step_start("Checking database")
+        import time
+
+        ready = False
+        for _ in range(30):
+            if is_container_ready(db_container, db_user):
+                ready = True
+                break
+            time.sleep(1)
+
+        if ready:
+            if not is_db_initialized(db_container, db_user, db_name):
+                step_done("Checking database")
+                confirm_action(
+                    "The database for this app is not set up. "
+                    "Would you like to set it up now?"
+                )
+                step_start("Initializing database")
+                run_interactive(
+                    name=f"{app_name}_django_setup",
+                    image=f"cave-app:{app_name}",
+                    network=network,
+                    volumes=django_volumes,
+                    env_vars=django_env,
+                    command=["./utils/reset_db.sh"],
+                )
+                run_and_log(["docker", "rm", f"{app_name}_django_setup"])
+                step_done("Initializing database")
+            else:
+                step_done("Checking database")
+        else:
+            step_fail("Checking database", "Database container failed to become ready.")
+            remove_containers(app_name)
+            sys.exit(1)
+
     parsed = parse_ip_port(ip_port_arg) if ip_port_arg else None
     django_container = f"{app_name}_django"
 
@@ -177,7 +225,7 @@ def run_cave(
         url = f"https://{ip}:{port}"
 
         if interactive:
-            logger.header("CAVE App: (Interactive)")
+            logger.header("CAVE App (Interactive)")
             run_interactive(
                 name=django_container,
                 image=f"cave-app:{app_name}",
@@ -189,8 +237,8 @@ def run_cave(
                 command=server_command,
             )
             remove_containers(app_name)
-
         elif use_tui:
+            logger.header("CAVE App (TUI)")
             _run_tui(
                 app_name=app_name,
                 django_container=django_container,
@@ -205,6 +253,7 @@ def run_cave(
             )
 
         else:
+            logger.header("CAVE App (CLI)")
             if is_server_run:
                 logger.info(
                     f"Your Cave App can be accessed from Chrome at:\n{url}"
@@ -226,7 +275,7 @@ def run_cave(
         url = f"http://localhost:{port}"
 
         if interactive:
-            logger.header("CAVE App: (Interactive)")
+            logger.header("CAVE App (Interactive)")
             run_interactive(
                 name=django_container,
                 image=f"cave-app:{app_name}",
@@ -240,6 +289,7 @@ def run_cave(
             remove_containers(app_name)
 
         elif use_tui:
+            logger.header("CAVE App (TUI)")
             _run_tui(
                 app_name=app_name,
                 django_container=django_container,
@@ -254,6 +304,7 @@ def run_cave(
             )
 
         else:
+            logger.header("CAVE App (CLI)")
             if is_server_run:
                 logger.info(
                     f"Your Cave App can be accessed from Chrome at:\n{url}"

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/cave_cli/commands/sync_cmd.py

@@ -12,7 +12,7 @@ from cave_cli.utils.sync import sync_files
 from cave_cli.utils.validate import confirm_action, find_app_dir
 
 
-def sync_cmd(args: argparse.Namespace) -> None:
+def sync_cmd(args: argparse.Namespace, do_reset: bool=True) -> None:
     """
     Usage:
 
@@ -69,11 +69,12 @@ def sync_cmd(args: argparse.Namespace) -> None:
 
     shutil.rmtree(temp_dir, ignore_errors=True)
 
-    reset_args = argparse.Namespace(
-        yes=True,
-        verbose=getattr(args, "verbose", False),
-        loglevel=getattr(args, "loglevel", "INFO"),
-    )
-    reset(reset_args)
+    if do_reset:
+        reset_args = argparse.Namespace(
+            yes=True,
+            verbose=getattr(args, "verbose", False),
+            loglevel=getattr(args, "loglevel", "INFO"),
+        )
+        reset(reset_args)
 
     logger.success("Sync complete.")

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/cave_cli/commands/test.py

@@ -30,7 +30,7 @@ def test(args: argparse.Namespace) -> None:
         extra_env=extra_env,
         interactive=False,
         it=False,
-        docker_args="",
+        docker_args=getattr(args, "docker_args", "") or "",
         ip_port=None,
         yes=True,
         verbose=getattr(args, "verbose", False),

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/cave_cli/commands/uninstall.py

@@ -5,15 +5,14 @@ import sys
 
 from cave_cli.utils.display import RED, RESET, step_done, step_start
 from cave_cli.utils.logger import logger
-
-PIPX_DOCS_URL = "https://pipx.pypa.io/stable/installation/"
+from cave_cli.commands.doctor import check_uv
 
 
 def uninstall(args: argparse.Namespace) -> None:
     """
     Usage:
 
-    - Removes the CAVE CLI package via pipx.
+    - Removes the CAVE CLI package via uv.
     """
     try:
         response = input(
@@ -28,17 +27,15 @@ def uninstall(args: argparse.Namespace) -> None:
         logger.error("Uninstall canceled")
         return
 
-    pipx = shutil.which("pipx")
-    if not pipx:
-        logger.error(
-            "pipx not found. Please uninstall cave_cli manually."
-        )
-        logger.error(f"See: {PIPX_DOCS_URL}")
+    has_uv, uv_message, uv_path = check_uv()
+    if not has_uv:
+        logger.error(uv_message)
+        logger.error(f"You may need to uninstall CAVE CLI manually based on how it was installed.")
         sys.exit(1)
 
     step_start("Removing installation")
     result = subprocess.run(
-        [pipx, "uninstall", "cave_cli"],
+        [uv_path, "tool", "uninstall", "cave_cli"],
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         text=True,

{cave_cli-3.5.4 → cave_cli-3.6.0b1}/cave_cli/commands/update.py

@@ -1,13 +1,13 @@
 import argparse
-import shutil
 import subprocess
 import sys
 import tempfile
 
 from cave_cli.utils.display import step_done, step_start
 from cave_cli.utils.logger import logger
+from cave_cli.commands.doctor import check_uv
 
-PIPX_DOCS_URL = "https://pipx.pypa.io/stable/installation/"
+UV_DOCS_URL = "https://docs.astral.sh/uv/"
 CLI_REPO_URL = "https://github.com/MIT-CAVE/cave_cli.git"
 
 
@@ -15,32 +15,30 @@ def update(args: argparse.Namespace) -> None:
     """
     Usage:
 
-    - Updates the CAVE CLI via pipx.
+    - Updates the CAVE CLI via uv.
 
     Notes:
 
-    - Without ``--version``, installs the latest version from PyPI via
-      ``pipx install --force cave_cli``.
-    - With ``--version``, reinstalls via ``pipx install --force`` from the
-      specified git tag or branch.
+    - Without ``--version``, upgrades to the latest version from PyPI via
+      ``uv tool upgrade cave_cli``.
+    - With ``--version``, reinstalls via ``uv tool install --reinstall`` from
+      the specified git tag or branch.
     - On Windows, the update runs in a new console window because Windows
       locks running executables and cave.exe cannot replace itself.
     """
-    pipx = shutil.which("pipx")
-    if not pipx:
-        logger.error(
-            "pipx not found. Please install pipx and reinstall cave_cli."
-        )
-        logger.error(f"See: {PIPX_DOCS_URL}")
+    has_uv, uv_message, uv_path= check_uv()
+    if not has_uv:
+        logger.error(uv_message)
+        logger.error(f"The cave_cli package may need to be updated manually based on how it was installed.")
         sys.exit(1)
 
     version = getattr(args, "version", None)
     if version:
         label = f"Reinstalling CAVE CLI ({version})"
-        spec = f"cave_cli @ git+{CLI_REPO_URL}@{version}"
+        cmd = [uv_path, "tool", "install", "--reinstall", f"cave_cli @ git+{CLI_REPO_URL}@{version}"]
     else:
         label = "Updating CAVE CLI"
-        spec = "cave_cli"
+        cmd = [uv_path, "tool", "upgrade", "cave_cli"]
 
     step_start(label)
 
@@ -54,7 +52,7 @@ def update(args: argparse.Namespace) -> None:
         ) as f:
             f.write("@echo off\r\n")
             f.write("timeout /t 1 /nobreak >nul\r\n")
-            f.write(f'"{pipx}" install --force "{spec}"\r\n')
+            f.write(" ".join(f'"{c}"' for c in cmd) + "\r\n")
             f.write('del "%~f0"\r\n')
             bat_path = f.name
         subprocess.Popen(
@@ -66,7 +64,7 @@ def update(args: argparse.Namespace) -> None:
         return
 
     result = subprocess.run(
-        [pipx, "install", "--force", spec],
+        cmd,
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         text=True,