cup/docs/pages/docs/usage/cli.mdx

import Image from "next/image";
import cup from "../../../assets/cup.gif";

# CLI

Cup's CLI provides the `cup check` command.

## Basic Usage

### Check for all updates
```ansi
$ cup check
nginx:alpine                                      Update available
redis:7                                           Update available
redis:alpine                                      Update available
...
centos:7                                                Up to date
mcr.microsoft.com/devcontainers/go:0-1.19-bullseye      Up to date
rockylinux:9-minimal                                    Up to date
rabbitmq:3.11.9-management                              Up to date
...
some/deleted:image                                         Unknown
[38:5:86mINFO  ✨ Checked 58 images in 3772ms
```

### Check for updates to specific images
```ansi
$ cup check node:latest
node:latest                                      Update available
[38:5:86mINFO  ✨ Checked 1 images in 1310ms
```

```ansi
$ cup check node:latest
nextcloud:30                                          Update available
postgres:14                                           Update available
mysql:8.0                                               Up to date
[38:5:86mINFO  ✨ Checked 3 images in 1769ms
```

## Enable icons
You can also enable icons if you have a [Nerd Font](https://nerdfonts.com) installed.

<Image src={cup} unoptimized />

## 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](/docs/usage/server) for more information), along with a list of images and whether they have an update or not.

```
$ cup check -r
{"metrics":{"update_available":4,"monitored_images":25,"unknown":1,"up_to_date":20},"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,...}}
```

Here is how it would look in Typescript:

```ts
interface CupData {
    metrics: {
        monitored_images: number,
        up_to_date: number,
        update_available: number,
        unknown: number
    },
    images: {
        [image: string]: boolean | null
    }
}
```

## 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:
```bash /check node:latest/
$ cup check node:latest
```
becomes:
```bash /check node:latest/
$ docker run -tv /var/run/docker.sock:/var/run/docker.sock ghcr.io/sergi0g/cup check node:latest
```