V3

Many many many changes, honestly just read the release notes

docs/src/content/_meta.ts

@@ -0,0 +1,17 @@
+export default {
+  index: {
+    theme: {
+      sidebar: false,
+      toc: false,
+      breadcrumb: false,
+      pagination: false,
+      timestamp: false,
+      layout: "full",
+    },
+    display: "hidden",
+  },
+  docs: {
+    type: "page",
+    title: "Documentation",
+  },
+};

docs/src/content/docs/_meta.ts

@@ -0,0 +1,5 @@
+export default {
+  installation: {},
+  usage: {},
+  configuration: {},
+};

docs/src/content/docs/community-resources/docker-compose.mdx

@@ -0,0 +1,43 @@
+# Docker Compose
+
+Many users find it useful to run Cup with Docker Compose, as it enables them to have it constantly running in the background and easily control it. Cup's lightweight resource use makes it ideal for this use case.
+
+There have been requests for an official Docker Compose file, but I believe you should customize it to your needs.
+
+Here is an example of what I would use (by [@ioverho](https://github.com/ioverho)):
+
+```yaml
+services:
+  cup:
+    image: ghcr.io/sergi0g/cup:latest
+    container_name: cup # Optional
+    restart: unless-stopped
+    command: -c /config/cup.json serve
+    ports:
+      - 8000:8000
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./cup.json:/config/cup.json
+```
+
+If you don't have a config, you can use this instead:
+
+```yaml
+services:
+  cup:
+    image: ghcr.io/sergi0g/cup:latest
+    container_name: cup # Optional
+    restart: unless-stopped
+    command: serve
+    ports:
+      - 8000:8000
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+Cup can run with a non-root user, but needs to be in a docker group. Assuming user id of 1000 and `docker` group id of 999 you can add this to the `services.cup` key in the docker compose:
+```yaml
+    user: "1000:999"
+```
+
+The compose can be customized further of course, if you choose to use a different port, another config location, or would like to change something else. Have fun!

docs/src/content/docs/community-resources/homepage-widget.mdx

@@ -0,0 +1,79 @@
+import Image from "next/image";
+import widget1 from "@/app/assets/350767810-42eccc89-bdfd-426a-a113-653abe7483d8.png";
+import widget2 from "@/app/assets/358304960-e9f26767-51f7-4b5a-8b74-a5811019497b.jpeg";
+
+# Homepage Widget
+
+Some users have asked for a homepage widget.
+
+## Docker Compose with the widget configured via labels:
+
+```yaml
+services:
+  cup:
+    image: ghcr.io/sergi0g/cup
+    container_name: cup
+    command: -c /config/cup.json serve -p 8000
+    volumes:
+      - ./config/cup.json:/config/cup.json
+      - /var/run/docker.sock:/var/run/docker.sock
+    ports:
+      - 8000:8000
+    restart: unless-stopped
+    labels:
+      homepage.group: Network
+      homepage.name: Cup
+      homepage.icon: /icons/cup-with-straw.png
+      homepage.href: http://myserver:8000
+      homepage.ping: http://myserver:8000
+      homepage.description: Checks for container updates
+      homepage.widget.type: customapi
+      homepage.widget.url: http://myserver:8000/api/v3/json
+      homepage.widget.mappings[0].label: Monitoring
+      homepage.widget.mappings[0].field.metrics: monitored_images
+      homepage.widget.mappings[0].format: number
+      homepage.widget.mappings[1].label: Up to date
+      homepage.widget.mappings[1].field.metrics: up_to_date
+      homepage.widget.mappings[1].format: number
+      homepage.widget.mappings[2].label: Updates
+      homepage.widget.mappings[2].field.metrics: updates_available
+      homepage.widget.mappings[2].format: number
+```
+
+Preview:
+
+<Image src={widget1} />
+
+Credit: [@agrmohit](https://github.com/agrmohit)
+
+## Widget in Homepage's config file format:
+
+```yaml
+widget:
+  type: customapi
+  url: http://<SERVER_IP>:9000/api/v3/json
+  refreshInterval: 10000
+  method: GET
+  mappings:
+    - field:
+        metrics: monitored_images
+      label: Monitored images
+      format: number
+    - field:
+        metrics: up_to_date
+      label: Up to date
+      format: number
+    - field:
+        metrics: updates_available
+      label: Available updates
+      format: number
+    - field:
+        metrics: unknown
+      label: Unknown
+      format: number
+```
+
+Preview:
+
+<Image src={widget2} />
+Credit: [@remussamoila](https://github.com/remussamoila)

docs/src/content/docs/configuration/agent.mdx

@@ -0,0 +1,12 @@
+# Agent mode
+
+If you'd like to have only the server API exposed without the dashboard, you can run Cup in agent mode.
+
+Modify your config like this:
+
+```jsonc
+{
+    "agent": true
+    // Other options
+}
+```

docs/src/content/docs/configuration/authentication.mdx

@@ -0,0 +1,26 @@
+import { Callout } from "nextra/components";
+
+# Authentication
+
+Some registries (or specific images) may require you to be authenticated. For those, you can modify `cup.json` like this:
+
+```jsonc
+{
+  "registries": {
+    "<YOUR_REGISTRY_DOMAIN_1>": {
+      "authentication": "<YOUR_TOKEN_1>"
+      // Other options
+    },
+    "<YOUR_REGISTRY_DOMAIN_2>" {
+      "authentication": "<YOUR_TOKEN_2>"
+      // Other options
+    },
+    // ...
+  }
+  // Other options
+}
+```
+
+You can use any registry, like `ghcr.io`, `quay.io`, `gcr.io`, etc.
+
+<Callout emoji="⚠️">For Docker Hub, use `registry-1.docker.io`</Callout>

docs/src/content/docs/configuration/automatic-refresh.mdx

@@ -0,0 +1,12 @@
+# Automatic refresh
+
+Cup can automatically refresh the results when running in server mode. Simply add this to your config:
+
+```jsonc
+{
+  "refresh_interval": "0 0,30 * 0 0" // Check twice an hour
+  // Other options
+}
+```
+
+You can use a cron expression to specify the refresh interval. The reference is [here](https://github.com/Hexagon/croner-rust#pattern)

docs/src/content/docs/configuration/ignore-registry.mdx

@@ -0,0 +1,22 @@
+# Ignored registries
+
+If you want to skip checking images from some registries, you can modify your config like this:
+
+```jsonc
+{
+  "registries": {
+    "<SOME_REGISTRY_DOMAIN_1>": {
+      "ignore": true
+      // Other options
+    },
+    "<SOME_REGISTRY_DOMAIN_2>" {
+      "ignore": false
+      // Other options
+    },
+    // ...
+  }
+  // Other options
+}
+```
+
+This configuration option is a bit redundant, since you can achieve the same with [this option](/docs/configuration/include-exclude-images). It's recommended to use that.

docs/src/content/docs/configuration/include-exclude-images.mdx

@@ -0,0 +1,35 @@
+# Include/Exclude images
+
+If you want to exclude some images (e.g. because they have too many tags and take too long to check), you can add the following to your config:
+
+```jsonc
+{
+  "images": {
+    "exclude": [
+        "ghcr.io/immich-app/immich-machine-learning",
+        "postgres:15"
+    ]
+    // ...
+  }
+  // Other options
+}
+```
+
+For an image to be excluded, it must start with one of the strings you specify above. That means you could use `ghcr.io` to exclude all images from ghcr.io or `ghcr.io/sergi0g` to exclude all my images (why would you do that?).
+
+
+If you want Cup to always check some extra images that aren't available locally, you can modify your config like this:
+```jsonc
+{
+  "images": {
+    "extra": [
+        "mysql:8.0",
+        "nextcloud:30"
+    ]
+    // ...
+  }
+  // Other options
+}
+```
+
+Note that you must specify images with version tags, otherwise Cup will exit with an error!

docs/src/content/docs/configuration/index.mdx

@@ -0,0 +1,111 @@
+---
+asIndexPage: true
+---
+
+import { Steps, Callout, Cards } from "nextra/components";
+import {
+  IconPaint,
+  IconLockOpen,
+  IconKey,
+  IconPlug,
+  IconServer,
+} from "@tabler/icons-react";
+
+# Configuration
+
+## Custom docker socket
+
+Sometimes, there may be a need to specify a custom docker socket. Cup provides the `-s` option for this.
+
+For example, if using Podman, you might do
+
+```bash
+$ cup -s /run/user/1000/podman/podman.sock check
+```
+
+This option is also available in the configuration file and it's best to put it there.
+
+<Cards.Card
+  icon={<IconPlug />}
+  title="Custom Docker socket"
+  href="/docs/configuration/socket"
+/>
+
+## Configuration file
+
+Cup has an option to be configured from a configuration file named `cup.json`.
+
+<Steps>
+### Create the configuration file
+Create a `cup.json` file somewhere on your system. For binary installs, a path like `~/.config/cup.json` is recommended.
+If you're running with Docker, you can create a `cup.json` in the directory you're running Cup and mount it into the container. _In the next section you will need to use the path where you **mounted** the file_
+
+### Configure Cup from the configuration file
+
+Follow the guides below to customize your `cup.json`
+
+<Cards>
+  <Cards.Card
+    icon={<IconKey />}
+    title="Authentication"
+    href="/docs/configuration/authentication"
+  />
+  <Cards.Card
+    icon={<IconLockOpen />}
+    title="Insecure registries"
+    href="/docs/configuration/insecure-registries"
+  />
+  <Cards.Card
+    icon={<IconPaint />}
+    title="Theme"
+    href="/docs/configuration/theme"
+  />
+  <Cards.Card
+    icon={<IconServer />}
+    title="Multiple servers"
+    href="/docs/configuration/servers"
+  />
+</Cards>
+
+Here's a full example:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/sergi0g/cup/main/cup.schema.json",
+  "version": 3,
+  "images": {
+    "exclude": ["ghcr.io/immich-app/immich-machine-learning"],
+    "extra": ["ghcr.io/sergi0g/cup:v3.0.0"]
+  },
+  "registries": {
+    "myregistry.com": {
+      "authentication": "<YOUR_TOKEN_HERE>"
+    }
+  },
+  "servers": {
+    "Raspberry Pi": "https://server.local:8000"
+  },
+  "theme": "blue"
+}
+```
+
+<Callout>
+  If you want autocompletions and error checking for your editor, there is a
+  JSON schema available. Use it by adding a `"$schema":
+  "https://raw.githubusercontent.com/sergi0g/cup/main/cup.schema.json"` entry in
+  your `cup.json` file.
+</Callout>
+
+### Run Cup with the new configuration file
+
+To let Cup know that you'd like it to use a custom configuration file, you can use the `-c` flag, followed by the _absolute_ path of the file.
+
+```bash
+$ cup -c /home/sergio/.config/cup.json check
+```
+
+```bash
+$ docker run -tv /var/run/docker.sock:/var/run/docker.sock -v /home/sergio/.config/cup.json:/config/cup.json ghcr.io/sergi0g/cup -c /config/cup.json serve
+```
+
+</Steps>

docs/src/content/docs/configuration/insecure-registries.mdx

@@ -0,0 +1,32 @@
+import { Callout } from "nextra/components";
+
+# Insecure registries
+
+For the best security, Cup only connects to registries over SSL (HTTPS) by default. However, for people running a local registry that doesn't support SSL, this may be a problem.
+
+To solve this problem, you can specify exceptions in your `cup.json`.
+
+Here's what it looks like:
+
+```jsonc
+{
+  "registries": {
+    "<INSECURE_REGISTRY_1>": {
+      "insecure": true
+      // Other options
+    },
+    "<INSECURE_REGISTRY_2>" {
+      "insecure": true
+      // Other options
+    },
+    // ...
+  }
+  // Other options
+}
+```
+
+<Callout emoji="⚠️">
+  When configuring an insecure registry that doesn't run on port 80, don't
+  forget to specify the port (i.e. use `localhost:5000` instead of `localhost`
+  if your registry is running on port `5000`)
+</Callout>

docs/src/content/docs/configuration/servers.mdx

@@ -0,0 +1,15 @@
+# Multiple servers
+
+Besides checking for local image updates, you might want to be able to view update stats for all your servers running Cup in a central place. If you choose to add more servers to your Cup configuration, Cup will retrieve the current list of updates from your other servers and it will be included in the results.
+
+Just add something like this to your config:
+
+```jsonc
+{
+    "servers": {
+        "Cool server 1": "http://your-other-server-running-cup:8000",
+        "Other server": "http://and-another-one:9000"
+    }
+    // Other options
+}
+```

docs/src/content/docs/configuration/socket.mdx

@@ -0,0 +1,19 @@
+# Custom socket
+
+If you need to specify a custom Docker socket (e.g. because you're using Podman), you can use the `socket` option. Here's an example:
+
+```jsonc
+{
+  "socket": "/run/user/1000/podman/podman.sock"
+  // Other options
+}
+```
+
+You can also specify a TCP socket if you're using a remote Docker host or a [proxy](https://github.com/Tecnativa/docker-socket-proxy):
+
+```jsonc
+{
+  "socket": "tcp://localhost:2375"
+  // Other options
+}
+```

docs/src/content/docs/configuration/theme.mdx

@@ -0,0 +1,31 @@
+import { Callout } from "nextra/components";
+import Image from "next/image";
+
+import blue from "@/app/assets/blue_theme.png";
+import neutral from "@/app/assets/hero-dark.png";
+
+# Theme
+
+<Callout emoji="⚠️">This configuration option is only for the server</Callout>
+
+Cup initially had a blue theme which looked like this:
+
+<Image alt="Screenshot of blue theme" src={blue} />
+
+This was replaced by a more neutral theme which is now the default:
+
+<Image alt="Screenshot of neutral theme" src={neutral} />
+
+However, you can get the old theme back by adding the `theme` key to your `cup.json`
+Available options are `default` and `blue`.
+
+Here's an example:
+
+```jsonc
+{
+  "theme": "blue"
+  // Other options
+}
+```
+
+Note that the difference between the 2 themes is almost impossible to perceive when your system is in light mode.

docs/src/content/docs/contributing.mdx

@@ -0,0 +1,71 @@
+import { Steps } from "nextra/components";
+
+# Contributing
+
+First of all, thanks for taking time to contribute to Cup! This guide will help you set up a development environment and make your first contribution.
+
+## Setting up a development environment
+
+Requirements:
+
+- A computer running Linux
+- Rust (usually installed from https://rustup.rs/)
+- Node.js 22+ and Bun 1+
+
+<Steps>
+### Fork the repository
+This is where you'll be pushing your changes before you create a pull request. Make sure to _create a new branch_ for your changes.
+### Clone your fork
+```bash
+git clone https://github.com/<YOUR_USERNAME>/cup
+```
+If you use SSH:
+```bash
+git clone git@github.com:<YOUR_USERNAME>/cup`)
+```
+### Switch to your newly created branch (e.g. if your branch is called `improve-logging`, run `git checkout improve-logging`)
+### Set up the frontend
+```bash
+$ cd web
+$ bun install
+$ cd ..
+$ ./build.sh
+```
+</Steps>
+
+You're ready to go!
+
+## Project architecture
+
+Cup can be run in 2 modes: CLI and server.
+
+All CLI specific functionality is located in `src/formatting.rs` and some other files in functions prefixed with `#[cfg(feature = "cli")]`.
+
+All server specific functionality is located in `src/server.rs` and `web/`.
+
+## Important notes
+
+- When making any changes, always make sure to write optimize your code for:
+
+  - Performance: You should always benchmark Cup before making changes and after your changes to make sure there is none (or a very small) difference in time. Profiling old and new code is also good.
+  - Readability: Include comments describing any new functions you create, give descriptive names to variables and when making a design decision or a compromise, ALWAYS include a comment explaining what you did and why.
+
+- If you plan on developing the frontend without making backend changes, it is highly recommended to run `cup serve` in the background and start the frontend in development mode from `web/` with `bun dev`.
+
+- If you make changes to the frontend, always remember to prefix your build command with the `build.sh` script which takes care of rebuilding the frontend. For example: `./build.sh cargo build -r`
+
+- When adding new features to Cup (e.g. configuration options), make sure to update the documentation (located in `docs/`). Refer to other pages in the documentation, or to the [official docs](https://nextra.site) for any questions you may have. The docs use `pnpm` as their package manager.
+
+- If you need help with finishing something (e.g. you've made some commits and need help with writing docs, you want some feedback about a design decision, etc.), you can open a draft PR and ask for help there.
+
+## Submitting a PR
+
+To have your changes included in Cup, you will need to create a pull request.
+
+Before doing so, please make sure you have run `cargo clippy` and resolved all warnings related to your changes and have formatted your code with `cargo fmt`. This ensures Cup's codebase is consistent and uses good practices for code.
+
+After you're done with that, commit your changes and push them to your branch.
+
+Next, open your fork on Github and create a pull request. Make sure to include the changes you made, which issues it addresses (if any) and any other info you think is important.
+
+Happy contributing!

docs/src/content/docs/index.mdx

@@ -0,0 +1,34 @@
+import Image from "next/image";
+import cup from "@/app/assets/cup.gif";
+import { Cards } from "nextra/components";
+import { IconBrandDocker, IconPackage } from "@tabler/icons-react";
+
+# Introduction
+
+<Image src={cup} alt="Animated GIF of Cup's CLI in action" unoptimized />
+
+Cup is a lightweight alternative to [What's up Docker?](https://github.com/getwud/wud) written in Rust.
+
+# Features ✨
+
+- 🚀 Extremely fast. Cup takes full advantage of your CPU and is hightly optimized, resulting in lightning fast speed. On my Raspberry Pi 5, it took 3.7 seconds for 58 images!
+- Supports most registries, including Docker Hub, ghcr.io, Quay, lscr.io and even Gitea (or derivatives)
+- Doesn't exhaust any rate limits. This is the original reason I created Cup. It was inspired by [What's up docker?](https://github.com/getwud/wud) which would always use it up.
+- Beautiful CLI and web interface for checking on your containers any time.
+- The binary is tiny! At the time of writing it's just 5.4 MB. No more pulling 100+ MB docker images for a such a simple program.
+- JSON output for both the CLI and web interface so you can connect Cup to integrations. It's easy to parse and makes webhooks and pretty dashboards simple to set up!
+
+# Installation
+
+<Cards>
+  <Cards.Card
+    icon={<IconBrandDocker />}
+    title="With Docker"
+    href="/docs/installation/docker"
+  />
+  <Cards.Card
+    icon={<IconPackage />}
+    title="As a binary"
+    href="/docs/installation/binary"
+  />
+</Cards>

docs/src/content/docs/installation/_meta.ts

@@ -0,0 +1,8 @@
+export default {
+  docker: {
+    title: "With Docker",
+  },
+  binary: {
+    title: "As a binary",
+  },
+};

docs/src/content/docs/installation/binary.mdx

@@ -0,0 +1,28 @@
+import { Callout, Cards, Steps } from "nextra/components";
+import { IconFileDescription } from "@tabler/icons-react";
+
+# As a binary
+
+## Introduction
+
+This guide will help you install Cup from a binary.
+
+## Installation
+
+<Steps>
+### Download binary
+Go to https://github.com/sergi0g/cup/releases/latest.
+
+Depending on your system's architecture, choose the binary for your system. For example, for an `x86_64` machine, you should download `cup-x86_64-unknown-linux-musl`
+
+<Callout>
+You can use the command `uname -i` to find this
+</Callout>
+### Add binary to path
+Move the binary you downloaded to a directory in your path. You can usually get a list those directories by running `echo $PATH`. On most Linux systems, moving it to `~/.local/bin` is usually enough.
+</Steps>
+
+That's it! Cup is ready to be used. Head over to the Usage page to get started.
+
+<br />
+<Cards.Card icon={<IconFileDescription />} title="Usage" href="/docs/usage" />

docs/src/content/docs/installation/docker.mdx

@@ -0,0 +1,27 @@
+import { Callout, Cards } from "nextra/components";
+import { IconFileDescription } from "@tabler/icons-react";
+
+# With Docker
+
+## Introduction
+
+This guide will help you install Cup as a Docker container. It is the easiest installation method and also makes updating Cup very easy.
+
+## Installation
+
+To get started, open up a terminal and run the following command.
+
+```bash
+$ docker pull ghcr.io/sergi0g/cup
+```
+
+<Callout emoji="⚠️">
+  If you aren't a member of the `docker` group, please ensure you run all
+  commands as a user who is. In most cases, you'll just need to prefix the
+  `docker` commands with `sudo`
+</Callout>
+
+That's it! Cup is ready to be used. Head over to the Usage page to get started.
+
+<br />
+<Cards.Card icon={<IconFileDescription />} title="Usage" href="/docs/usage" />

docs/src/content/docs/integrations.mdx

@@ -0,0 +1,79 @@
+import { Callout, Cards } from "nextra/components";
+import { IconServer, IconTerminal } from "@tabler/icons-react"
+
+# Integrations
+
+At the moment, Cup has no built-in integrations, but it provides an API for the server and JSON output for the CLI, which can enable you to connect Cup to your own integrations.
+
+## JSON data
+
+The data returned from the API or from the CLI is in JSON and looks like this:
+
+```jsonc
+{
+    // Statistics useful for displaying on dashboards.
+    // You could calculate these yourself based on the rest of the data,
+    // but they're provided for easier integration with other systems.
+    "metrics": {
+        "monitored_images": 5,
+        "up_to_date": 2,
+        "updates_available": 3,
+        "major_updates": 1,
+        "minor_updates": 0,
+        "patch_updates": 0,
+        "other_updates": 2,
+        "unknown": 0,
+    },
+    // A list of image objects with all related information.
+    "images": [
+        {
+            "reference": "ghcr.io/sergi0g/cup:latest",
+            "parts": {
+                // The information Cup extracted about the image from the reference. Mostly useful for debugging and the way the web interface works.
+                "registry": "ghcr.io",
+                "repository": "sergi0g/cup",
+                "tag": "latest",
+            },
+            "result": {
+                "has_update": true, // `true` when an image has an update of any kind, `false` when up to date and `null` when unknown.
+                "info": {
+                    // `null` if up to date
+                    "type": "digest", // Can also be `version` when Cup detects the tag contains a version.
+                    // If `type` is "digest":
+                    "local_digests": [
+                        // A list of local digests present for the image
+                        "sha256:b7168e5f6828cbbd3622fa19965007e4611cf42b5f3c603008377ffd45a4fe00",
+                    ],
+                    "remote_digest": "sha256:170f1974d8fc8ca245bcfae5590bc326de347b19719972bf122400fb13dfa42c", // Latest digest available in the registry
+                    // If `type` is "version":
+                    "version_update_type": "major", // Loosely corresponds to SemVer versioning. Can also be `minor` or `patch`.
+                    "new_tag": "v3.3.3", // The tag of the latest image.
+                },
+                "error": null, // If checking for the image fails, will be a string with an error message.
+            },
+            "time": 869, // Time in milliseconds it took to check for the update. Useful for debugging.
+            "server": "Lithium", // The name of the server which the image was checked for updates on. `null` if from the current machine.
+        },
+    ],
+}
+```
+
+<Callout emoji="⚠️">
+    Please keep in mind that the above may not always be up to date. New fields
+    may be added, or some types extended. If you notice that, just open an issue
+    and they'll be updated. Changes to the JSON data schema will _always_ happen
+    in a backwards-compatible way. In case backwards-incompatible changes are
+    made, these docs will be updated. For something more up-to-date, you can
+    take a look at https://github.com/sergi0g/cup/blob/main/web/src/types.ts
+</Callout>
+
+For retrieving the above data, refer to the CLI and server pages:
+
+<Cards>
+    <Cards.Card icon={<IconTerminal />} title="CLI" href="/docs/usage/cli" />
+    <Cards.Card
+        icon={<IconServer />}
+        title="Server"
+        href="/docs/usage/server"
+    />
+</Cards>

docs/src/content/docs/nightly.mdx

@@ -0,0 +1,25 @@
+import { Callout } from "nextra/components";
+
+# Using the latest version
+
+The installation instructions you previously followed describe how to install Cup's stable version.
+
+However, it is only updated when a new release is created, so if you want the latest features, you'll need to install Cup's nightly version.
+
+Cup's nightly version always contains the latest changes in the main branch.
+
+<Callout emoji="⚠️">
+  There is no guarantee that the nightly version will always work. There may be
+  breaking changes or a bad commit and it may not work properly. Install nightly
+  only if you know what you are doing. These instructions will assume you have
+  the technical know-how to follow them. If you do not, please use the stable
+  release!
+</Callout>
+
+## With Docker
+
+Instead of `ghcr.io/sergi0g/cup`, use `ghcr.io/sergi0g/cup:nightly`
+
+## As a binary
+
+Go to a [nightly workflow run](https://github.com/sergi0g/cup/actions/workflows/nightly.yml) and download the artifact for your system.

docs/src/content/docs/usage/cli.mdx

@@ -0,0 +1,99 @@
+import Image from "next/image";
+import cup from "@/app/assets/cup.gif";
+import { Callout } from "nextra/components";
+
+# CLI
+
+Cup's CLI provides the `cup check` command.
+
+## Basic Usage
+
+### Check for all updates
+
+```ansi
+$ 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
+
+```ansi
+$ cup check node:latest
+✓ Done!
+~ Local images
+ ╭───────────┬────────────────┬─────────╮
+ │Reference  │Status          │Time (ms)│
+ ├───────────┼────────────────┼─────────┤
+ │node:latest│Update available│788      │
+ ╰───────────┴────────────────┴─────────╯
+ INFO ✨ Checked 1 images in 310ms
+```
+
+```ansi
+$ 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](https://nerdfonts.com) installed.
+
+<Image src={cup} alt="GIF of Cup's CLI" 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. 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,...}}
+```
+
+<Callout emoji="⚠️">
+  When parsing Cup's output, capture only `stdout`, otherwise you might not get
+  valid JSON (if there are warnings)
+</Callout>
+
+## 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
+$ cup check node:latest
+```
+
+becomes:
+
+```bash
+$ docker run -tv /var/run/docker.sock:/var/run/docker.sock ghcr.io/sergi0g/cup check node:latest
+```

docs/src/content/docs/usage/index.mdx

@@ -0,0 +1,15 @@
+---
+asIndexPage: true
+---
+
+import { IconServer, IconTerminal } from "@tabler/icons-react";
+import { Cards } from "nextra/components";
+
+# Usage
+
+You can use Cup in 2 different ways. As a CLI or as a server. You can learn more about each mode on its corresponding page
+
+<Cards>
+  <Cards.Card icon={<IconTerminal />} title="CLI" href="/docs/usage/cli" />
+  <Cards.Card icon={<IconServer />} title="Server" href="/docs/usage/server" />
+</Cards>

docs/src/content/docs/usage/server.mdx

@@ -0,0 +1,55 @@
+import { Callout } from "nextra/components";
+
+# Server
+
+The server provides the `cup serve` command.
+
+## Basic usage
+
+```ansi
+$ cup serve
+ INFO Starting server, please wait...
+ INFO ✨ Checked 8 images in 8862ms
+ INFO Ready to start!
+ HTTP GET / 200 in 0ms
+ HTTP GET /assets/index.js 200 in 3ms
+ HTTP GET /assets/index.css 200 in 0ms
+ HTTP GET /api/v3/json 200 in 0ms
+```
+
+This will launch the server on port `8000`. To access it, visit `http://<YOUR_IP>:8000` (replace `<YOUR_IP>` with the IP address of the machine running Cup.)
+
+<Callout>
+The URL `http://<YOUR_IP>:8000/api/v3/json` is also available for usage with integrations.
+</Callout>
+
+## Use a different port
+
+Pass the `-p` argument with the port you want to use
+
+```ansi
+$ cup serve -p 9000
+ INFO Starting server, please wait...
+ INFO ✨ Checked 8 images in 8862ms
+ INFO Ready to start!
+ HTTP GET / 200 in 0ms
+ HTTP GET /assets/index.js 200 in 3ms
+ HTTP GET /assets/index.css 200 in 0ms
+ HTTP GET /api/v3/json 200 in 0ms
+```
+
+## 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 -p <PORT>:<PORT> ghcr.io/sergi0g/cup`, where `<PORT>` is the port Cup will be using.
+
+For example, this:
+
+```bash
+$ cup serve -p 9000
+```
+
+becomes:
+
+```bash
+$ docker run -tv /var/run/docker.sock:/var/run/docker.sock -p 9000:9000 ghcr.io/sergi0g/cup serve -p 9000
+```