Referência da CLI do Anotae¶

Diátaxis: reference. Para tutorial passo-a-passo, veja docs/tutorials/. Para receitas práticas, veja docs/how-to/.

A CLI do Anotae expõe operações administrativas que não acessam o conteúdo do vault — apenas registram extensões de navegador, criam snapshots cifrados e verificam integridade. Sua senha-mestra nunca é solicitada pela CLI.

Convocação geral¶

anotae [-h] [-V] [comando] [...]

Forma	Comportamento
`anotae` (sem args)	Inicia a interface gráfica (PySide6).
`anotae -V` ou `anotae --version`	Imprime versão e sai.
`anotae version`	Idem (alias para discoverability).
`anotae <comando>`	Executa subcomando administrativo.

Exit codes¶

Código	Significado
`0`	Sucesso.
`1`	Erro de operação (vault inexistente, falha de NMH, hash inválido…).
`2`	Erro de argumento (capturado pelo argparse, ou subcomando hierárquico sem ação).

Subcomandos¶

`install-extension`¶

Registra o canal Native Messaging Host (NMH) entre o Anotae e o navegador escolhido. Não baixa nem instala a extensão em si — apenas cria o manifesto que permite à extensão se comunicar com o app.

anotae install-extension --browser {chrome,edge,firefox,chromium}
                         [--exe-path PATH]

Argumento	Descrição
`--browser` (obrigatório)	Navegador alvo.
`--exe-path`	Caminho do executável do Anotae chamado pelo navegador. Default: `sys.executable` (útil em desenvolvimento).

Após executar, a CLI imprime o passo-a-passo para carregar a pasta extension/dist/<browser>/ no navegador (modo desenvolvedor).

`uninstall-extension`¶

Remove o manifesto NMH do navegador escolhido. Operação idempotente: sai com código 0 mesmo se nenhum manifesto for encontrado.

anotae uninstall-extension --browser {chrome,edge,firefox,chromium}

`extension-info`¶

Imprime o ID determinístico da extensão (Chrome/Edge/Chromium) e os caminhos de manifesto NMH para cada família de navegador. Útil para confirmar que o ID que aparece em chrome://extensions/ bate com o que o NMH espera.

anotae extension-info

`version`¶

Imprime Anotae vX.Y.Z. Idêntico a anotae --version.

anotae version

`backup create <vault>`¶

Cria um snapshot do vault apontado em <vault-dir>/backups/vault_<timestamp>.db com hash SHA-256 adjacente. Não descifra o vault — copia o arquivo cifrado.

anotae backup create /caminho/para/vault.db [--extra-dir DIR | --as-zip]

Flag	Descrição
`--extra-dir DIR`	Pasta extra opcional para receber cópia adicional do snapshot (pen drive, pasta sincronizada). O arquivo continua cifrado. Falhas aqui não invalidam o backup principal.
`--as-zip`	Produz `anotae-vault-<ts>.zip` portável com `vault.db` cifrado + `vault.db.sha256` + `metadata.json` (versão, timestamp, hash). Útil para anexar a e-mail ou postar em issue — vault interno permanece cifrado.

Saída:

[OK] Snapshot criado.
  Arquivo:   /caminho/para/backups/vault_20260507_143022_123456.db
  Tamanho:   16384 bytes
  SHA-256:   3a2f...

`backup list <vault>`¶

Lista backups existentes do vault apontado, mais recentes primeiro.

anotae backup list /caminho/para/vault.db

Saída (1 linha por backup):

Backups de vault.db (3 encontrados):
  2026-05-07T14:30:22  16384 B  3a2f1c8d4b9a7e62…  vault_20260507_143022_123456.db
  2026-05-06T09:11:45  16384 B  9b8a7c6d5e4f3a21…  vault_20260506_091145_654321.db
  ...

`backup verify <vault> <name>`¶

Verifica integridade SHA-256 do backup nomeado. Exit 0 se íntegro; 1 caso contrário.

anotae backup verify /caminho/para/vault.db vault_20260507_143022_123456.db

`telemetry status / list / clear`¶

Gerencia a telemetria local opt-in — gravação de eventos categóricos (atalhos usados, fluxos abertos) só no disco do usuário, sem qualquer rede. Default: desabilitada.

anotae telemetry status         # diz se está habilitada
anotae telemetry list [--days N] # sumário por contagem
anotae telemetry clear           # apaga todos os arquivos

A telemetria só é gravada quando config.telemetry_enabled = true (em ~/.anotae/config.toml). Sem esse opt-in, todas as chamadas a record_event(...) no app são no-op.

A whitelist de eventos válidos vive em anotae/core/telemetry.py (constante ALLOWED_EVENTS). Adicionar evento novo exige PR explícito — defesa em profundidade contra deriva acidental.

`doctor <vault>`¶

Roda o healthcheck do vault — equivalente CLI ao Help → Verificar saúde do vault (PR #58). Útil para automação (cron, Tarefas Agendadas) ou diagnóstico rápido.

anotae doctor /caminho/para/vault.db

Senha-mestra fornecida via:

Prompt interativo (default) — getpass esconde caracteres.
Variável de ambiente ANOTAE_VAULT_PASSWORD — para automação. Last-resort: prefira agente de senha do SO ou KMS para automação real.

Saída cron-friendly:

[OK] healthcheck: 6/6 verificações
OK   Arquivo do vault — 16384 bytes, SHA-256 começa com 3a2f1c8d…
OK   Schema — versão 3 (esperada 3)
OK   Encounters — 12 total, todos com hash registrado
OK   Audit log — 47 entradas, 8 ações distintas
OK   Backups — 3 total, todos íntegros
OK   Snapshot pre-restore — ausente (esperado em operação normal)

Exit codes:

Código	Significado
`0`	Todas as 6 verificações passaram.
`1`	Pelo menos uma falhou (vault corrompido, schema desatualizado, backup com hash inválido, etc.)
`2`	Erro de uso (vault não encontrado, senha incorreta, prompt cancelado)

`bench all`¶

Roda a suite consolidada de benchmarks (KDF + vault open + encounter throughput + export). Útil para comparar o mesmo hardware em momentos diferentes ou comparar máquinas distintas (UBS-A vs. UBS-B). Resultados podem ser anexados a CSV.

anotae bench all [--encounters N] [--md-iterations N]
                 [--pdf-iterations N] [--skip-pdf]
                 [--csv PATH]

Argumento	Default	Descrição
`--encounters`	`50`	Quantidade de encounters no throughput.
`--md-iterations`	`10`	Iterações do `render_markdown`.
`--pdf-iterations`	`5`	Iterações do `render_pdf`.
`--skip-pdf`	—	Pula export_pdf (útil em headless sem `QGuiApplication`).
`--csv`	—	Anexa medições a CSV consolidado.

Saída exemplo (truncada):

benchmark              label                                    elapsed(s)  iters
kdf                    t=2 m=19456KiB p=1                           0.0500       1
kdf                    t=3 m=65536KiB p=1                           0.1700       1
vault_open             t=3 m=65536KiB                               0.1650       2
encounter_throughput   50 encounters (light KDF)                    0.4000      50
export_markdown        10x render_markdown(weak)                    0.0000      10
export_pdf             5x render_pdf(weak)                          0.0500       5

`mappings list`¶

Lista todos os plugins de mapping descobertos em ordem de prioridade. Útil para diagnóstico de conflitos e para confirmar que mappings custom (~/.anotae/mappings/ ou ANOTAE_MAPPING_PATHS) foram carregados.

anotae mappings list [--target-system SYS]

Argumento	Default	Descrição
`--target-system`	—	Filtra por `target_system` (ex.: `sei`, `esus-aps-pec`).

Saída exemplo:

3 mappings descobertos:

source   target_system          version  id
builtin  esus-aps-pec           1.0.0    esus-aps-pec-atendimento-individual
builtin  sei                    1.0.0    sei-relatorio-ses-df
user     sisreg-iii             1.1.0    sisreg-iii-customizado-regional

Fontes (ordem de prioridade — maior vence em conflito de id):

Source	Caminho
`builtin`	`vocabularies/mappings/` (parte do pacote, assinada)
`user`	`~/.anotae/mappings/` (opt-in do usuário)
`custom`	`ANOTAE_MAPPING_PATHS` env var (multi-instância / dev)

`vault-benchmark`¶

Mede o caminho real de criar/abrir vault em uma grade de KDFParams (Fallback, Intermediário, Default). Diferente de kdf benchmark, este reflete o que o usuário sente ao digitar a senha-mestra (lê meta, deriva chave, abre SQLite, decrypt do token).

anotae vault-benchmark [--iterations N] [--csv PATH] [--host-label LABEL]

Argumento	Default	Descrição
`--iterations`	`2`	Vezes que cada vault é aberto para média.
`--csv`	—	Anexa resultados a CSV (opt-in).
`--host-label`	hostname	Identificador curto (≤16 chars) para o CSV.

Senha placeholder fixa, vault sintético em tempfile.mkdtemp() apagado ao final. Nenhum dado real envolvido.

`kdf benchmark`¶

Mede o tempo de derivação de chave Argon2id em diferentes combinações de (time_cost, memory_cost, parallelism) e recomenda os parâmetros mais pesados (mais seguros) que ainda cumprem um alvo de latência. Útil para decidir, em hardware modesto (UBSs antigas), se vale usar o FALLBACK em vez do DEFAULT.

anotae kdf benchmark [--target SEGUNDOS]

Argumento	Default	Descrição
`--target`	`0.5`	Latência alvo em segundos.

A senha usada é uma placeholder fixa e o salt é aleatório — o comando não toca em nenhum vault real.

Saída:

Benchmark Argon2id (alvo: 0.50s)...
(usando senha placeholder + salt aleatório — sem tocar vaults)

  time   memory(KiB)  parallelism  elapsed(s)  status
     2         19456            1       0.045  ok
     3         19456            1       0.062  ok
     ...
     5        262144            1       2.131  lento

[OK] Recomendado para esta máquina:
  time_cost=3 memory_cost=65536 KiB parallelism=1

Não exposto pela CLI (por design)¶

A CLI não oferece:

Abrir/fechar vault, ler/escrever encounters — tudo isso exige a senha-mestra e fica restrito à GUI.
Restaurar backup pela CLI (use a GUI: Vault → Backups… → Restaurar selecionado… para snapshots .db, ou Restaurar de ZIP… para arquivos anotae-vault-*.zip portáveis — PR #64). Restaurar é destrutivo e merece a dupla confirmação visual.
Sincronização ou envio para nuvem — viola o ethos privacy-first (CLAUDE.md §2.1). Sem exceções.

Variáveis de ambiente reconhecidas¶

A CLI consulta as variáveis de ambiente abaixo. Nenhuma é obrigatória; existem para casos de automação ou customização local.

Variável	Onde é lida	Para que serve
`ANOTAE_VAULT_PASSWORD`	`anotae doctor`	Fornece a senha-mestra sem prompt interativo (automação cron / Tarefas Agendadas). Last-resort: prefira agente de senha do SO ou KMS. Nunca commitar em scripts versionados.
`ANOTAE_MAPPING_PATHS`	descoberta de plugins de mapping	Lista separada por `:` (Linux/macOS) ou `;` (Windows) de diretórios extras a procurar mappings, com prioridade mais alta que `~/.anotae/mappings/`. Útil em testes e ambientes onde o vault padrão não é gravável.
`LC_ALL` / `LC_MESSAGES` / `LANG`	`anotae.core.i18n._detect_language`	Define o idioma da UI/CLI (default `pt_BR`). Aceita `pt_BR.UTF-8`, `pt-BR` ou `pt_BR`.
`LOCALAPPDATA` (Windows)	NMH manifest install	Caminho do diretório `%LOCALAPPDATA%`; default `~/AppData/Local`. Só relevante em Windows e raramente precisa ser sobrescrita.
`QT_QPA_PLATFORM=offscreen`	testes Qt	Não usada pela CLI em si, mas referida em pytest/conftest. Documentada aqui para evitar confusão durante automação.

A CLI não consulta variáveis como ANOTAE_VAULT_PATH, ANOTAE_CONFIG, etc. — o caminho do vault sempre vem como argumento explícito. Isso é deliberado: evita "vault errado" por env var herdada de outro shell.

Exit codes consolidados¶

Código	Significado
`0`	Sucesso. Para subcomandos com múltiplas verificações (`doctor`, `bench`), significa "todas passaram".
`1`	Falha de domínio (vault corrompido, hash não bate, healthcheck falhou, etc.).
`2`	Erro de uso da CLI (argumento faltando, subcomando sem ação, vault inexistente).
`130`	Cancelamento pelo usuário (Ctrl-C no prompt de senha — propagado de `getpass`).

Para automação que toma decisão baseada em saída, sempre testar explicitamente o código (0 vs ≠ 0) — nunca grep no stdout.

Exemplos de uso real¶

Backup diário automatizado (Linux/macOS)¶

crontab -e com:

0 2 * * * /usr/local/bin/anotae backup create /home/$USER/.anotae/vault.db && /usr/local/bin/anotae backup verify /home/$USER/.anotae/vault.db $(ls -t /home/$USER/.anotae/backups/vault_*.db | head -1 | xargs basename)

Backup diário automatizado (Windows, Tarefas Agendadas)¶

$vault = "$env:USERPROFILE\.anotae\vault.db"
& "C:\Program Files\Anotae\anotae.exe" backup create $vault

Verificar todos os backups de um vault¶

for b in ~/.anotae/backups/vault_*.db; do
  anotae backup verify ~/.anotae/vault.db "$(basename "$b")"
done

Referência da CLI do Anotae¶

Convocação geral¶

Exit codes¶

Subcomandos¶

install-extension¶

uninstall-extension¶

extension-info¶

version¶

backup create <vault>¶

backup list <vault>¶

backup verify <vault> <name>¶

telemetry status / list / clear¶

doctor <vault>¶

bench all¶

mappings list¶

vault-benchmark¶

kdf benchmark¶