---
title: "CLI da imagem"
description: "A imagem é um appliance: o entrypoint notarium, os comandos start, backup, restore, admin e version, e o contrato de códigos de saída."
---

# CLI da imagem

A imagem já sabe como se iniciar: não é preciso acrescentar comando nenhum ao `docker run` — por padrão ela sobe o servidor. Um argumento substitui apenas o comando, e por isso uma operação pontual se lê com naturalidade — `docker run … IMAGE restore`.

Num contêiner em execução, os comandos de operador são chamados via `docker exec`, com nomes curtos:

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

## Comandos

| Comando | O que faz | Como costuma ser chamado |
|---|---|---|
| `start` | Sobe o servidor HTTP/MCP como PID 1 | O comando padrão da imagem |
| `backup` | Entrega em stream um ZIP online já verificado | `docker exec notarium backup` mais a sequência de publicação segura do [runbook](/docs/self-hosting/backup/) |
| `backup verify` | Verifica um arquivo de backup sem alterar nada | `docker exec -i notarium backup verify < arquivo` |
| `restore` | Instala um arquivo de backup numa raiz de dados vazia | Um contêiner pontual sobre um volume novo |
| `admin` | Recupera o acesso por fora da interface | `docker exec -it notarium admin …` |
| `healthcheck` | Consulta o `/api/health` local | O `HEALTHCHECK` do Docker |
| `version` | Versão, commit, hora do build e link para o código-fonte (`--json` para scripts) | Suporte e checagem de compatibilidade |
| `help` / `--help` | Descreve a CLI ou um comando específico | Qualquer contêiner |

O `start` fica em primeiro plano, então os sinais do contêiner chegam direto ao servidor — o `docker stop` o encerra de forma limpa. Não há comando de parada nem de reinício, e isso é deliberado: essa é tarefa do orquestrador. As migrações de esquema são aplicadas na inicialização; você nunca precisa rodá-las como um comando à parte.

## Streams e códigos de saída

- No modo de stream (sem `--output`), o `backup` coloca no stdout **apenas** os bytes do ZIP; diagnósticos e o resumo final vão para o stderr. Com `--output FILE`, o arquivo de backup é gravado nesse caminho e o stdout recebe um único resumo em JSON — não redirecione esse stdout para um `.zip`, o que cair lá não é um arquivo de backup.
- `backup verify`, `restore` e os comandos `admin` não interativos imprimem o resultado no stdout.
- Erros vão para o stderr e devolvem código diferente de zero. Comandos desconhecidos, opções desconhecidas, opções repetidas e opções sem valor **falham**, em vez de serem ignorados em silêncio.
- O transporte canônico no Docker é **stdin e stdout**. O par `--output FILE` no `backup` e `--input FILE` no `verify`/`restore` existe para cenários em que o contêiner já enxerga o diretório. O `--output` traz um efeito colateral bem-vindo: o próprio comando grava num arquivo temporário, verifica o backup e o publica de forma atômica, sem sobrescrever nada — assim você não precisa escrever nenhum wrapper de shell.
- Todo comando tem `--help`; `notarium --version` equivale a `notarium version`.

## Identidade do build

O `version` imprime exatamente o que você está rodando — é daí que parte qualquer conversa sobre compatibilidade e qualquer atualização:

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

O `version --json` devolve a mesma coisa num único objeto — `version`, `commit`, `builtAt` e `source` (o link para a revisão exata do código-fonte) —, então a checagem de "o que está implantado" pode entrar direto no seu pipeline de deploy. O que o build honestamente não tem volta como `null`: valores nunca são inventados, e por isso dá para confiar neles. A mesma informação aparece na interface — **Settings → About**.

> [!important] As tags de versão são imutáveis
> Uma tag de versão publicada sempre significa uma imagem específica: a `:0.1.0` nunca vai migrar para outro build. Em produção, fixe uma versão específica em vez de `:latest`. A imagem publicada é construída para `linux/amd64`; em outras arquiteturas, construa a partir do código-fonte.

## Health checks (verificação de integridade)

O `healthcheck` só devolve código de saída zero quando o endpoint local `/api/health` responde que está saudável. Ele foi feito para a diretiva `HEALTHCHECK` do Docker e para as sondas do orquestrador — sem dependências externas e sem precisar de `curl` no host.

## Recuperando o acesso

O `admin` é o limite de operador do host. Os caminhos comuns para trocar uma senha estão todos no aplicativo (a sua própria senha, pela interface; a de outra pessoa, por um link de uso único emitido por um administrador). A CLI serve para outra coisa: **forçar** uma senha sem apresentar a atual e emitir um administrador fora de banda. Para essas duas operações não existe caminho HTTP, e isso é deliberado — não há o que apresentar —, então elas ficam com quem tem acesso ao host.

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

A lista completa dos comandos e o significado de cada um estão em [Autenticação](/docs/self-hosting/authentication/#recuperando-o-acesso).

## A seguir

- [Backup e restauração](/docs/self-hosting/backup/) — o runbook por trás de `backup`, `backup verify` e `restore`.
- [Autenticação](/docs/self-hosting/authentication/) — o que o `admin` faz e quando você precisa dele.
- [Instalação](/docs/self-hosting/install/) — executar a imagem e o volume de dados.