YNAB Manager CLI

Visão Geral

O YNAB resolve muito bem o controle financeiro diário, mas falha em um caso extremamente comum no Brasil: compras parceladas. Para cada compra em 6x, 10x ou 12x, o usuário precisa lançar manualmente cada parcela mês a mês. Isso torna o uso disciplinado do YNAB cansativo, propenso a erro e fácil de abandonar justamente em momentos de mais complexidade financeira.

O YNAB Manager CLI nasceu como uma ferramenta pessoal para eliminar essa fricção: em vez de criar parcelas manualmente, o usuário informa valor total, número de parcelas, data de início e conta - e a CLI gera todas as transações automaticamente no YNAB, respeitando as regras da API. As parcelas passadas entram como transações normais; as futuras, como transações agendadas. Opcionalmente, o usuário pode ativar sugestões por IA para payees e categorias.

Foi um projeto solo, em que desenhei a arquitetura em camadas (CLI, core, serviços, storage), implementei toda a lógica de parcelamento, deduplicação e integração com a API do YNAB, além de testes automatizados e setup de qualidade de código. O resultado é uma ferramenta que eu uso diariamente desde o início de 2026 e que foi aberta para outros usuários avançados do YNAB com o mesmo problema.

Diferencial Principal

O diferencial do YNAB Manager CLI não é “apenas” criar parcelas automaticamente, mas tratar a operação de escrita no YNAB como um fluxo crítico que precisa ser seguro, idempotente e alinhado às restrições pouco documentadas da API.

Dois pontos se destacam: a separação inteligente entre transações passadas e futuras (com uso de endpoints diferentes para contornar a limitação de 7 dias para transações agendadas) e um sistema de import_id determinístico baseado em hash do plano de parcelamento. Isso permite reexecutar o mesmo wizard sem medo de duplicar nada no orçamento, algo que muitas integrações com YNAB e outros ERPs ignoram.

Além disso, o uso de IA é pragmático: não é o centro do produto, mas um serviço opcional que sugere categorias e payees usando GPT-4o-mini com temperatura controlada, sem tornar a ferramenta dependente da API da OpenAI.

Arquitetura

• CLI Layer (app.py, commands/, wizards/): Orquestra a interação com o usuário via terminal usando Rich e Questionary; implementa fluxos guiados para criar parcelamentos, revisar configurações e buscar transações.
• Installment Wizard: Coleta dados do plano (conta, valor total, número de parcelas, frequência, data de início) e expande isso em uma série de transações unitárias, já no formato exigido pela API do YNAB.
• Core – installment.py: Modelos Pydantic v2 para o plano de parcelamento e regras de negócio de geração de parcelas (datas, valores, arredondamento, memos), além da geração de hashes determinísticos.
• Core – deduplication.py / similarity.py: Funções para gerar import_id baseado em SHA256 do plano, além de lógica de busca e comparação de transações recentes para evitar duplicatas silenciosas.
• Services – ynab_client.py: Wrapper sobre o SDK oficial do YNAB, expondo operações de leitura e escrita (transações e transações agendadas) com tratamento de erros e logging amigável para CLI.
• Services – ai_suggester.py: Integração com OpenAI (GPT-4o-mini) para sugerir payees e categorias a partir de descrições de compra, usando temperatura baixa para previsibilidade.
• Storage – config.py: Gerencia arquivo de configuração local (orçamento padrão, símbolo de moeda, preferências de IA), carregando e persistindo as opções do usuário em disco.
• Storage – cache.py: Cache local de dados que mudam pouco (lista de budgets, contas, categorias) para reduzir chamadas à API do YNAB e melhorar a responsividade da CLI.
• Storage – keyring_storage.py: Encapsula a persistência de tokens sensíveis (token de API do YNAB e, opcionalmente, da OpenAI) no keyring nativo do sistema operacional.
• Test Suite (pytest): Conjunto de testes cobrindo geração de planos, hash/import_id, deduplicação e partes da lógica de integração, com formatação (Black), lint (Ruff) e checagem estática (mypy).

Destaques Técnicos

• Modelei o plano de parcelamento com Pydantic v2, centralizando validações de entrada (datas, frequência, contagem de parcelas, valor total) e reduzindo bugs de borda em datas e arredondamento.
• Implementei um sistema de idempotência baseado em SHA256 do plano (account_id, payee_name, valor total, número de parcelas, data de início, frequência), gerando import_id determinísticos por parcela, compatíveis com o comportamento de deduplicação do YNAB.
• Tratei explicitamente a restrição de “até 7 dias no passado” da API de transações agendadas, separando a criação de parcelas em duas chamadas: TransactionsApi para o histórico e ScheduledTransactionsApi para o futuro.
• Usei Keyring para armazenar tokens de API no keychain do sistema, removendo a necessidade de variáveis de ambiente ou arquivos .env sensíveis no disco.
• Estruturei a CLI com Rich e Questionary para fornecer menus navegáveis, tabelas coloridas e feedback visual imediato, reduzindo a barreira de uso para quem não domina flags de terminal.
• Configurei pipeline local de qualidade com pytest, Black, Ruff e mypy, garantindo um código Python consistente, tipado e fácil de evoluir como ferramenta pessoal de longo prazo.
• Mantive a integração de IA desacoplada: a CLI funciona integralmente sem chave de OpenAI, e as chamadas ao modelo usam temperatura baixa (0.3) para priorizar consistência sobre criatividade nas sugestões.