suave CLI

One command for everyday SUAVE work: Docker images and the container, colcon build/test, experiment campaigns and batches, and the analysis scripts.

The CLI wraps existing tools and does not replace them. Each subcommand builds a docker, colcon, ros2 launch or ros2 run command line and runs it. build_docker_images.sh, the launch files and the runner configs are still the source of truth. Add --dry-run to any command to see what it would run.

• Plain Python (>= 3.10, stdlib only). It runs from the checkout and needs no build or pip.
• It never imports ROS, so it also works on a host that has only Docker.
• suave --help and suave COMMAND --help are the full option reference. This file covers the concepts, workflows and pitfalls.

Contents

• Put it on PATH
• Quick start
• Commands
• Where ROS commands run
• Paths and the container
• Configuration
• Extra mounts
• Scripting and automation
• Troubleshooting
• Development

Put it on PATH

Pick one:

Without any of these, call <repo>/suave_cli/bin/suave directly. Inside the SUAVE images suave is already on PATH, and SUAVE_CLI_CONTEXT=container tells it that it runs in a container.

Which checkout is used: --suave-root PATH, else $SUAVE_ROOT, else the checkout that contains the suave launcher that was run. That checkout’s .config/ holds the settings, and it is the tree suave docker build builds from (it must contain build_docker_images.sh and docker/versions.env).

Quick start

A typical first session on a host with Docker:

suave docker build              # build suave-headless:latest from this checkout
suave docker run                # start container 'suave' in the background
suave test suave_runner         # colcon build + test inside the container
suave run                       # one campaign with the installed runner_config.yml
suave campaign list             # result folders and how many runs finished
suave docker shell              # interactive shell in the container, ROS sourced
suave docker stop               # stop it (add --rm to remove it)

On the first interactive run the CLI offers a short setup. You can skip it: the defaults work, and suave config init asks the questions again later.

Commands

suave docker (host only)

What suave docker run does depends on the container’s current state:

When no image is given (--image or the image setting), the CLI uses the first match:

1. suave-headless:latest
2. suave-headless:dev
3. any other local suave-headless tag (with a warning)
4. ghcr.io/kas-lab/suave-headless:main, pulled after you confirm, or with --yes

By default the container gets these mounts:

• this checkout at /home/ubuntu-user/suave_ws/src/suave
• ~/suave/results at /home/ubuntu-user/suave/results, created if missing
• any saved extra mounts

The container also gets access to the host display and GPU:

| Setup | docker run options | |—|—|

File truncated at 100 lines see the full file