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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cave_cli
-Version: 3.5.4
+Version: 3.6.0
 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.0}/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.0}/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",
@@ -157,11 +164,16 @@ def main():
         "reset",
         aliases=["reset-db"],
         help=(
-            "Remove Docker containers and volumes, "
-            "then rebuild from scratch"
+            "Remove Docker containers and volumes, " "then rebuild from scratch"
         ),
     )
     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 +245,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 +265,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 +425,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.0}/cave_cli/commands/create.py

@@ -8,7 +8,12 @@ from pathlib import Path
 from cave_cli.commands.reset import reset
 from cave_cli.commands.run import run_cave
 from cave_cli.utils.constants import HTTPS_URL
-from cave_cli.utils.display import print_section, step_done, step_fail, step_start
+from cave_cli.utils.display import (
+    print_section,
+    step_done,
+    step_fail,
+    step_start,
+)
 from cave_cli.utils.docker import build_image, generate_secret_key
 from cave_cli.utils.env import create_env_interactive
 from cave_cli.utils.git import add, branch_rename, clone, commit, init

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

@@ -34,31 +34,38 @@ 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 (
+    output = (
         False,
-        "pipx is not installed. Please install pipx: https://pipx.pypa.io/",
+        "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 +133,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 +152,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.0}/cave_cli/commands/list_cmd.py

@@ -20,9 +20,12 @@ 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 +43,8 @@ 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.0}/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:
@@ -51,10 +48,11 @@ def list_versions(args: argparse.Namespace) -> None:
 
     all_versions = sorted(
         (
-            v for v in set().union(*repo_tags.values())
+            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 +62,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)
@@ -91,7 +89,10 @@ def list_versions(args: argparse.Namespace) -> None:
             row = indent + f"{v:<{version_w}}"
             for r, w in zip(repos, col_w):
                 mark = f"{GREEN}✓{RESET}" if v in repo_tags[r] else ""
-                row += " " * pad + f"{mark:^{w + len(GREEN) + len(RESET) if mark else w}}"
+                row += (
+                    " " * pad
+                    + f"{mark:^{w + len(GREEN) + len(RESET) if mark else w}}"
+                )
             print(row)
 
         if hidden:

{cave_cli-3.5.4 → cave_cli-3.6.0}/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.0}/cave_cli/commands/purge.py

@@ -64,11 +64,19 @@ def purge(args: argparse.Namespace) -> None:
             "Some files are owned by root (created by Docker). "
             "Removing via Docker..."
         )
-        run_and_log([
-            "docker", "run", "--rm",
-            "-v", f"{abs_path}:/purge",
-            "alpine", "rm", "-rf", "/purge",
-        ])
+        run_and_log(
+            [
+                "docker",
+                "run",
+                "--rm",
+                "-v",
+                f"{abs_path}:/purge",
+                "alpine",
+                "rm",
+                "-rf",
+                "/purge",
+            ]
+        )
         if os.path.isdir(abs_path):
             try:
                 shutil.rmtree(abs_path)

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

@@ -40,11 +40,13 @@ 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),
         loglevel=getattr(args, "loglevel", "INFO"),
     )
-    run_cave(app_dir, app_name, reset_args, skip_header=True, skip_build=skip_build)
+    run_cave(
+        app_dir, app_name, reset_args, skip_header=True, skip_build=skip_build
+    )
     step_done("Reset complete")

{cave_cli-3.5.4 → cave_cli-3.6.0}/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,
@@ -46,13 +49,21 @@ def run_cave(
     interactive = getattr(args, "interactive", False) or getattr(
         args, "it", False
     )
-    show_all = getattr(args, "show_all", False) or getattr(args, "verbose", False) or getattr(args, "loglevel", "INFO").upper() == "DEBUG"
+    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,15 +147,60 @@ 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"
 
     if parsed:
         ip, port = parsed
         if not is_port_available(port):
-            logger.error(
-                "The specified port is in use. Please try another."
-            )
+            logger.error("The specified port is in use. Please try another.")
             sys.exit(1)
 
         if is_server_run and not interactive:
@@ -177,7 +233,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 +245,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 +261,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 +283,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 +297,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 +312,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.0}/cave_cli/commands/sync_cmd.py

@@ -5,14 +5,19 @@ import tempfile
 
 from cave_cli.commands.reset import reset
 from cave_cli.utils.constants import HTTPS_URL
-from cave_cli.utils.display import print_section, step_done, step_start, print_key_value
+from cave_cli.utils.display import (
+    print_section,
+    step_done,
+    step_start,
+    print_key_value,
+)
 from cave_cli.utils.git import clone
 from cave_cli.utils.logger import logger
 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 +74,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.0}/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),