O que é o ClickUpfy e o que ele faz
O ClickUpfy é uma ferramenta de linha de comando que reúne CLI, TUI e servidor MCP num único executável e conversa com as APIs públicas v2 e v3 do ClickUp. No seu terminal, o comando clickupfy lê e altera tarefas, comentários, Sprints e registros de tempo com a API key de um perfil local, por isso o agente de código trabalha no mesmo workspace que você sem receber a chave dentro do repositório.
Ficha e sumário da página
- Referência técnica
- ClickUpfy v1.1.2
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
Um executável com CLI, TUI, MCP e skills
O ClickUpfy é compilado em Bun como um binário só. Três das quatro formas de uso dependem do jeito de chamar esse binário. Com argumentos, ele funciona como CLI: a sintaxe segue recurso ação, como task get, comment create ou sprint current. A resposta sai em texto compacto ou, quando você acrescenta --json, num envelope JSON. Sem argumentos, num terminal interativo, ele abre a TUI.
A TUI desta versão serve para leitura de relance. A aba Overview mostra o perfil resolvido, o usuário, o workspace, o cronômetro em execução e o estado dos arquivos locais. A aba About mostra a identidade do binário e a licença. Nenhuma tela edita tarefas: a escrita acontece pela CLI ou pelo servidor MCP.
O comando clickupfy mcp inicia o servidor MCP com transporte stdio, a forma que o Claude Code, o Codex, o Gemini CLI e o OpenCode usam para chamar ferramentas externas. O cliente MCP abre o processo, lista as ferramentas e chama cada uma com argumentos validados por schema. A página O servidor MCP por projeto explica o escopo que cada projeto fixa nesse servidor.
As skills completam o conjunto. Elas são instruções em Markdown que acompanham o binário e orientam o agente na ordem de trabalho: ler a tarefa inteira, publicar o plano, registrar tempo, marcar checklists e conferir o status final. As skills usam a CLI ou o MCP disponível e não guardam credencial. A página Skills dos agentes descreve as cinco que vêm no binário.
- CLIComandos no formato recurso e ação, com saída em texto ou no envelope JSON e exit codes estáveis.
- TUIPainel de leitura aberto pelo comando sem argumentos, com perfil, workspace e cronômetro em execução.
- Servidor MCPProcesso stdio que expõe as operações do ClickUp como ferramentas para os agentes de código.
- SkillsInstruções em Markdown que dizem ao agente quando ler, planejar, comentar, medir tempo e concluir.
Onde ficam a chave e o escopo
O ClickUpfy separa dois lugares no disco. A pasta global ~/.clickupfy/ guarda os perfis, o cofre cifrado com as API keys, a master key e as preferências. A raiz do projeto guarda só o perfil escolhido e os IDs autorizados da hierarquia do ClickUp, gravados no arquivo de configuração de cada cliente MCP. Com essa separação, você usa a mesma API key em vários repositórios e cada repositório aponta para a própria List.
~/.clickupfy/Pasta global do usuário, com permissão 0700.accounts.jsonPerfis, usuário e workspace de cada um, sem segredo.credentials.jsonCofre AES-256-GCM com a API key de cada perfil.master.keyChave do cofre, trocada por CLICKUPFY_MASTER_KEY quando definida.settings.jsonPreferências em texto claro, como o formato de saída.raiz do projeto/Repositório ligado a uma List do ClickUp..mcp.jsonServidor MCP do Claude Code com perfil e IDs fixados..codex/config.tomlA mesma entrada no formato do Codex..gemini/settings.jsonA entrada do Gemini CLI, gravada por mcp setup.opencode.jsonA entrada do OpenCode, gravada por mcp setup.
Os arquivos do projeto podem entrar no Git quando os IDs do ClickUp não forem informação sensível para o seu projeto, porque nenhum deles carrega a chave. A página Perfis, workspaces e cofre mostra como o cofre cifra a API key e a ordem que o binário segue para escolher o perfil de cada comando.
Como o binário chega à sua máquina
O pacote @promovaweb/clickupfy no npm funciona como launcher. Na primeira execução, ele baixa o binário da sua plataforma, confere o SHA256 contra o SHA256SUMS da GitHub Release e mantém o arquivo em cache. Por isso o Node.js 18.17 ou superior serve só para esse download. O binário em si roda sem runtime instalado. Cada release publica binários para Linux x64 e ARM64, macOS Intel e Apple Silicon e Windows x64.
O comando clickupfy upgrade atualiza a instalação nas duas formas. Instalado pelo npm, ele roda o npm install -g da versão alvo. Como binário avulso, ele baixa o arquivo novo, confere o hash e troca o executável. Os detalhes de cada plataforma estão na instalação da documentação.
O que fica com o ClickUp
O ClickUp continua guardando o trabalho. A tarefa permanece no workspace com a descrição, o status, os checklists e os comentários, assim como as Sprints e os registros de tempo. O ClickUpfy não cria um gerenciador paralelo nem um banco local com cópia das tarefas. No disco ficam só perfis, credenciais e preferências. Permissões e ClickApps também seguem administrados na interface do ClickUp.
Algumas ações ficam fora da ferramenta porque a API pública não oferece o endpoint. O ClickUpfy não cria Sprints nem habilita o Sprint ClickApp: você cria o Sprint Folder no ClickUp e usa a CLI para consultar a Sprint, associar tarefas e definir Sprint Points. O binário também não escolhe qual status encerra uma tarefa. O comando list get devolve os status configurados na List. As skills escolhem, entre eles, um status terminal que exista ali. O portal ClickUp explica a hierarquia de Spaces, Folders e Lists que o ClickUpfy percorre.
Licença, versões e mantenedor
A Promovaweb mantém o ClickUpfy no repositório promovaweb/clickupfy, no GitHub. Desde a versão 1.1.0, o código sai sob a GNU AGPL 3.0. As versões anteriores continuam com a licença que tinham na publicação. A versão de referência deste portal é a v1.1.2, publicada em 13 de novembro de 2026 no npm e na GitHub Release. Desde a v1.1.1, o pacote do npm é publicado da máquina local do mantenedor. O workflow de release do GitHub deixou de publicar no npm.
O ClickUpfy usa a estrutura do Termfy, o framework da Promovaweb para binários com CLI, TUI e MCP no mesmo executável. As versões capturadas pela Promovaweb aparecem no changelog do ClickUpfy, cada uma com um artigo em português. A referência completa de comandos e ferramentas vive na documentação do ClickUpfy. O próximo assunto deste portal mostra o trabalho que essas peças fazem juntas, na página Para que serve o ClickUpfy.