CLI

Cup’s CLI provides the cup check command.

Basic Usage

Check for all updates


$ cup check
✓ Done!
~ Local images
 ╭─────────────────────────────────────────┬──────────────────────────────────┬─────────╮
 │Reference                                │Status                            │Time (ms)│
 ├─────────────────────────────────────────┼──────────────────────────────────┼─────────┤
 │postgres:15-alpine                       │Major update (15 → 17)            │788      │
 │ghcr.io/immich-app/immich-server:v1.118.2│Minor update (1.118.2 → 1.127.0)  │2294     │
 │ollama/ollama:0.4.1                      │Minor update (0.4.1 → 0.5.12)     │533      │
 │adguard/adguardhome:v0.107.52            │Patch update (0.107.52 → 0.107.57)│1738     │
 │jc21/nginx-proxy-manager:latest          │Up to date                        │583      │
 │louislam/uptime-kuma:1                   │Up to date                        │793      │
 │moby/buildkit:buildx-stable-1            │Up to date                        │600      │
 │tecnativa/docker-socket-proxy:latest     │Up to date                        │564      │
 │ubuntu:latest                            │Up to date                        │585      │
 │wagoodman/dive:latest                    │Up to date                        │585      │
 │rolebot:latest                           │Unknown                           │174      │
 ╰─────────────────────────────────────────┴──────────────────────────────────┴─────────╯
 INFO ✨ Checked 11 images in 8312ms

Check for updates to specific images


$ cup check node:latest
✓ Done!
~ Local images
 ╭───────────┬────────────────┬─────────╮
 │Reference  │Status          │Time (ms)│
 ├───────────┼────────────────┼─────────┤
 │node:latest│Update available│788      │
 ╰───────────┴────────────────┴─────────╯
 INFO ✨ Checked 1 images in 310ms


$ cup check nextcloud:30 postgres:14 mysql:8.0
✓ Done!
~ Local images
 ╭────────────┬────────────────────────┬─────────╮
 │Reference   │Status                  │Time (ms)│
 ├────────────┼────────────────────────┼─────────┤
 │postgres:14 │Major update (14 → 17)  │195      │
 │mysql:8.0   │Major update (8.0 → 9.2)│382      │
 │nextcloud:30│Up to date              │585      │
 ╰────────────┴────────────────────────┴─────────╯
 INFO ✨ Checked 3 images in 769ms

Enable icons

You can also enable icons if you have a Nerd Font installed.

JSON output

When integrating Cup with other services (e.g. webhooks or a dashboard), you may find Cup’s JSON output functionality useful.

It provides some useful metrics (see server for more information), along with a list of images and whether they have an update or not. Note that at the moment it does not match the detailed API the server provides.


$ cup check -r
{"metrics":{"monitored_images":26,"up_to_date":2,"updates_available":23,"major_updates":8,"minor_updates":6,"patch_updates":2,"other_updates":7,"unknown":1},"images":{"ghcr.io/immich-app/immich-server:v1.106.4":false,"portainer/portainer-ce:2.20.3-alpine":false,"ghcr.io/runtipi/runtipi:v3.4.1":false,...}}

⚠️

When parsing Cup’s output, capture only stdout, otherwise you might not get valid JSON (if there are warnings)

Usage with Docker

If you’re using the Docker image, just replace all occurences of cup in the examples with docker run -tv /var/run/docker.sock:/var/run/docker.sock ghcr.io/sergi0g/cup.

For example, this:


$ cup check node:latest

becomes:


$ docker run -tv /var/run/docker.sock:/var/run/docker.sock ghcr.io/sergi0g/cup check node:latest