cave-cli 3.5.2

CLI for creating and managing Docker-based CAVE web applications.

CAVE CLI

A cross-platform CLI for creating and managing Docker-based CAVE web applications.

Developed by MIT-CAVE (Center for Transportation & Logistics). Licensed under Apache 2.0.

Prerequisites

• Python 3.11+
• Docker 23.0.6+
• Git

Ubuntu

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh
# Add the current user to the docker group
dockerd-rootless-setuptool.sh install
# Make sure it works outside of sudo
docker run hello-world

macOS

• Install Docker Desktop: https://docs.docker.com/docker-for-mac/install/

Windows

• Install Docker Desktop: https://docs.docker.com/docker-for-windows/install/

Installation

Install with pipx (recommended — keeps the CLI isolated from your system Python):

pipx install cave_cli

If you don't have pipx, install it first:

macOS

# With Homebrew (recommended)
brew install pipx
pipx ensurepath

# Or with pip
pip3 install --user pipx
pipx ensurepath

Other Linux / Windows

python3 -m pip install --user pipx
pipx ensurepath

For more options see the pipx installation guide.

Verify the installation and check your environment health:

cave doctor

Quick Start

cave create my_app
cd my_app
cave run
# Open http://localhost:8000/ in your browser

CLI Commands

cave --help

Core Commands

Command	Description
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

Peripheral Commands

Command	Description
cave reset	Remove containers/volumes and rebuild from scratch
cave upgrade	Upgrade app files from the upstream template
cave sync --url <url>	Merge files from another repository into the app
cave test	Run tests in cave_api/tests/
cave prettify	Format code with autoflake and black
cave purge <path>	Remove an app and all its Docker resources

Utility Commands

Command	Description
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

Global Flags

Flag	Description
-v, --verbose	Enable verbose (DEBUG) logging output
--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

cave update

Or directly via pipx:

pipx upgrade cave_cli

License Notice

Copyright 2023 Massachusetts Institute of Technology (MIT), Center for Transportation & Logistics (CTL)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.