Ir para o conteúdo
Promovaweb

Comandos e recursos do ClickUpfy

Os comandos do ClickUpfy seguem a sintaxe clickupfy recurso ação e cobrem tarefas, checklists, comentários, Sprints, Docs, registro de tempo e a hierarquia do workspace. Com --json, cada comando responde num envelope com ok, command e data e sai com um exit code fixo por tipo de falha, por isso um script ou um agente separa uma tarefa inexistente, código 6, de uma credencial ausente no cofre, código 4, sem interpretar a mensagem de erro.

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. Recurso e ação
  2. Do comando à resposta
  3. Os grupos de comandos
  4. Exit codes que o script entende
  5. Exclusões com confirmação

Recurso e ação

Cada comando do ClickUpfy nomeia primeiro o recurso do ClickUp e depois a ação sobre ele. O comando task get lê uma tarefa, comment create publica um comentário, sprint current encontra a Sprint ativa e list get devolve os status de uma List. Os recursos levam os nomes que o ClickUp usa para tarefa, List, Sprint e Doc, então o nome do comando já diz qual objeto ele lê ou altera.

As opções globais valem em qualquer posição da linha. A opção --account usa outro perfil só naquela execução, --json troca a saída de texto pelo envelope estruturado e --no-color desliga as cores ANSI, com o mesmo efeito da variável NO_COLOR. A opção --skill imprime a documentação embutida no binário, inteira ou por tópico. Já --opencli descreve a árvore inteira de comandos em JSON, no formato OpenCLI.

Do comando à resposta

O binário segue o mesmo caminho para qualquer comando. O diagrama abaixo usa os nomes dos arquivos de src/ descritos na arquitetura do projeto.

  1. Entrada

    main.ts

    Sem argumentos e com TTY, abre a TUI. Com argumentos, envia a linha ao parser.

  2. Parser

    cli/parser.ts

    Percorre a árvore de comandos e valida opções e argumentos. Uma linha inválida sai com código 2.

  3. Comando

    cli/commands/

    Executa a ação, chama a API do ClickUp e devolve os campos da resposta.

  4. Saída

    --json

    Imprime texto ou o envelope com ok, command e data, ou error na falha.

  5. Exit code

    error.code

    O processo encerra com o mesmo número que aparece no envelope.

O caminho de um comando dentro do binário, conforme docs/architecture.md: o parser valida a linha, o comando chama a API e o envelope JSON leva o mesmo código que encerra o processo.

A saída padrão é texto compacto, pensada para leitura no terminal. Com --json, a resposta de sucesso traz ok, command e data, com as listas dentro de um objeto, como data.tasks ou data.comments. Em task get, os modos --raw e --markdown são exclusivos: a linha com os dois sai com código 2. Na falha, o envelope troca data por error, com o código, o nome, a mensagem e os detalhes. Um agente que chama a CLI pelo terminal lê o campo ok e o código, sem procurar texto de erro na saída.

Os grupos de comandos

Os comandos se dividem pelo recurso que leem ou alteram. A tabela abaixo reúne os grupos da referência do CLI na v1.1.2, com um comando real de cada um.

ComandoRecursoO que faz
clickupfy task get <task-id> --markdownTarefasLê a tarefa com subtarefas e checklists num documento único.
clickupfy checklist setChecklistsMarca ou reabre um item de checklist e confirma o novo estado.
clickupfy comment create --task <task-id>ComentáriosPublica um comentário na tarefa, como o plano ou um checkpoint.
clickupfy sprint tasks <sprint-id>SprintsLista as tarefas da Sprint, com --open-only para as abertas.
clickupfy doc page list <doc-id>DocsLê as páginas de um Doc do ClickUp com o conteúdo em Markdown.
clickupfy list list --space <id>HierarquiaLista as Lists de um Space, ou de um Folder com --folder.
clickupfy api call GetTaskAPI genéricaChama qualquer operação do catálogo das APIs v2 e v3 do ClickUp.

O grupo de registro de tempo consulta o cronômetro atual, inicia um registro ligado a uma tarefa e encerra o registro em execução. O grupo de tags cria, renomeia e exclui tags de um Space. Os comandos de tarefa acrescentam ou removem uma tag sem trocar as outras. Na criação, task create aceita a descrição em Markdown com --markdown-content, a tarefa pai com --parent para gerar uma subtarefa e as datas de início e de entrega, com a lista completa de opções no --help de cada ação.

O grupo api cobre o que os comandos dedicados não alcançam. O comando api list lista as operações do catálogo, api describe mostra os parâmetros de uma delas e api call executa a chamada com os parâmetros de caminho, de consulta e de corpo em JSON, inclusive o envio de anexos. O mesmo catálogo vira ferramentas no servidor MCP, com 173 operações das APIs v2 e v3.

Exit codes que o script entende

O ClickUpfy usa um número por tipo de falha. Esse número é o mesmo no processo e no campo error.code do envelope. Um script de integração contínua ou um agente decide o próximo passo pelo código: repetir a chamada numa falha de rede, refazer o setup numa credencial ausente ou parar quando o recurso não existe.

  • 0 SUCCESSO comando terminou sem falha.
  • 2 USAGEArgumento, opção ou subcomando inválido.
  • 3 CONFIGO settings.json está ausente, inválido ou tem chave desconhecida.
  • 4 CREDENTIALSCofre ilegível, master key ausente ou credencial não encontrada.
  • 5 NETWORK_OR_APIFalha de rede ou resposta da API fora do esperado.
  • 6 NOT_FOUNDO recurso solicitado não existe no workspace.

A tabela completa também tem os códigos 1 para falha sem classificação, 7 para permissão negada no sistema de arquivos, 8 quando a TUI roda sem terminal interativo, 9 quando o servidor MCP não inicia ou perde o transporte e 130 para interrupção com Ctrl+C. O servidor MCP devolve o mesmo código nas respostas com isError.

Exclusões com confirmação

Os comandos que apagam alguma coisa exigem confirmação. O task delete, o tag delete e o account remove mostram um prompt no terminal. Nas automações, a opção --yes confirma sem prompt. No servidor MCP, as ferramentas destrutivas só executam com confirm: true no argumento.

O ClickUpfy também deixa algumas ações com a interface do ClickUp. A criação de Sprints e a ativação do Sprint ClickApp ficam fora da CLI, porque a API pública não tem endpoint para elas. A referência de cada comando, com todas as opções e exemplos, está na referência do CLI. A página O servidor MCP por projeto mostra como as mesmas operações chegam ao agente como ferramentas.

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.