Ir para o conteúdo
Promovaweb

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
  1. O perfil e o projeto
  2. Os arquivos da pasta global
  3. Qual perfil cada comando usa
  4. Conferir sem chamar a API
  5. Perfis da versão 0.9.0

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.
As chaves dos dois arquivos que formam um perfil: os metadados em accounts.json, legíveis, e a API key em credentials.json, cifrada com AES-256-GCM. A figura mostra só os nomes das chaves, sem nenhuma credencial.

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.

SituaçãoPerfil usadoEfeito no perfil ativo
Comando com --account cliente-aO perfil cliente-a, só nessa execução.Nenhum: o ativo continua o mesmo.
Variável definida no ambienteO perfil nomeado em PROMOVAWEB_CLICKUPFY_ACCOUNT.Nenhum: vale enquanto a variável existir.
Sem opção nem variávelO 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.

Abrir a documentaçãoConhecer a formação Vibe Coding

A formação Vibe Coding faz parte do Plano IA Makers.

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.