Este guia ensina você a construir uma ferramenta de terminal com o Termfy, o framework da Promovaweb para binários em Bun. Cada binário é um único executável com três modos: você navega pela TUI usando o teclado, executa comandos pela CLI e conecta agentes de IA pelo servidor MCP. A CLI também atende scripts e agentes com saída estruturada. Você descreve ao agente o que precisa construir e as 18 skills do Termfy conduzem cada etapa, da entrevista inicial à release.
Os exemplos do guia usam o mycli, um binário que consulta os pedidos de
uma loja. O capítulo de integração usa a API de WhatsApp da uazapi. As saídas
do esqueleto vêm do starter kit em execução. Na Parte 2, as saídas dos
commands novos mostram o comportamento que a spec descreve.
Como ler este guia
O guia tem três partes. Se é a sua primeira vez com o Termfy, leia a Parte 1 e siga a Parte 2 na ordem. A Parte 3 é para consulta.
Parte 1. Fundamentos
O que o Termfy é, como um executável atende três públicos e como as skills orientam o agente.
| Capítulo | Pergunta que responde |
|---|---|
| Visão geral | De que peças o Termfy é feito? |
| Começar | Como criar um binário e ver os três modos funcionando? |
| Três modos | Como um só executável decide entre TUI, CLI e MCP? |
| Skills | Como as skills orientam um agente e como são atualizadas? |
| Sequência das skills | Qual é a ordem das skills e o que cada uma entrega à seguinte? |
Parte 2. Construir
A Parte 2 acompanha uma evolução desde a descrição ao agente até a publicação do binário, mostrando os documentos e o código de cada etapa.
| Capítulo | O que você aprende |
|---|---|
| Descrever e especificar | a entrevista do CLISPEC.md, a spec de uma evolução e o ciclo dos status |
| Integrar uma API | importar a API da uazapi, guardar o token, escrever o client e passar a instância por parâmetro |
| Guardar dados | quando pedir um banco SQLite, migrations embutidas e repositórios |
| Testar, revisar e publicar | testes nos três modos, revisão por gravidade, release e conexão do agente |
Parte 3. Referência
| Página | Conteúdo |
|---|---|
| CLI | registry, options globais, saída em texto e --json, exit codes |
| TUI | abas, teclas, tema e componentes |
| MCP | tools, resources, prompts e regras de segurança |
| Configuração e credenciais | settings.json, cofre cifrado e master key |
| Publicar | versão, changelog, tag e binários |
| Glossário e problemas comuns | termos do framework e soluções para os erros frequentes |
Uma página por skill
Cada página diz quando usar a skill, como pedir, o que ela faz, um exemplo do que ela produz, os contratos que segue e para onde o fluxo vai depois.
| Etapa | Skills |
|---|---|
| começar | termfy, termfy-init, termfy-brand |
| descrever | termfy-clispec, termfy-spec, termfy-api-import |
| implementar | termfy-cli, termfy-tui, termfy-mcp, termfy-config, termfy-api, termfy-database, termfy-command-set |
| verificar | termfy-test, termfy-review, termfy-docs |
| entregar | termfy-release, termfy-mcp-client |
Repositórios
promovaweb/termfy: framework, skills e este guia.promovaweb/termfy-starter-kit: esqueleto do binário, template do GitHub.