---
title: "Image-CLI"
description: "Das Image ist eine Appliance: der Entrypoint notarium, die Befehle start, backup, restore, admin, healthcheck, version und der Kontrakt für Exit-Codes."
---

# Image-CLI

Das Image weiß bereits, wie es sich selbst startet: An `docker run` muss kein Befehl angehängt werden, standardmäßig fährt der Server hoch. Ein Argument ersetzt lediglich den Befehl, deshalb liest sich eine einmalige Operation ganz natürlich — `docker run … IMAGE restore`.

In einen laufenden Container gelangen Betreiberbefehle über `docker exec`, unter kurzen Namen:

```bash
docker exec notarium backup
docker exec -it notarium admin list
```

## Befehle

| Befehl | Zweck | Typischer Aufruf |
|---|---|---|
| `start` | Startet den HTTP/MCP-Server als PID 1 | Der Standardbefehl des Images |
| `backup` | Gibt ein verifiziertes Online-ZIP als Stream aus | `docker exec notarium backup` plus die sichere Veröffentlichung aus dem [Runbook](/docs/self-hosting/backup/) |
| `backup verify` | Prüft ein Archiv, ohne etwas zu verändern | `docker exec -i notarium backup verify < Datei` |
| `restore` | Spielt ein Archiv in ein leeres Datenverzeichnis ein | Ein einmaliger Container auf einem frischen Volume |
| `admin` | Stellt den Zugriff an der Oberfläche vorbei wieder her | `docker exec -it notarium admin …` |
| `healthcheck` | Fragt das lokale `/api/health` ab | Docker-`HEALTHCHECK` |
| `version` | Version, Commit, Build-Zeitpunkt und ein Link zu den Quellen (`--json` für Skripte) | Support und Kompatibilitätsprüfung |
| `help` / `--help` | Beschreibt die CLI oder einen einzelnen Befehl | Jeder Container |

`start` bleibt im Vordergrund, sodass die Signale des Containers den Server direkt erreichen — `docker stop` fährt ihn sauber herunter. Einen Befehl zum Stoppen oder Neustarten gibt es bewusst nicht: Das ist Sache des Orchestrators. Schema-Migrationen werden beim Start angewendet; du führst sie nie mit einem separaten Befehl aus.

## Streams und Exit-Codes

- Im Streaming-Modus (ohne `--output`) schreibt `backup` **ausschließlich** ZIP-Bytes nach stdout; Diagnose und die abschließende Zusammenfassung gehen nach stderr. Mit `--output FILE` landet das Archiv in dieser Datei, und nach stdout geht eine einzelne JSON-Zusammenfassung; leite sie nicht in eine `.zip` um — was dort landet, ist kein Archiv.
- `backup verify`, `restore` und die nicht-interaktiven `admin`-Befehle geben ihr Ergebnis auf stdout aus.
- Fehler gehen nach stderr und liefern einen Exit-Code ungleich null. Unbekannte Befehle, unbekannte Optionen, doppelt angegebene Optionen und Optionen ohne Wert **scheitern**, statt stillschweigend ignoriert zu werden.
- Der kanonische Transportweg unter Docker sind **stdin und stdout**. Das Gespann `--output FILE` bei `backup` und `--input FILE` bei `verify`/`restore` gibt es für Setups, in denen der Container das Verzeichnis ohnehin schon sieht. `--output` hat einen angenehmen Nebeneffekt: Der Befehl schreibt selbst in eine temporäre Datei, verifiziert das Archiv und veröffentlicht es atomar, ohne etwas zu überschreiben — einen Shell-Wrapper muss also niemand schreiben.
- Jeder Befehl hat sein `--help`; `notarium --version` ist gleichbedeutend mit `notarium version`.

## Build-Identität

`version` gibt aus, was genau bei dir läuft — damit beginnt jedes Gespräch über Kompatibilität und jedes Upgrade:

```bash
docker run --rm docouno/notarium:latest version
docker compose exec notarium version --json
```

`version --json` liefert dasselbe als ein einziges Objekt — `version`, `commit`, `builtAt` und `source` (ein Link auf die exakte Quell-Revision) —, sodass die Prüfung „Was ist eigentlich ausgerollt?“ direkt in die Deploy-Pipeline wandern kann. Was der Build ehrlicherweise nicht hat, kommt als `null` zurück: Werte werden nie erfunden, du kannst dich also darauf verlassen. Dasselbe steht in der Oberfläche — **Settings → About**.

> [!important] Versions-Tags sind unveränderlich
> Ein veröffentlichter Versions-Tag steht immer für genau ein Image: `:0.1.0` wandert nie auf einen anderen Build. Lege dich in der Produktion deshalb auf eine Version fest und nicht auf `:latest`. Das veröffentlichte Image wird für `linux/amd64` gebaut; auf anderen Architekturen baust du aus den Quellen.

## Health-Checks

`healthcheck` liefert nur dann den Exit-Code null, wenn der lokale Endpunkt `/api/health` „gesund“ meldet. Er ist auf die `HEALTHCHECK`-Direktive in Docker und auf die Probes des Orchestrators zugeschnitten — externe Abhängigkeiten oder ein `curl` auf dem Host braucht es dafür nicht.

## Zugriff wiederherstellen

`admin` ist die Betreibergrenze des Hosts. Die gewöhnlichen Wege, ein Passwort zu ändern, liegen alle in der Anwendung (das eigene Passwort in der Oberfläche, ein fremdes über einen Einmal-Link vom Administrator). Die CLI ist für etwas anderes da: ein Passwort **erzwingen**, ohne das aktuelle vorzuzeigen, und einen Administrator außerhalb des regulären Wegs anlegen. Für diese beiden Operationen gibt es bewusst keinen HTTP-Weg — es ist ja nichts vorzuzeigen —, deshalb bleiben sie dem vorbehalten, der Zugriff auf den Host hat.

```bash
docker compose exec notarium admin list
docker compose exec notarium admin create-admin <user> --random
```

Die vollständige Liste der Befehle und ihre Bedeutung — auf der Seite [Authentifizierung](/docs/self-hosting/authentication/#zugriff-wiederherstellen).

## Weiter

- [Backup und Wiederherstellung](/docs/self-hosting/backup/) — das Runbook hinter `backup`, `backup verify` und `restore`.
- [Authentifizierung](/docs/self-hosting/authentication/) — was `admin` kann und wann du ihn brauchst.
- [Installation](/docs/self-hosting/install/) — das Image starten und das Daten-Volume einrichten.