# CLI `tatuzim`

CLI administrativo do server. Opera diretamente no vault (file lock exclusivo — server precisa estar parado).

# Sintaxe geral

tatuzim <COMMAND> [OPTIONS]

# Variaveis de ambiente comuns

# Comandos

# `tatuzim init`

Inicializa um novo vault criptografado.

tatuzim init --root <DIR> [--passphrase <PASS>]

Opcoes:

Exit codes:

• 0 — sucesso
• 1 — erro (root ja existe, passphrase vazia, etc.)

Exemplo:

TATUZIM_MASTER_PASSPHRASE=minha-senha tatuzim init --root /var/lib/tatuzim

O que faz:

1. Gera salt aleatorio (32 bytes)
2. Argon2id deriva KEK da passphrase
3. Gera DEK random
4. Cifra DEK com KEK → wrapped_dek
5. Salva config.json (salt, kdf_params, wrapped_dek_b64)
6. Inicializa Stoolap em db.plain/, aplica schema_v1
7. Cifra db.plain → db.enc
8. Remove db.plain

# `tatuzim unseal`

Valida que vault abre com a passphrase + schema integro.

tatuzim unseal --root <DIR>

Opcoes: igual init.

Exemplo:

tatuzim unseal --root /var/lib/tatuzim
# Esperado: "Vault unsealed and verified at /var/lib/tatuzim"

Uso tipico: validacao apos restore de backup.

# `tatuzim token create`

Gera um enrollment token one-time.

tatuzim token create [OPTIONS] --hostname <H> --role <R>

Opcoes:

Exit codes:

• 0 — token criado
• 1 — erro

Exemplo:

tatuzim token create --hostname vps-mautic-01 --role mautic --ttl 1h

Output:

Enrollment token created:
  ID:       00000000-0000-4000-8000-000000000002
  Hostname: vps-mautic-01
  Role:     mautic
  Expires:  2026-05-23T23:02:22+00:00

Token (single-use, save it now — won't be shown again):

    EXEMPLO_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Importante: token plaintext mostrado apenas 1x. Apos isso, so o SHA256 vive no vault.

# `tatuzim agente list`

Lista agents registrados.

tatuzim agente list --root <DIR>

Output:

ID                                     HOSTNAME                ROLE         ENROLLED_AT
00000000-0000-4000-8000-000000000001   vps-mautic-01           mautic       2026-05-23T22:14:38+00:00
3a8c7f12-...                           vps-traefik-02          edge         2026-05-23T20:11:22+00:00

Sem agents:

No agents enrolled.

# `tatuzim carga create`

Registra uma carga + atribui a um agent como entrega pendente.

tatuzim carga create [OPTIONS] --nome <N> --destino <HOST>

Opcoes:

Exemplo:

tatuzim carga create --tipo csr_cert --nome traefik-cert --destino vps-mautic-01

Output:

Carga registrada:
  carga_id:     00000000-0000-...
  entrega_id:   00000000-0000-...
  destinatario: vps-mautic-01 (00000000-0000-...)

# `tatuzim evento list`

Lista eventos do audit log (com opcao de verificar a hash chain).

tatuzim evento list [OPTIONS]

Opcoes:

Exemplo:

tatuzim evento list --agente vps-mautic-01 --verify --limit 20

Output:

Hash chain: VALID

OCORRIDO_EM                          TIPO                  EVENTO_ID                              HASH_PRFX
2026-05-23T22:30:15.123456789+00:00  entrega_instalada     00000000-0000-4000-8000-000000000003  0000000000000000
2026-05-23T22:29:46.179498265+00:00  cert_renewed          00000000-0000-4000-8000-000000000004  1111111111111111
2026-05-23T22:29:30.456789012+00:00  agent_started         a1b2c3d4-...                          2222222222222222

Hash chain: cada evento contem hash_atual = SHA256(hash_anterior || payload || timestamp). Adulteracao detectavel via --verify (recomputa toda a chain e compara).

Se houver adulteracao:

Hash chain: BROKEN

# Pattern de uso (com server rodando)

Como o vault tem lock exclusivo (flock), pra usar o CLI voce precisa parar o server:

# Stop
docker stop dev_tatuzim_server

# Operate
tatuzim agente list --root /var/lib/tatuzim
tatuzim token create --hostname X --role Y

# Start
docker start dev_tatuzim_server

Erro se tentar com server up:

Error: configuration error: vault already locked (...): Resource temporarily unavailable — another process is using the vault

# Em containers

Quando o vault esta num volume Docker:

docker run --rm --entrypoint /usr/local/bin/tatuzim \
    -v tatuzim_tatuzim_vault:/var/lib/tatuzim \
    -e TATUZIM_MASTER_PASSPHRASE=SUA-SENHA \
    tatuzim-server:dev \
    agente list --root /var/lib/tatuzim

--entrypoint /usr/local/bin/tatuzim substitui o entrypoint default (que e o tatuzim-server), permitindo rodar o CLI.

# Roadmap