---
title: "CLI de la imagen"
description: "La imagen es un aparato listo para usar: el entrypoint notarium, los comandos start, backup, restore, admin y version, y sus códigos de salida."
---

# CLI de la imagen

La imagen ya sabe arrancarse sola: no hay que añadir ningún comando a `docker run`, porque por defecto levanta el servidor. Un argumento sustituye únicamente al comando, así que una operación puntual se lee con toda naturalidad — `docker run … IMAGE restore`.

Los comandos de operador entran en un contenedor en marcha a través de `docker exec`, con nombres cortos:

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

## Comandos

| Comando | Qué hace | Cómo se invoca normalmente |
|---|---|---|
| `start` | Arranca el servidor HTTP/MCP como PID 1 | El comando por defecto de la imagen |
| `backup` | Transmite (stream) un ZIP en caliente ya verificado | `docker exec notarium backup` más la secuencia de publicación segura del [runbook](/docs/self-hosting/backup/) |
| `backup verify` | Comprueba un archivo de copia de seguridad sin tocar nada | `docker exec -i notarium backup verify < file` |
| `restore` | Instala un archivo de copia de seguridad en una raíz de datos vacía | Un contenedor puntual sobre un volumen nuevo |
| `admin` | Recupera el acceso al margen de la interfaz | `docker exec -it notarium admin …` |
| `healthcheck` | Consulta el `/api/health` local | El `HEALTHCHECK` de Docker |
| `version` | Versión, commit, fecha y hora de compilación y enlace al código fuente (`--json` para scripts) | Soporte y comprobaciones de compatibilidad |
| `help` / `--help` | Describe la CLI o un comando concreto | Cualquier contenedor |

`start` se queda en primer plano, de modo que las señales del contenedor llegan directamente al servidor — `docker stop` lo detiene de forma limpia. No hay ningún comando para parar ni para reiniciar, y es deliberado: eso es cosa del orquestador. Las migraciones de esquema se aplican al arrancar; nunca las lanzas como comando aparte.

## Flujos y códigos de salida

- En modo streaming (sin `--output`), `backup` deja en stdout **solo** los bytes del ZIP; el diagnóstico y el resumen final van a stderr. Con `--output FILE` el archivo de copia de seguridad se escribe en ese fichero y a stdout va un único resumen JSON — no lo redirijas a un `.zip`, porque lo que acabaría ahí no es un archivo de copia de seguridad.
- `backup verify`, `restore` y los comandos `admin` no interactivos imprimen su resultado en stdout.
- Los errores van a stderr y devuelven un código distinto de cero. Los comandos desconocidos, las opciones desconocidas, las opciones repetidas y las opciones sin valor **fallan**, en lugar de ignorarse en silencio.
- El transporte canónico bajo Docker son **stdin y stdout**. Las opciones emparejadas `--output FILE` en `backup` e `--input FILE` en `verify`/`restore` existen para los escenarios en los que el contenedor ya ve el directorio. `--output` tiene además un efecto secundario muy de agradecer: el propio comando escribe en un fichero temporal, verifica el archivo y lo publica de forma atómica sin sobrescribir nada, de manera que no hay que escribir ninguna envoltura en shell.
- Todos los comandos tienen `--help`; `notarium --version` equivale a `notarium version`.

## Identidad de compilación

`version` imprime exactamente lo que estás ejecutando — el punto de partida de cualquier conversación sobre compatibilidad y de cualquier actualización:

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

`version --json` devuelve lo mismo en un único objeto — `version`, `commit`, `builtAt` y `source` (un enlace a la revisión exacta del código fuente) —, así que la comprobación de «qué hay desplegado» puede ir directamente en tu pipeline de despliegue. Lo que la compilación honestamente no tiene se devuelve como `null`: los valores nunca se inventan, y por eso puedes apoyarte en ellos. Lo mismo se ve en la interfaz — **Settings → About**.

> [!important] Las etiquetas de versión son inmutables
> Una etiqueta de versión publicada significa siempre una imagen concreta: `:0.1.0` nunca se moverá a otra compilación. Por eso, en producción fija una versión y no `:latest`. La imagen publicada se compila para `linux/amd64`; en otras arquitecturas, compila desde el código fuente.

## Comprobación de estado

`healthcheck` devuelve un código de salida cero solo cuando el endpoint local `/api/health` responde que todo está sano. Está pensado para la directiva `HEALTHCHECK` de Docker y para las sondas del orquestador: sin dependencias externas y sin necesidad de tener `curl` en el host.

## Recuperar el acceso

`admin` es el límite del operador del host. Las vías corrientes para cambiar una contraseña viven todas en la aplicación (la tuya propia, desde la interfaz; la de otra persona, con un enlace de un solo uso emitido por un administrador). La CLI está para otra cosa: **forzar** el cambio de una contraseña sin presentar la actual y crear un administrador fuera de banda. Para esas dos operaciones no hay ruta HTTP, y es deliberado — no hay nada que presentar —, así que pertenecen a quien tiene acceso al host.

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

La lista completa de comandos y qué significa cada uno: [Autenticación](/docs/self-hosting/authentication/#recuperar-el-acceso).

## Siguiente

- [Copia de seguridad y restauración](/docs/self-hosting/backup/) — el runbook detrás de `backup`, `backup verify` y `restore`.
- [Autenticación](/docs/self-hosting/authentication/) — qué sabe hacer `admin` y cuándo lo necesitas.
- [Instalación](/docs/self-hosting/install/) — arrancar la imagen y el volumen de datos.