Perfis, workspaces e cofre
Um perfil do ClickUpfy é o registro local que associa um nome, como promovaweb ou cliente-a, a um usuário e a um workspace do ClickUp, com a API key guardada à parte no cofre cifrado de ~/.clickupfy/. Cada comando resolve o perfil pela opção --account, pela variável PROMOVAWEB_CLICKUPFY_ACCOUNT ou pelo perfil ativo, nessa ordem, por isso o mesmo binário atende workspaces de clientes diferentes sem misturar as chaves.
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
O perfil e o projeto
O ClickUpfy guarda o perfil e o projeto em lugares diferentes. O perfil vive na sua pasta de usuário e diz com qual API key e em qual workspace o binário fala. O projeto vive no repositório e diz qual perfil usar e quais IDs da hierarquia ficam autorizados. O mesmo perfil atende vários projetos. Um repositório de cliente aponta para outro perfil, com outra chave e outro workspace.
O comando clickupfy setup cria o perfil. Ele recebe a API key pessoal do ClickUp num prompt oculto, valida a chave, consulta o usuário autenticado e lista os workspaces que a chave alcança. Você escolhe o workspace do perfil e um nome local, que o binário normaliza em kebab-case. Em automação isolada, o mesmo setup aceita a chave, o nome e o workspace por opção, com --non-interactive.
Os arquivos da pasta global
A pasta ~/.clickupfy/ é criada com permissão 0700. Cada arquivo dentro dela recebe 0600. O accounts.json guarda os perfis sem nenhum segredo, então ele pode ser lido e copiado sem expor a chave. A API key de cada perfil fica no credentials.json, cifrada.
~/.clickupfy/
accounts.json
version:- Versão do formato do arquivo.
activeAccount:- Nome do perfil usado quando nenhum outro é indicado.
accounts.<perfil>.user:- ID, nome e e-mail do usuário autenticado pela chave.
accounts.<perfil>.workspace:- ID e nome do workspace associado ao perfil.
Cofre e preferências
clickup.<perfil>.api_key:- A API key do perfil, dentro do envelope cifrado.
master.key:- Arquivo vizinho com a chave do cofre em hexadecimal.
CLICKUPFY_MASTER_KEY:- Variável que fornece a chave do cofre no lugar do arquivo.
settings.json:- Preferências em texto claro, como o formato de saída.
Para abrir o cofre, o binário precisa da master key, lida da variável CLICKUPFY_MASTER_KEY ou do arquivo master.key. Num servidor de integração contínua, a variável deixa o cofre e a chave do cofre em lugares diferentes. A variável CLICKUPFY_HOME troca a pasta inteira, útil em testes e ambientes descartáveis. A referência de variáveis de ambiente deste portal lista todas as variáveis que o ClickUpfy lê, com o padrão e a fonte de cada uma.
Nenhum comando, ferramenta ou tela mostra a chave. Os comandos status e account show exibem a versão mascarada, enquanto o account list omite o campo. A ferramenta clickupfy_accounts_list do servidor MCP também lista os perfis sem revelar a chave.
Qual perfil cada comando usa
O binário resolve o perfil de cada execução em três degraus. A opção --account vale só para aquele comando e não altera o perfil ativo. Sem ela, vale a variável PROMOVAWEB_CLICKUPFY_ACCOUNT, pensada para automações. Sem as duas, vale o activeAccount do accounts.json, que o comando clickupfy account use troca.
cliente-a, só nessa execução.Nenhum: o ativo continua o mesmo.PROMOVAWEB_CLICKUPFY_ACCOUNT.Nenhum: vale enquanto a variável existir.activeAccount do accounts.json.Trocado por account use <perfil>.O workspace segue o perfil: o comando clickupfy workspace use troca o workspace do perfil resolvido. A configuração de um projeto que fixa --workspace precisa continuar igual ao workspace do perfil depois dessa troca. A página O servidor MCP por projeto mostra como o servidor compara os IDs fixados em cada chamada.
Conferir sem chamar a API
O comando clickupfy status mostra o caminho do accounts.json, o perfil resolvido, se ele é o ativo, a chave mascarada, o usuário e o workspace, sem nenhuma chamada ao ClickUp. O clickupfy whoami faz uma chamada autenticada e confirma se a chave continua válida. O clickupfy doctor confere localmente as permissões da pasta, o cofre, a master key, o perfil e os arquivos de MCP do projeto. Já o doctor --online acrescenta a validação da chave no endpoint de usuário e a leitura das skills instaladas.
A remoção também fica no disco local. O comando clickupfy account remove apaga os metadados e a credencial do perfil depois de uma confirmação, mas a API key continua válida no ClickUp até você revogá-la nas configurações do seu usuário no ClickUp.
Perfis da versão 0.9.0
O ClickUpfy 0.9.0 guardava os perfis num arquivo de configuração diferente, em ~/clickupfy/config.json. Na primeira execução de um comando que lê perfis, sem accounts.json e com o arquivo antigo presente, o binário importa cada perfil: os metadados vão para o accounts.json e cada API key para o cofre. O arquivo antigo só é lido, sem alteração, então a versão 0.9.0 continua funcionando durante a transição. O comando account import repete a importação. Com --force, ele substitui os perfis que já existem.
A configuração completa, com cada opção do setup e o formato dos arquivos, está na página de configuração da documentação. A hierarquia de Spaces, Folders e Lists que o perfil alcança tem página própria em Hierarquia. O portal ClickUp explica essa estrutura pelo lado do próprio ClickUp.
Continue na comunidade
Leve ao Discord da Promovaweb a chamada que falhou no ClickUpfy, com a mensagem de erro e a versão do binário. A comunidade pode comparar o comando com o escopo configurado no projeto.
Comandos e opções na documentação
Um comando recusado ou uma chamada MCP sem acesso precisa ser comparada com as opções da versão usada. A documentação reúne a instalação, os argumentos e as mensagens de erro para essa consulta.
A formação Vibe Coding faz parte do Plano IA Makers.