cave-cli 3.5.0__tar.gz → 3.5.2__tar.gz

{cave_cli-3.5.0/cave_cli.egg-info → cave_cli-3.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cave_cli
-Version: 3.5.0
+Version: 3.5.2
 Summary: CLI for creating and managing Docker-based CAVE web applications.
 Author-email: MIT-CAVE <cave-contact@mit.edu>
 License: Apache-2.0
@@ -50,28 +50,49 @@ docker run hello-world
 <details>
 <summary>Windows</summary>
 
-- Install Docker Desktop for WSL: https://docs.docker.com/desktop/wsl/
-- Install WSL2 with Ubuntu: https://learn.microsoft.com/en-us/windows/wsl/install
-- Open your WSL Ubuntu terminal for all `cave` commands
+- Install Docker Desktop: https://docs.docker.com/docker-for-windows/install/
 
 </details>
 
 ## Installation
 
+Install with [pipx](https://pipx.pypa.io/) (recommended — keeps the CLI isolated from your system Python):
+
 ```sh
-pip install git+https://github.com/MIT-CAVE/cave_cli.git
+pipx install cave_cli
 ```
 
-Or with [pipx](https://pipx.pypa.io/) (recommended for CLI tools):
+If you don't have pipx, install it first:
+
+<details>
+<summary>macOS</summary>
 
 ```sh
-pipx install git+https://github.com/MIT-CAVE/cave_cli.git
+# With Homebrew (recommended)
+brew install pipx
+pipx ensurepath
+
+# Or with pip
+pip3 install --user pipx
+pipx ensurepath
 ```
 
-Verify the installation:
+</details>
+<details>
+<summary>Other Linux / Windows</summary>
 
 ```sh
-cave --version
+python3 -m pip install --user pipx
+pipx ensurepath
+```
+</details>
+
+For more options see the [pipx installation guide](https://pipx.pypa.io/stable/installation/).
+
+Verify the installation and check your environment health:
+
+```sh
+cave doctor
 ```
 
 ## Quick Start
@@ -94,7 +115,8 @@ cave --help
 | Command | Description |
 |---|---|
 | `cave create <name>` | Create a new CAVE app from the template repository |
-| `cave run` | Build Docker image and run the app |
+| `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 |
 
 ### Peripheral Commands
 
@@ -114,6 +136,7 @@ cave --help
 | `cave list` | List running CAVE apps |
 | `cave kill` | Stop Docker containers for an app |
 | `cave list-versions` | List available CAVE app versions |
+| `cave theme <name>` | Set the CLI color theme (dark, light, solarized, monokai) |
 | `cave update` | Update the CAVE CLI itself |
 | `cave uninstall` | Remove the CAVE CLI |
 | `cave version` | Print version information |
@@ -126,16 +149,24 @@ cave --help
 | `--loglevel LEVEL` | Set log level: DEBUG, INFO, WARN, ERROR, SILENT |
 | `-y`, `--yes` | Automatically answer confirmation prompts with yes |
 
+### `cave run` Options
+
+| Flag | Description |
+|---|---|
+| `--all` | Show raw container output instead of the TUI dashboard |
+| `-it`, `--interactive` | Run in interactive mode (drops into a bash shell) |
+| `ip:port` | Optional argument for LAN hosting (e.g. `192.168.1.1:8000`) |
+
 ## Updating
 
 ```sh
-pip install --upgrade git+https://github.com/MIT-CAVE/cave_cli.git
+cave update
 ```
 
-Or:
+Or directly via pipx:
 
 ```sh
-cave update
+pipx upgrade cave_cli
 ```
 
 ## License Notice

{cave_cli-3.5.0 → cave_cli-3.5.2}/README.md

@@ -33,28 +33,49 @@ docker run hello-world
 <details>
 <summary>Windows</summary>
 
-- Install Docker Desktop for WSL: https://docs.docker.com/desktop/wsl/
-- Install WSL2 with Ubuntu: https://learn.microsoft.com/en-us/windows/wsl/install
-- Open your WSL Ubuntu terminal for all `cave` commands
+- Install Docker Desktop: https://docs.docker.com/docker-for-windows/install/
 
 </details>
 
 ## Installation
 
+Install with [pipx](https://pipx.pypa.io/) (recommended — keeps the CLI isolated from your system Python):
+
 ```sh
-pip install git+https://github.com/MIT-CAVE/cave_cli.git
+pipx install cave_cli
 ```
 
-Or with [pipx](https://pipx.pypa.io/) (recommended for CLI tools):
+If you don't have pipx, install it first:
+
+<details>
+<summary>macOS</summary>
 
 ```sh
-pipx install git+https://github.com/MIT-CAVE/cave_cli.git
+# With Homebrew (recommended)
+brew install pipx
+pipx ensurepath
+
+# Or with pip
+pip3 install --user pipx
+pipx ensurepath
 ```
 
-Verify the installation:
+</details>
+<details>
+<summary>Other Linux / Windows</summary>
 
 ```sh
-cave --version
+python3 -m pip install --user pipx
+pipx ensurepath
+```
+</details>
+
+For more options see the [pipx installation guide](https://pipx.pypa.io/stable/installation/).
+
+Verify the installation and check your environment health:
+
+```sh
+cave doctor
 ```
 
 ## Quick Start
@@ -77,7 +98,8 @@ cave --help
 | Command | Description |
 |---|---|
 | `cave create <name>` | Create a new CAVE app from the template repository |
-| `cave run` | Build Docker image and run the app |
+| `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 |
 
 ### Peripheral Commands
 
@@ -97,6 +119,7 @@ cave --help
 | `cave list` | List running CAVE apps |
 | `cave kill` | Stop Docker containers for an app |
 | `cave list-versions` | List available CAVE app versions |
+| `cave theme <name>` | Set the CLI color theme (dark, light, solarized, monokai) |
 | `cave update` | Update the CAVE CLI itself |
 | `cave uninstall` | Remove the CAVE CLI |
 | `cave version` | Print version information |
@@ -109,16 +132,24 @@ cave --help
 | `--loglevel LEVEL` | Set log level: DEBUG, INFO, WARN, ERROR, SILENT |
 | `-y`, `--yes` | Automatically answer confirmation prompts with yes |
 
+### `cave run` Options
+
+| Flag | Description |
+|---|---|
+| `--all` | Show raw container output instead of the TUI dashboard |
+| `-it`, `--interactive` | Run in interactive mode (drops into a bash shell) |
+| `ip:port` | Optional argument for LAN hosting (e.g. `192.168.1.1:8000`) |
+
 ## Updating
 
 ```sh
-pip install --upgrade git+https://github.com/MIT-CAVE/cave_cli.git
+cave update
 ```
 
-Or:
+Or directly via pipx:
 
 ```sh
-cave update
+pipx upgrade cave_cli
 ```
 
 ## License Notice

{cave_cli-3.5.0 → cave_cli-3.5.2}/cave_cli/cli.py

@@ -142,6 +142,13 @@ def main():
         default=False,
         help="Run in interactive mode (entrypoint set to bash)",
     )
+    p_run.add_argument(
+        "--all",
+        dest="show_all",
+        action="store_true",
+        default=False,
+        help="Show raw container output instead of the TUI dashboard (also enabled by --verbose)",
+    )
 
     # ------------------------------------------------------------------ #
     # reset                                                                #
@@ -265,6 +272,13 @@ def main():
         help="Stop Docker containers for a CAVE app",
     )
     add_global_args(p_kill)
+    p_kill.add_argument(
+        "name",
+        nargs="?",
+        default=None,
+        metavar="app-name",
+        help="Name of the CAVE app to kill",
+    )
     p_kill.add_argument(
         "-a",
         "--all",
@@ -309,6 +323,15 @@ def main():
         help="Glob pattern to filter versions (e.g. v3.*, v3.4.*)",
     )
 
+    # ------------------------------------------------------------------ #
+    # doctor                                                               #
+    # ------------------------------------------------------------------ #
+    p_doctor = subparsers.add_parser(
+        "doctor",
+        help="Check the health of the CAVE environment",
+    )
+    add_global_args(p_doctor)
+
     # ------------------------------------------------------------------ #
     # update                                                               #
     # ------------------------------------------------------------------ #
@@ -342,6 +365,22 @@ def main():
     )
     add_global_args(p_version)
 
+    # ------------------------------------------------------------------ #
+    # theme                                                                #
+    # ------------------------------------------------------------------ #
+    p_theme = subparsers.add_parser(
+        "theme",
+        help="Set the CLI color theme",
+    )
+    add_global_args(p_theme)
+    p_theme.add_argument(
+        "name",
+        nargs="?",
+        default=None,
+        metavar="THEME",
+        help="Name of the theme to apply (dark, light, solarized, monokai)",
+    )
+
     # ------------------------------------------------------------------ #
     # Dispatch                                                             #
     # ------------------------------------------------------------------ #
@@ -371,85 +410,99 @@ def main():
     # Command dispatch                                                     #
     # ------------------------------------------------------------------ #
     if args.command == "create":
-        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.create import create
 
-        check_docker()
+        check_all()
         create(args)
 
     elif args.command == "run":
-        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.run import run
 
-        check_docker()
+        check_all()
         run(args)
 
     elif args.command == "reset":
-        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.reset import reset
 
-        check_docker()
+        check_all()
         reset(args)
 
     elif args.command == "upgrade":
-        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.upgrade import upgrade
 
-        check_docker()
+        check_all()
         upgrade(args)
 
     elif args.command == "sync":
-        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.sync_cmd import sync_cmd
 
-        check_docker()
+        check_all()
         sync_cmd(args)
 
     elif args.command == "test":
-        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.test import test
 
-        check_docker()
+        check_all()
         test(args)
 
     elif args.command == "prettify":
-        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.prettify import prettify
 
-        check_docker()
+        check_all()
         prettify(args)
 
     elif args.command == "list":
-        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.list_cmd import list_cmd
 
-        check_docker()
+        check_all()
         list_cmd(args)
 
     elif args.command == "kill":
-        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.kill import kill
 
-        check_docker()
+        check_all()
         kill(args)
 
     elif args.command == "purge":
-        from cave_cli.utils.docker import check_docker
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.purge import purge
 
-        check_docker()
+        check_all()
         purge(args)
 
     elif args.command == "list-versions":
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.list_versions import list_versions
 
+        check_all()
         list_versions(args)
 
     elif args.command == "update":
+        from cave_cli.commands.doctor import check_all
         from cave_cli.commands.update import update
 
+        check_all()
         update(args)
 
+    elif args.command == "doctor":
+        from cave_cli.commands.doctor import doctor
+
+        doctor(args)
+
+    elif args.command == "theme":
+        from cave_cli.commands.theme import theme_cmd
+
+        theme_cmd(args)
+
     elif args.command == "uninstall":
         from cave_cli.commands.uninstall import uninstall
 

{cave_cli-3.5.0 → cave_cli-3.5.2}/cave_cli/commands/create.py

@@ -8,6 +8,7 @@ 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.docker import build_image, check_docker, generate_secret_key
 from cave_cli.utils.env import create_env_interactive
 from cave_cli.utils.git import add, branch_rename, clone, commit, init
@@ -37,29 +38,31 @@ def create(args: argparse.Namespace) -> None:
     clone_url = getattr(args, "url", None) or HTTPS_URL
     version = getattr(args, "version", None)
 
-    logger.header("App Creation:")
-    logger.info("Downloading the app template...")
+    print_section("App Creation")
 
+    step_start("Downloading app template")
     success = clone(clone_url, app_name, branch=version)
     if not success or not os.path.isdir(app_name):
+        step_fail("Downloading app template")
         logger.error("Clone failed. Ensure you used a valid version.")
         logger.error(
             f"The version must be a tag (or branch) listed at {clone_url}."
         )
         sys.exit(1)
-
-    logger.info("Done")
+    step_done("Downloading app template")
 
     app_dir = os.path.abspath(app_name)
     remove_licence_info(app_dir)
-
     Path(os.path.join(app_dir, ".env")).touch()
 
     example_env = os.path.join(app_dir, "example.env")
     env_path = os.path.join(app_dir, ".env")
 
     build_image(app_name, app_dir)
+
+    step_start("Generating secret key")
     secret_key = generate_secret_key(app_name)
+    step_done("Generating secret key")
 
     create_env_interactive(
         app_name=app_name,
@@ -73,10 +76,11 @@ def create(args: argparse.Namespace) -> None:
         verbose=getattr(args, "verbose", False),
         loglevel=getattr(args, "loglevel", "INFO"),
     )
-    reset(reset_args, app_dir=app_dir, app_name=app_name)
+    reset(reset_args, app_dir=app_dir, app_name=app_name, skip_build=True)
 
-    logger.header("Version Control:")
-    logger.info("Configuring git repository...")
+    print_section("Version Control")
+
+    step_start("Configuring git repository")
     git_dir = os.path.join(app_dir, ".git")
     if os.path.isdir(git_dir):
         rmtree_force(git_dir)
@@ -97,9 +101,9 @@ def create(args: argparse.Namespace) -> None:
     add(app_dir)
     commit(app_dir, "Initialize CAVE App")
     branch_rename(app_dir, "main")
-    logger.info("Done.")
+    step_done("Configuring git repository")
 
-    logger.info("Generating LLM Docs...")
+    step_start("Generating LLM docs")
     docs_args = argparse.Namespace(
         entrypoint="./utils/generate_docs.sh",
         interactive=False,
@@ -110,15 +114,12 @@ def create(args: argparse.Namespace) -> None:
         verbose=getattr(args, "verbose", False),
         loglevel=getattr(args, "loglevel", "INFO"),
     )
-    run_cave(app_dir, app_name, docs_args)
-    logger.info("Done.")
-
-    logger.header("App Creation Status:")
-    logger.info(f"App '{app_name}' created successfully!")
-    logger.info(
-        f"Created variables and additional configuration options "
-        f"are available in {app_name}/.env"
-    )
+    run_cave(app_dir, app_name, docs_args, skip_header=True, skip_build=True)
+    step_done("Generating LLM docs")
+
+    print_section("Done")
+    step_done(f"App '{app_name}' created successfully!")
+    step_done(f"Configuration options available in {app_name}/.env")
 
 
 def force_remove(func, path, exc):

cave_cli-3.5.2/cave_cli/commands/doctor.py

@@ -0,0 +1,170 @@
+import argparse
+import sys
+
+from cave_cli.utils.display import (
+    print_section,
+    step_done,
+    step_fail,
+    step_start,
+)
+from cave_cli.utils.logger import logger
+from cave_cli.utils.subprocess import run, version_tuple
+
+
+def check_git() -> tuple[bool, str]:
+    """
+    Usage:
+
+    - Validates that git is installed
+
+    Returns:
+
+    - ``success``: bool
+    - ``message``: str remediation or version
+    """
+    try:
+        result = run(["git", "--version"])
+        if result.returncode == 0:
+            return True, result.stdout.strip()
+    except FileNotFoundError:
+        pass
+    return (
+        False,
+        "git is not installed. Please install git: https://git-scm.com/",
+    )
+
+
+def check_pipx() -> tuple[bool, str]:
+    """
+    Usage:
+
+    - Validates that pipx is installed
+
+    Returns:
+
+    - ``success``: bool
+    - ``message``: str remediation or version
+    """
+    import shutil
+
+    pipx = shutil.which("pipx")
+    if pipx:
+        try:
+            result = run([pipx, "--version"])
+            if result.returncode == 0:
+                return True, f"pipx version {result.stdout.strip()}"
+        except Exception:
+            pass
+    return (
+        False,
+        "pipx is not installed. Please install pipx: https://pipx.pypa.io/",
+    )
+
+
+def check_docker() -> tuple[bool, str]:
+    """
+    Usage:
+
+    - Validates that Docker is installed, running, and meets the minimum version
+
+    Returns:
+
+    - ``success``: bool
+    - ``message``: str remediation or version
+    """
+    from cave_cli.utils.constants import MIN_DOCKER_VERSION
+
+    try:
+        result = run(["docker", "--version"])
+    except FileNotFoundError:
+        return (
+            False,
+            f"Docker is not installed. "
+            f"Please install Docker version {MIN_DOCKER_VERSION} or greater: "
+            f"https://docs.docker.com/get-docker/",
+        )
+
+    if result.returncode != 0 or not result.stdout:
+        return (
+            False,
+            f"Could determine Docker version. "
+            f"Please install Docker version {MIN_DOCKER_VERSION} or greater.",
+        )
+
+    version_str = result.stdout.strip()
+    import re
+
+    match = re.search(r"(\d+\.\d+\.\d+)", version_str)
+    if not match:
+        return False, f"Could not parse Docker version from: {version_str}"
+
+    current = match.group(1)
+    if version_tuple(current) < version_tuple(MIN_DOCKER_VERSION):
+        return (
+            False,
+            f"Your current Docker version ({current}) is too old. "
+            f"Please install Docker version {MIN_DOCKER_VERSION} or greater.",
+        )
+
+    info_result = run(["docker", "info"])
+    if info_result.returncode != 0:
+        return False, "Docker is not running... Please start Docker."
+
+    return True, version_str
+
+
+def check_all(exit_on_fail: bool = True) -> dict[str, tuple[bool, str]]:
+    """
+    Usage:
+
+    - Runs all environment checks
+
+    Optional:
+
+    - ``exit_on_fail``: bool - Exits the process if any check fails
+    """
+    results = {
+        "Docker": check_docker(),
+        "Git": check_git(),
+        "Pipx": check_pipx(),
+    }
+
+    if exit_on_fail:
+        failed = False
+        for name, (success, message) in results.items():
+            if not success:
+                logger.error(message)
+                failed = True
+        if failed:
+            sys.exit(1)
+
+    return results
+
+
+def doctor(args: argparse.Namespace) -> None:
+    """
+    Usage:
+
+    - Checks the health of the CAVE environment (Docker, Git, Pipx)
+    """
+    print_section("CAVE Doctor")
+
+    results = check_all(exit_on_fail=False)
+
+    all_pass = True
+    for name, (success, message) in results.items():
+        if success:
+            step_done(f"{name}: {message}")
+        else:
+            step_fail(f"{name}: {message}")
+            all_pass = False
+
+    print_section("Status")
+    if all_pass:
+        logger.success("Your environment is healthy and ready to CAVE!")
+    else:
+        logger.error(
+            "Some issues were found in your environment. "
+            "Please follow the remediation steps above."
+        )
+        sys.exit(1)