---
title: "CLI образа"
description: "Образ — приложение-прибор: entrypoint notarium, команды start, backup, restore, admin, healthcheck и version, контракт потоков и кодов возврата."
---

# CLI образа

Образ уже знает, как себя запускать: дописывать команду в `docker run` не нужно, по умолчанию поднимается сервер. Аргумент заменяет только команду, поэтому разовая операция читается естественно — `docker run … ОБРАЗ restore`.

В работающий контейнер операторские команды зовут через `docker exec`, короткими именами:

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

## Команды

| Команда | Назначение | Как обычно вызывают |
|---|---|---|
| `start` | Запустить HTTP/MCP-сервер как PID 1 | Команда образа по умолчанию |
| `backup` | Отдать проверенный онлайн-ZIP потоком | `docker exec notarium backup` + безопасная публикация из [runbook](/docs/self-hosting/backup/) |
| `backup verify` | Проверить архив, ничего не меняя | `docker exec -i notarium backup verify < файл` |
| `restore` | Установить архив в пустой корень данных | Разовый контейнер на свежем томе |
| `admin` | Восстановление доступа мимо интерфейса | `docker exec -it notarium admin …` |
| `healthcheck` | Опросить локальный `/api/health` | Docker `HEALTHCHECK` |
| `version` | Версия, коммит, время сборки и ссылка на исходники (`--json` для скриптов) | Поддержка и проверка совместимости |
| `help` / `--help` | Описание CLI или конкретной команды | Любой контейнер |

`start` остаётся на переднем плане, и сигналы контейнера доходят до сервера напрямую — `docker stop` останавливает его штатно. Остановки и перезапуска среди команд нет намеренно: это дело оркестратора. Миграции схемы применяются при старте, отдельной командой их запускать не нужно.

## Контракт потоков и кодов возврата

- `backup` в потоковом режиме (без `--output`) отдаёт под stdout **только** байты ZIP; диагностика и итоговая сводка идут в stderr. С `--output FILE` архив пишется в файл, а в stdout уходит одна JSON-сводка — не перенаправляйте его в `.zip`, там будет не архив.
- `backup verify`, `restore` и неинтерактивные команды `admin` печатают результат в stdout.
- Ошибки идут в stderr и возвращают ненулевой код. Неизвестные команды, неизвестные опции, продублированные опции и опции без значения **падают**, а не игнорируются молча.
- Каноничный транспорт в Docker — **stdin и stdout**. Парные `--output FILE` у `backup` и `--input FILE` у `verify`/`restore` существуют для сценариев, где каталог контейнеру уже виден. У `--output` есть приятное следствие: команда сама пишет во временный файл, верифицирует архив и публикует его атомарно без перезаписи, так что shell-обвязку писать не приходится.
- У каждой команды есть `--help`; `notarium --version` эквивалентно `notarium version`.

## Идентичность сборки

`version` печатает, что именно у вас запущено, — это то, с чего начинается любой разговор о совместимости и любое обновление:

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

`version --json` отдаёт то же самое одним объектом — `version`, `commit`, `builtAt` и `source` (ссылка на точную ревизию исходников), — поэтому проверку «что развёрнуто» можно поставить прямо в деплой. Чего у сборки честно нет, будет `null`: значения не выдумываются, и на них можно опираться. То же видно в интерфейсе — **Settings → About**.

> [!important] Version-теги неизменяемы
> Опубликованный version-тег всегда означает один конкретный образ: `:0.1.0` не переедет на другую сборку. Поэтому в продакшне закрепляйтесь на версии, а не на `:latest`. Публикуемый образ собирается под `linux/amd64`; на других архитектурах собирайте из исходников.

## Проверка здоровья

`healthcheck` возвращает нулевой код, только когда локальный эндпоинт `/api/health` отвечает «здоров». Он рассчитан на директиву `HEALTHCHECK` в Docker и на пробы оркестратора — внешних зависимостей и хостового `curl` для этого не нужно.

## Восстановление доступа

`admin` — операторская граница хоста. Обычные пути смены пароля в приложении есть (свой пароль — в интерфейсе, чужой — одноразовой ссылкой от администратора). Из CLI доступно другое: **принудительно** задать пароль, не предъявляя текущий, и выпустить администратора внеполосно. Для этих двух операций HTTP-пути нет намеренно — предъявить нечего, поэтому они живут только у того, у кого есть доступ к хосту.

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

Полный список команд и их семантика — на странице [Аутентификация](/docs/self-hosting/authentication/#восстановление-доступа).

## Дальше

- [Бэкап и восстановление](/docs/self-hosting/backup/) — runbook под `backup`, `backup verify` и `restore`.
- [Аутентификация](/docs/self-hosting/authentication/) — что умеет `admin` и когда он нужен.
- [Установка](/docs/self-hosting/install/) — запуск образа и том данных.