# CLI `tatuzim-agent`

CLI do agent que roda em cada VPS. Tipicamente operado via systemd, mas comandos pontuais sao uteis pra debug/admin.

# Sintaxe geral

tatuzim-agent <COMMAND>

# Variaveis de ambiente (comuns a todos os comandos)

# Comandos

# `tatuzim-agent enroll`

First-time enrollment contra o server.

tatuzim-agent enroll

Pre-requisitos (env):

• TATUZIM_ENROLL_TOKEN
• TATUZIM_AGENT_HOSTNAME (deve bater com o token)
• TATUZIM_AGENT_ROLE (idem)
• TATUZIM_SERVER_URL

Comportamento:

1. Se identity/agent.crt ja existe → erro identity already present
2. Gera ECDSA P-256 keypair
3. Cria CSR (CN = hostname)
4. POST /v1/enroll com token + CSR
5. Salva agent.crt (0644) + agent.key (0600) + ca.pem (0644)

Exemplo:

sudo -u tatuzim \
    TATUZIM_SERVER_URL=https://tatuzim.dev.borlot.com.br \
    TATUZIM_AGENT_HOSTNAME=vps-01 \
    TATUZIM_AGENT_ROLE=mautic \
    TATUZIM_AGENT_DATA_DIR=/var/lib/tatuzim-agent \
    TATUZIM_ENROLL_TOKEN="EXEMPLO_xxxxxxxx..." \
    /usr/local/bin/tatuzim-agent enroll

# `tatuzim-agent identity`

Mostra info do cert atual do agent. Nao faz chamadas de rede.

tatuzim-agent identity

Output:

Tatuzim Agent identity:
  hostname:    vps-01
  cert CN:     vps-01
  cert serial: 0123456789abcdef0123456789abcdef
  not_before:  May 23 22:03:09 2026 +00:00
  not_after:   May 24 22:04:09 2026 +00:00
  data_dir:    /var/lib/tatuzim-agent

Erro se identity ausente:

Error: no identity at /var/lib/tatuzim-agent/identity — run `tatuzim-agent enroll` first

# `tatuzim-agent run`

Daemon loop principal. Usado pelo systemd (ExecStart).

tatuzim-agent run

Loop:

1. Verifica validade do cert; renova se < TATUZIM_AGENT_RENEWAL_THRESHOLD
2. GET /v1/manifest via mTLS
3. Para cada entrega NAO em processed.json:
     match tipo:
       csr_cert: gera CSR + POST /v1/certs/issue + escreve out/<nome>.{crt,key}
                 + POST /v1/events entrega_instalada
                 + executa hooks/post-csr-cert
       _:        warn + skip
4. Sleep TATUZIM_AGENT_POLL_INTERVAL
5. Goto 1

No boot do loop: emite agent_started (best-effort).

Termina apenas via SIGTERM/SIGINT (no MVP, sem graceful shutdown — abort imediato).

# `tatuzim-agent rotate`

Forca renovacao do cert (ignora threshold).

tatuzim-agent rotate

Output:

INFO renewing cert old_serial=0123456789abcdef0123456789abcdef
INFO cert renewed new_serial=fedcba9876543210fedcba9876543210

Cert rotated:
  old serial: 0123456789abcdef0123456789abcdef
  new serial: fedcba9876543210fedcba9876543210

Uso tipico:

• Apos comprometimento suspeito da key atual
• Debugging do fluxo de renewal
• Apos tatuzim agente revoke no server (futuro)

# `tatuzim-agent self-update`

Baixa nova versao do binario, valida assinatura minisign, swap atomico.

tatuzim-agent self-update --url <URL> [--binary <PATH>]

Opcoes:

Comportamento:

1. GET <URL>/tatuzim-agent → binario
2. GET <URL>/tatuzim-agent.minisig → assinatura
3. Verifica com pubkey embutida no proprio binario (minisign-verify)
4. Se valido: escreve .new, chmod +x, atomic rename
5. Se invalido: aborta sem mudar nada

Exemplo:

sudo tatuzim-agent self-update --url https://get.get.tatuzim.com/v0.2.0

Pubkey embutida (compile-time): RWSeTpgYV+16Z//WwZku61OpIYgaU8iyyN/dEYm7bOGru0vFTbdLSAcD

Erro se signature invalida:

Error: signature does NOT match binary — refusing to install

# Exit codes

# Pattern de uso em systemd

A systemd unit (/etc/systemd/system/tatuzim-agent.service) roda:

ExecStart=/usr/local/bin/tatuzim-agent run
EnvironmentFile=-/etc/tatuzim-agent/env
User=tatuzim

O env file contem as variaveis necessarias. Modifique e systemctl restart tatuzim-agent pra aplicar mudancas.

# Logging

Por default RUST_LOG=info. Pra debug detalhado:

sudo systemctl stop tatuzim-agent
sudo -u tatuzim RUST_LOG=debug /usr/local/bin/tatuzim-agent run
# Ou via env:
echo "RUST_LOG=debug" | sudo tee -a /etc/tatuzim-agent/env
sudo systemctl restart tatuzim-agent
sudo journalctl -u tatuzim-agent -f

Modulos disponiveis pra filtrar:

• tatuzim_agent::commands::enroll
• tatuzim_agent::commands::run
• tatuzim_agent::processor (process_csr_cert)
• tatuzim_agent::renewal (cert renewal)
• tatuzim_agent::hooks
• tatuzim_agent::http_client
• tatuzim_agent::update