Instalação do ClickUpfy pelo npm ou executável standalone

Classificação

Requisitos

Para instalar pelo npm ou desenvolver, use Node.js 22.12.0 ou superior. Para usar um executável standalone, o Node.js não é necessário porque o runtime já está incorporado.

Você também precisa de uma API key pessoal do ClickUp com acesso a pelo menos um workspace. A chave só será usada na etapa de configuração.

Instale pelo npm

O pacote oficial instala o comando global:

1
npm install --global @promovaweb/clickupfy
2
clickupfy --version
3
clickupfy --help

O launcher seleciona o executável compilado em Linux x64, macOS Intel e macOS Apple Silicon. Em outras plataformas, inclusive Windows, usa o build JavaScript incluído no pacote.

Uma versão válida na primeira linha confirma que o pacote e o launcher foram encontrados. Se o terminal não localizar clickupfy, confira o diretório global do npm:

1
npm prefix --global
2
npm bin --global

O segundo comando pode não existir em versões novas do npm. Nesse caso, o diretório de executáveis costuma ser bin dentro do prefixo em Linux e macOS.

Atualize a instalação npm

Quando o ClickUpfy foi instalado globalmente pelo npm, o próprio comando inicia a instalação da versão nova e confirma o launcher que ficará disponível no terminal:

1
clickupfy upgrade

O alvo padrão é latest. Para testar um canal ou fixar uma versão, use clickupfy upgrade next ou clickupfy upgrade 0.5.0. O comando não substitui um executável standalone, nesse caso, baixe o archive correspondente na GitHub Release, confira SHA256SUMS e substitua o arquivo no PATH.

Instale um executável standalone

Cada GitHub Release distribui archives para Linux x64, macOS Intel, macOS Apple Silicon e Windows x64. Baixe o archive da plataforma, extraia clickupfy ou clickupfy.exe e mova o arquivo para uma pasta presente no PATH.

No Linux ou macOS:

1
chmod +x clickupfy
2
./clickupfy --version

Antes de usar um binário baixado, confira o arquivo SHA256SUMS da mesma release. O nome e a versão do archive precisam corresponder à plataforma escolhida.

No macOS, o Gatekeeper pode impedir a abertura de um executável sem notarização. Confirme a origem no repositório oficial e siga a política de segurança da máquina. Não desative proteções globais para contornar o aviso.

Instale para desenvolvimento

Clone o repositório independente do ClickUpfy e execute:

1
npm install
2
npm run build
3
npm link
4
clickupfy --version

npm link aponta o comando global para o checkout atual. Use esse modo apenas quando precisar desenvolver ou validar uma mudança local. Para voltar ao pacote publicado, remova o link e reinstale a versão do npm.

Confirme a instalação

Execute três leituras sem credenciais:

1
clickupfy --version
2
clickupfy --help
3
clickupfy agent skill list

O catálogo deve listar clickupfy-dev, clickup-issue-create, clickup-issue-implement e clickupfy-release. A presença das skills confirma que os assets foram empacotados junto ao CLI.

Ainda não execute comandos remotos. Primeiro configure um perfil.

Windows: PATH e PowerShell

No Windows, npm prefix --global informa o diretório que contém clickupfy.cmd. Inclua esse diretório no PATH do seu usuário e abra outro terminal. Para o standalone, extraia clickupfy.exe para uma pasta própria, adicione essa pasta ao PATH em Variáveis de Ambiente e abra outro terminal.

Se o PowerShell impedir a execução de npm.ps1, use npm.cmd e clickupfy.cmd explicitamente, ou execute pelo Prompt de Comando. Isso evita alterar a política de execução da máquina.

Para capturar saída JSON com acentos, prefira PowerShell 7 ou redirecionamento pelo cmd.exe. No PowerShell 5.1, configure UTF-8 na sessão antes de capturar:

1
[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
2
clickupfy.cmd task list --list 30 --json | ConvertFrom-Json

O ClickUpfy emite UTF-8. Alterar a codepage dentro do processo filho não corrige a leitura feita pelo PowerShell pai.

As permissões 0700/0600 são verificadas apenas em Linux e macOS. No Windows, o doctor marca essas verificações como não aplicáveis, as ACLs NTFS precisam ser conferidas separadamente. Arquivos JSON com BOM UTF-8 são aceitos.

Se houver erro de escrita, feche programas que mantêm o arquivo aberto e confira o atributo somente leitura. As gravações usam substituição atômica e removem o temporário mesmo se a substituição falhar.