Ir para o conteúdo
Promovaweb

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
  1. Um executável com CLI, TUI, MCP e skills
  2. Onde ficam a chave e o escopo
  3. Como o binário chega à sua máquina
  4. O que fica com o ClickUp
  5. Licença, versões e mantenedor

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 que o ClickUpfy lê: a pasta global com perfis e cofre, criada com permissão 0700, mais os arquivos do projeto, que fixam perfil e IDs para cada cliente MCP sem conter a API key.

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.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.