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 uv (required to run cave update and cave uninstall):

uv tool install cave_cli

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

macOS

# With Homebrew (recommended)
brew install uv

# Or with the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

For more options see the uv 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 uv 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 uv:

uv tool 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.