cb-container

A cross-platform container management tool for Docker and nerdctl (Rancher Desktop). Provides a unified CLI to list images, start/stop containers, connect interactively, view logs, scan for vulnerabilities, and more.

Available as cb-container (shell) and cb-container.bat (Windows batch). Both versions provide identical functionality.

Runtime Detection

cb-container automatically detects the container runtime:

nerdctl is preferred if available (Rancher Desktop)
docker is used as fallback (Docker Desktop)

Quick Start

# List running containers
cb-container -l

# List all images
cb-container -l -a

# Filter images by name prefix
cb-container -l alpine

# Connect to a container (starts interactively if not running)
cb-container -i ubuntu

# Start a container (detached)
cb-container --start my-app

# Stop a container
cb-container --stop my-app

# View logs
cb-container --log my-app

# Scan for vulnerabilities
cb-container --scan my-app

# Scan all images
cb-container --scan -a

Project-Aware Mode

When run from a directory containing settings.gradle, cb-container automatically detects the project name from the rootProject.name property.

# In a project directory with settings.gradle:
cb-container                     # lists only this project's images
cb-container --scan              # scans the project image
cb-container --start             # starts the project image
cb-container --stop              # stops the project container
cb-container --log               # shows logs of the project container
cb-container --delete            # deletes the project image

The --list / -l flag is not affected by project detection — it always shows all images (or filtered by an explicit prefix).

Local Cache

When in a project directory, scan results are stored locally:

Default: build/container/
Testing projects (where gradle.properties has projectType = testing): build/reports/testing/

Commands

Option	Description
`-h`, `--help`	Show the help message.
`-v`, `--version`	Print version information.
`-l`, `--list [filter]`	List images with running containers. Optionally filter by image name prefix.
`-a`, `--all`	Show all images (default: running only).
`-w`, `--wide`	Show wider columns for installed/fixed versions in scan output.
`-f`, `--force`	Force scan, ignore cached results.
`--csv`	Output as CSV (semicolon-separated). Used with `-l`/`--list -a`, `--scan -a`, or `--scan img1,img2`.
`--verbose`	Show additional information (cache status, file paths, list summary).
`-i`, `--it [name\|id]`	Connect to a running container. If not running, starts it interactively. Supports distro aliases.
`-s`, `--shell <shell>`	Shell to use when connecting (default: `/bin/sh`).
`-e`, `--entrypoint <entry>`	Override entrypoint when starting a container.
`-p`, `--port <port>`	Publish port. Single port maps to same host port (e.g. `-p 8080` → `8080:8080`). With colon, taken as-is.
`--env <vars>`	Set environment variables (comma-separated). Example: `--env KEY="val",K2="v2"`
`--start [name\|id]`	Start a container detached. Without name, auto-detects from `settings.gradle`.
`--stop [name\|id]`	Stop a running container. Without name, auto-detects from `settings.gradle`.
`--log [name\|id] [n]`	Show logs of a container. Supports line ranges: `10`, `5-10`, `5-`, `-7`.
`-t`, `--tail`	Tail (follow) mode, used with `--log`.
`--scan [name\|id]`	Scan image(s) with trivy. Comma-separated for multiple. Without name, auto-detects from `settings.gradle`.
`--delete [name\|id]`	Delete an image. Without name, auto-detects from `settings.gradle`.
`--clean`	Clean the scan cache and prune dangling images.

Listing Images (`-l`, `--list`)

Show images with running container info. By default only images with running containers are shown.

cb-container -l                      # running containers only
cb-container -l -a                   # all images
cb-container -l alpine               # filter by name prefix (implies -a)
cb-container -l al                   # partial prefix match
cb-container -l --verbose            # includes summary: N image(s), M running.

Output columns: IMAGE ID, CONTAINER ID, CREATED, STARTED, SIZE, TAG. Sorted alphabetically by tag name. The header shows a right-aligned timestamp and image count.

When a filter prefix is provided, only images whose repository name or image ID starts with the prefix are shown, and -a (show all) is implied automatically.

Starting Containers (`--start`)

Start a container in detached mode (background).

cb-container --start my-app                  # resolves :latest or newest tag
cb-container --start my-app:1.0.0            # specific tag
cb-container --start 34b83c5c873f            # by image ID

If the image is not found locally, it tries to pull it (appending :latest if no tag specified). If a container from the same image is already running, reports the existing container ID.

Combined with other options

cb-container --start my-app -i               # start + attach interactive shell
cb-container --start my-app -t               # start + tail logs
cb-container --start my-app --log 10         # start + show first 10 log lines
cb-container --start my-app --log 5- -t      # start + tail from line 5

Distro Aliases

Alias	Maps to
`arch`	`archlinux`
`debian`	`library/debian`
`kali`	`kalilinux/kali-rolling`

Stopping Containers (`--stop`)

Stop a running container by name, image name, or container/image ID.

cb-container --stop my-app
cb-container --stop abc123def456             # by container ID
cb-container --stop 34b83c5c873f             # by image ID

If the image doesn't exist, reports "Image not found" instead of "No running container found".

Connecting to Containers (`-i`, `--it`)

Connect to a running container. If no container is running for the given image, starts one interactively with -it --rm.

cb-container -i my-app                       # by image name
cb-container -i abc123                       # by container ID
cb-container -i b2b5369197a8                 # by image ID
cb-container -i ubuntu                       # pulls + runs if not local
cb-container -i kali                         # alias for kalilinux/kali-rolling
cb-container -i ubuntu -s /bin/bash          # use bash as shell
cb-container --start my-app -i              # start detached + connect

Viewing Logs (`--log`)

cb-container --log my-app                    # full logs
cb-container --log my-app 10                 # first 10 lines
cb-container --log my-app 5-10               # lines 5 to 10
cb-container --log my-app 5-                 # from line 5 to end
cb-container --log my-app -7                 # lines 1 to 7
cb-container --log my-app -t                 # tail (follow) logs
cb-container --log my-app 10- -t             # tail from line 10

Log header is only shown with --verbose. Can be combined with --start.

Scanning for Vulnerabilities (`--scan`)

Scan images for security vulnerabilities using trivy. Results are cached with automatic invalidation.

cb-container --scan my-app                   # scan single image
cb-container --scan my-app,nginx:alpine      # scan multiple (comma-separated)
cb-container --scan alpine:3.16              # pulls if not local
cb-container --scan -a                       # scan ALL images (CRIT/HIGH/MED/LOW columns)
cb-container --scan img1,img2                # scan multiple (list-style with severity columns)
cb-container --scan -a --csv                 # CSV output
cb-container --list -a --csv                 # list as CSV
cb-container --scan -a -l my                 # scan all images filtered by prefix
cb-container --scan my-app -w               # wide output (full column widths)
cb-container --scan my-app -f               # force rescan (ignore cache)

Scan All Images (`--scan -a`)

When combined with -a / --all, scans every image and displays a list-style table with per-severity columns (CRIT, HIGH, MED, LOW) replacing SIZE and STARTED. Scanning multiple comma-separated images uses the same format. Supports image ID prefixes.

Wide Output (`-w`, `--wide`)

Shows full (untruncated) PACKAGE, INSTALLED, and FIXED columns with a wider separator line.

Force Rescan (`-f`, `--force`)

Ignores cached results and forces a fresh trivy scan.

CSV Output (`--csv`)

Output as semicolon-separated CSV. Suppresses separator lines and footers. Works with --list -a, --scan -a, and --scan img1,img2.

cb-container --list -a --csv                 # list all images as CSV
cb-container --scan -a --csv                 # scan all images as CSV
cb-container --scan img1,img2 --csv          # scan specific images as CSV

List CSV header: IMAGE ID;CONTAINER ID;CREATED;STARTED;SIZE;TAG
Scan CSV header: IMAGE ID;CONTAINER ID;CREATED;CRIT;HIGH;MED;LOW;TAG

Trivy Detection

If trivy is not in PATH, the script tries source cb --setenv (shell) or call cb --setenv (batch) to load the environment including TRIVY_HOME.

Output Format

Results are sorted by severity (CRITICAL, HIGH, MEDIUM, LOW):

------------------------------------------------------------------------------------------------------------------------
CVE ID                 SEV  PACKAGE                        INSTALLED      FIXED          TARGET      2026-04-23 16:30:21
------------------------------------------------------------------------------------------------------------------------
CVE-2026-28390         H    libcrypto3                     3.5.5-r0       3.5.6-r0       alpine:latest (alpine 3.23.3)
CVE-2026-28388         M    libcrypto3                     3.5.5-r0       3.5.6-r0       alpine:latest (alpine 3.23.3)
CVE-2026-2673          L    libcrypto3                     3.5.5-r0       3.5.6-r0       alpine:latest (alpine 3.23.3)
------------------------------------------------------------------------------------------------------------------------
Summary: 20 vulnerabilities (CRITICAL: 0, HIGH: 5, MEDIUM: 11, LOW: 4) [12s]
------------------------------------------------------------------------------------------------------------------------

SEV: C = CRITICAL, H = HIGH, M = MEDIUM, L = LOW
PACKAGE: truncated from left with .. if too long (full width with -w)
INSTALLED / FIXED: truncated from left with .. if too long (full width with -w)
FIXED: shows - when no fix is available; multiple fix versions on continuation lines
Duration: shown in brackets at the end of the summary line

Caching

Scan results are cached with filenames like <imageId>-<YYYYMMDD-HHmmss>-trivy.json, .rows, and .counts.

Cache is stored in:

Project directory: build/container/ (or build/reports/testing/ for testing projects) when settings.gradle is present
Global temp: $CB_TEMP/cb-container/ otherwise

Cache is automatically invalidated when:

A new day starts (day boundary)
The image has been rebuilt (creation timestamp newer than cache)
--force / -f is used

Deleting Images (`--delete`)

Delete an image by name or ID. Refuses if a container is currently running from the image.

cb-container --delete my-app
cb-container --delete my-app:0.0.1-SNAPSHOT
cb-container --delete 34b83c5c873f

Cleaning Cache (`--clean`)

Remove cached scan results and prune dangling images. Can be combined with other actions.

cb-container --clean                         # clean + show verbose output
cb-container --clean --scan my-app           # clean first, then scan

Additional Options

Shell Override (`-s`, `--shell`)

cb-container -i ubuntu -s /bin/bash

Entrypoint Override (`-e`, `--entrypoint`)

cb-container --start my-app -e /bin/bash

Port Publishing (`-p`, `--port`)

cb-container --start my-app -p 8080          # maps to -p 8080:8080
cb-container --start my-app -p 8081:8082     # maps to -p 8081:8082
cb-container --start my-app -p 8080 -p 9090  # multiple ports

Environment Variables (`--env`)

cb-container --start my-app --env DB_HOST="localhost",DB_PORT="5432"

Configuration File (`.cb-container`)

If a .cb-container file exists in the current directory, its first line is read and prepended to the CLI arguments as default parameters.

--env DB_HOST="localhost",DB_PORT="5432" -p 8080

Image Resolution

:latest tag is preferred
Newest available tag as fallback
Image ID — full or short IDs are matched as prefixes
Multi-tag matching — when an image ID has multiple tags, all are checked against running containers

When an image is not found locally (--start, -i, --scan):

If the name contains :, tries to pull as-is
If no :, appends :latest and tries to pull

Auto-Build from Dockerfile

If no command is given and a Dockerfile, dockerfile, or Containerfile exists in the current directory, cb-container automatically builds and runs the image.

Positional Argument

An image name can be passed as a positional argument:

cb-container my-app    # equivalent to --start my-app

Cross-Platform Compatibility

Windows: cb-container.bat using cmd.exe with delayed expansion. Uses PowerShell for JSON parsing and date formatting.
Linux / macOS: cb-container shell script, compatible with bash 3.2+ (macOS default). Uses awk for JSON parsing.
MinGW / Git Bash: Shell script works on Git Bash for Windows.

All container runtime commands are compatible with both Docker and nerdctl. Uses | as field separator in format strings for portability (nerdctl doesn't interpret \t).

Temp Directory

Temporary and cache files are stored in:

In a project directory (with settings.gradle): build/container/ (or build/reports/testing/ for testing projects)
Outside a project: $CB_TEMP/cb-container/ (shell) or %CB_TEMP%\cb-container\ (batch)

If CB_TEMP is not set, defaults to /tmp/cb-$USER (shell) or %TEMP%\cb (batch).

← Back to common-build documentation

GNU General Public License v3.0 — see LICENSE for details. | GitHub

cb-container

Runtime Detection

Quick Start

Project-Aware Mode

Local Cache

Commands

Listing Images (-l, --list)

Starting Containers (--start)

Combined with other options

Distro Aliases

Stopping Containers (--stop)

Connecting to Containers (-i, --it)

Viewing Logs (--log)

Scanning for Vulnerabilities (--scan)

Scan All Images (--scan -a)

Wide Output (-w, --wide)

Force Rescan (-f, --force)

CSV Output (--csv)