CLI ClickUpfy: tarefas, checklists, comentários e tempo

Classificação

Os IDs deste capítulo são fictícios. Use list get para obter a grafia dos status e task get --json para encontrar IDs de checklist items. Uma chamada de escrita deve ser seguida por uma nova leitura do recurso alterado, a ausência de erro não confirma que o ClickUp persistiu o valor esperado.

Leitura de tarefas

clickupfy task list --list <id>

Lista tarefas de uma List em uma página. --list é obrigatório porque o CLI não lê o .mcp.json do projeto. --status aceita um ou mais nomes de status, --assignee recebe um ou mais IDs de responsáveis, --page começa em zero.

Exemplos:

1
clickupfy task list --list 3001

1
clickupfy task list --list 3001 --status "em andamento"

1
clickupfy task list --list 3001 --status aberta "em andamento" --assignee 42

1
clickupfy task list --list 3001 --include-closed --page 0

1
clickupfy --account produto --json task list --list 3001 --page 2

A saída comum é uma tabela com ID, nome, status, prioridade, pontos, pessoas e link. Use --json quando um script precisar de todos os campos retornados pela API. Para encontrar uma tarefa fora de uma List conhecida, use task search.

clickupfy task get <task-id>

Obtém uma tarefa e prepara uma fila chamada execution, que inclui tarefa, subtarefas e checklist items em uma ordem estável. Sem opção de formato, imprime uma tabela compacta da fila. --json mostra a estrutura, --markdown junta metadados, descrição e itens em um documento, --raw mostra apenas a resposta original da API. Escolha exatamente um desses formatos.

Exemplos:

1
clickupfy task get 86abc123

1
clickupfy task get 86abc123 --markdown

1
clickupfy task get 86abc123 --raw

1
clickupfy --json task get 86abc123

1
clickupfy --account produto task get 86abc123 --markdown

execution.items usa task:<id> para tarefas e subtarefas e checklist:<checklist-id>:<item-id> para itens de checklist. parentKey e depth preservam a relação de parentesco. Não tente combinar --raw, --markdown e --json: o CLI recusa a ambiguidade de formato.

clickupfy task search

Busca tarefas em todo o workspace associado ao perfil. É uma consulta paginada, limitada por --max-pages, que começa em uma e aceita no máximo cem páginas. O texto de --query procura nome, descrição ou ID.

Exemplos:

1
clickupfy task search --query "autenticação"

1
clickupfy task search --query 86abc123

1
clickupfy task search --query "API" --status "em andamento"

1
clickupfy task search --assignee 42 --include-closed --max-pages 5

1
clickupfy --account cliente-a --json task search --query "checkout" --max-pages 10

Se mais de uma tarefa corresponder ao pedido, apresente os IDs e nomes para a pessoa escolher a correta antes de executar uma escrita. Em MCP de projeto, use clickupfy_tasks_search: essa ferramenta é limitada à List fixa, enquanto este comando percorre o workspace inteiro.

Criação e atualização de tarefas

clickupfy task create

Cria tarefa ou subtarefa na List indicada. --list e --name são obrigatórios. Use --description para texto simples ou --markdown-content quando a descrição precisa preservar Markdown. O CLI não impõe uma regra de prioridade, status ou pontos do seu time, ele transmite valores válidos para a API.

Exemplos:

1
clickupfy task create --list 3001 --name "Corrigir retorno da API"

1
clickupfy task create \
2
  --list 3001 \
3
  --name "Documentar autenticação" \
4
  --description "Explicar o fluxo de login."

1
clickupfy task create \
2
  --list 3001 \
3
  --name "Criar testes" \
4
  --markdown-content "## Casos\n\n- Login válido\n- Senha inválida"

1
clickupfy task create \
2
  --list 3001 \
3
  --name "Implementar refresh token" \
4
  --status "em andamento" \
5
  --priority 2 \
6
  --assignee 42 57 \
7
  --start-date 2026-08-10 \
8
  --due-date 2026-08-14 \
9
  --points 5

1
clickupfy --account produto task create \
2
  --list 3001 \
3
  --parent 86abc123 \
4
  --name "Cobrir expiração de sessão" \
5
  --markdown-content "Adicionar casos de teste para sessão expirada."

Consulte clickupfy list get <list-id> para copiar o status exato. Depois da criação, guarde o ID devolvido e chame task get para confirmar pai, datas, responsáveis e conteúdo. Não use --parent para mover uma tarefa existente, ele só define o pai na criação.

clickupfy task update <task-id>

Atualiza campos de uma tarefa existente. Pelo menos um campo é obrigatório. --clear-start-date e --clear-due-date removem as respectivas datas, quando uma flag de remoção e uma nova data aparecem juntas, a remoção prevalece.

Exemplos:

1
clickupfy task update 86abc123 --status "em andamento"

1
clickupfy task update 86abc123 --name "Corrigir autenticação por token"

1
clickupfy task update 86abc123 --priority 1 --points 8

1
clickupfy task update 86abc123 --start-date 2026-08-10 --due-date 2026-08-14

1
clickupfy --account produto task update 86abc123 --markdown-content "## Entrega\n\nPublicar a documentação atualizada." --clear-due-date

--description e --markdown-content representam alternativas de conteúdo, envie apenas a forma que você quer persistir. Uma atualização de status precisa usar a grafia devolvida por list get. Releia a tarefa depois da escrita e compare cada campo solicitado com o estado devolvido.

clickupfy task delete <task-id>

Exclui permanentemente uma tarefa. Em terminal interativo, pede confirmação, em automação, exige --yes. Leia nome, List e relação com Sprint antes de executar. A exclusão não é uma forma de retirar a tarefa de uma Sprint: use sprint remove-task para remover apenas a associação.

Exemplos:

1
clickupfy task delete 86abc123

1
clickupfy task delete 86abc123 --yes

1
clickupfy --account produto task delete 86abc123

1
clickupfy --account cliente-a task delete 77def456 --yes

1
clickupfy task get 86abc123 && clickupfy task delete 86abc123 --yes

O último exemplo lê a tarefa no mesmo terminal, mas ainda exige que você compare o resultado e tenha autorização explícita. No MCP, a ferramenta equivalente exige o campo literal confirm: true.

Checklists e comentários

clickupfy checklist create <task-id> --name <nome>

Cria um checklist vazio em uma tarefa. Os itens são criados pelo comando seguinte. Use um nome que indique a finalidade, como Testes, Publicação ou Revisão manual.

Exemplos:

1
clickupfy checklist create 86abc123 --name "Testes"

1
clickupfy checklist create 86abc123 --name "Revisão de segurança"

1
clickupfy checklist create 77def456 --name "Publicação"

1
clickupfy --account produto checklist create 86abc123 --name "Aceite"

1
clickupfy --json checklist create 86abc123 --name "Regressão"

Guarde o ID retornado: item-create usa o ID do checklist, não o ID da tarefa. Crie o checklist na tarefa que realmente possui os itens, uma subtarefa pode ter checklist próprio e não deve receber os itens da tarefa pai por acidente.

clickupfy checklist item-create <checklist-id> --name <nome>

Acrescenta um item aberto a um checklist. --assignee é opcional e recebe um ID numérico. O comando não aceita o ID da tarefa porque o checklist já define seu proprietário.

Exemplos:

1
clickupfy checklist item-create check-1 --name "Executar testes unitários"

1
clickupfy checklist item-create check-1 --name "Executar build"

1
clickupfy checklist item-create check-1 --name "Revisar documentação" --assignee 42

1
clickupfy --account produto checklist item-create check-2 --name "Conferir changelog"

1
clickupfy --json checklist item-create check-3 --name "Validar publicação" --assignee 57

Um item deve descrever uma verificação observável, não uma promessa genérica. Depois de criar itens, execute task get --json para localizar o item-id e confirmar que todos começam abertos.

clickupfy checklist set <task-id> <checklist-id> <item-id>

Marca um item como concluído com --resolved ou o reabre com --open. Escolha exatamente uma flag. O ClickUpfy primeiro confirma que o item pertence à tarefa raiz informada, grava o estado e relê a tarefa para confirmar o resultado.

Exemplos:

1
clickupfy checklist set 86abc123 check-1 item-1 --resolved

1
clickupfy checklist set 86abc123 check-1 item-1 --open

1
clickupfy --account produto checklist set 86abc123 check-2 item-4 --resolved

1
clickupfy --json checklist set 77def456 check-3 item-2 --resolved

1
clickupfy checklist set 77def456 check-3 item-2 --open

Não use --resolved --open nem omita ambas: o CLI recusa as duas situações. Um item-id de outro checklist também é recusado pela releitura. Marque o item somente depois da validação correspondente.

clickupfy comment list --task <id>

Lista os comentários de uma tarefa com autoria, data e texto. A API pode representar o conteúdo em formatos diferentes, o ClickUpfy o normaliza para a coluna text na tabela compacta.

Exemplos:

1
clickupfy comment list --task 86abc123

1
clickupfy comment ls --task 86abc123

1
clickupfy --json comment list --task 86abc123

1
clickupfy --account produto comment list --task 86abc123

1
clickupfy --account cliente-a --json comment list --task 77def456

Leia os comentários antes de atualizar status ou publicar outro progresso, pois podem conter uma orientação nova. Nunca publique credenciais, dados pessoais, URLs assinadas ou logs extensos em um comentário.

clickupfy comment create --task <id> --text <texto>

Publica um comentário em uma tarefa. --notify-all pede ao ClickUp que notifique todos os participantes. Use o comando para registrar início, resultado de teste, mudança de escopo ou conclusão, sempre com informação verificável.

Exemplos:

1
clickupfy comment create --task 86abc123 --text "Iniciei a análise da tarefa."

1
clickupfy comment create --task 86abc123 --text "Os testes unitários passaram."

1
clickupfy comment create --task 86abc123 --text "Aguardando acesso ao ambiente de homologação." --notify-all

1
clickupfy --account produto comment create --task 86abc123 --text "Documentação e ebook foram atualizados."

1
clickupfy --json comment create --task 77def456 --text "Validação final concluída." --notify-all

Reler comment list confirma que o comentário ficou na tarefa pretendida e que o texto chegou completo. O comando não modifica status, timer ou checklist.

Time tracking

clickupfy time current

Consulta o time entry em execução no workspace associado ao perfil. Chame este comando antes de time start para não iniciar outro registro sem saber qual tarefa já está em andamento.

Exemplos:

1
clickupfy time current

1
clickupfy --json time current

1
clickupfy --account produto time current

1
clickupfy --account cliente-a --json time current

1
clickupfy time current && clickupfy task get 86abc123

Se houver entrada ativa para outra tarefa, pare e peça orientação antes de usar time stop. O comando é somente leitura e não altera status ou comentários.

clickupfy time start --task <id>

Inicia um time entry associado à tarefa. A descrição é opcional e deve dizer o trabalho em curso. O registro pertence ao usuário autenticado pelo perfil e ao workspace desse perfil.

Exemplos:

1
clickupfy time start --task 86abc123

1
clickupfy time start --task 86abc123 --description "Implementação"

1
clickupfy time start --task 86abc123 --description "Testes de regressão"

1
clickupfy --account produto time start --task 86abc123 --description "Revisão de documentação"

1
clickupfy --account cliente-a time start --task 77def456 --description "Correção da integração"

Depois da chamada, execute time current para confirmar o item ativo. Iniciar um timer não muda o status da tarefa nem avisa participantes, essas ações usam task update e comment create separadamente.

clickupfy time stop

Encerra o time entry em execução no workspace do perfil. Não recebe argumento de tarefa: ele para o registro atual. Por isso a consulta anterior é necessária em trabalhos paralelos ou quando mais de uma pessoa usa o mesmo perfil local.

Exemplos:

1
clickupfy time stop

1
clickupfy --account produto time stop

1
clickupfy --account cliente-a time stop

1
clickupfy time stop && clickupfy time current

1
clickupfy --json time stop

O quarto exemplo verifica que não há entrada em execução após o encerramento. Parar o tempo não fecha tarefa, não altera seus pontos e não resolve checklist items. Registre a conclusão do trabalho nas interfaces próprias se elas também forem autorizadas.

Tags de tarefas

clickupfy task add-tag <task-id> <tag>

Adiciona uma tag a uma tarefa existente pela API do ClickUp. As demais tags permanecem na tarefa. Cada execução adiciona um único nome, coloque nomes com espaços entre aspas. O comando não gerencia as cores ou o catálogo de tags do Space.

A API key do perfil precisa ter permissão para alterar a tarefa. Erros de permissão, tarefa inexistente e outras recusas do ClickUp são propagados sem imprimir sucesso. A saída comum confirma a associação, e a saída JSON contém {"added":true,"taskId":"task-1","tagName":"bug"}. Essa confirmação indica que a API aceitou a chamada, confira as tags persistidas com task get --raw. Para IDs personalizados, use o ID interno retornado pela tarefa nessa leitura.

Exemplos:

Adicione uma tag pelo ID interno:

1
clickupfy task add-tag task-1 bug

Preserve um nome com espaço e acento:

1
clickupfy task add-tag task-1 "em revisão"

Use o workspace do perfil ativo com um ID personalizado:

1
clickupfy task add-tag DEV-42 backend --custom-task-id

Selecione o perfil para uma tarefa de outro workspace:

1
clickupfy --account produto task add-tag task-2 documentação

Capture o resultado em um script e consulte a tarefa:

1
clickupfy --json task add-tag task-1 "QA / revisão"
2
clickupfy task get task-1 --raw

O endpoint usado é Add Tag To Task, com POST /task/{task_id}/tag/{tag_name}. Nomes e IDs são codificados na URL, IDs personalizados enviam custom_task_ids=true e team_id na query.

Gestão do catálogo de tags

As operações usam o perfil ativo ou --account no CLI e account no MCP. A API key precisa ter acesso ao Space ou à tarefa. Falhas do ClickUp são propagadas, no MCP, retornam isError: true. Ferramentas de escrita não ficam disponíveis em modo somente leitura. O MCP aceita spaceId ou usa o Space fixado na configuração, o CLI exige --space nos comandos tag.

clickupfy tag list --space <id>

Lista nomes e cores das tags de um Space. A saída JSON é um array, o terminal mostra uma tabela. A consulta não altera tags.

spaceId é string, opcional quando o MCP fixa o Space. No CLI, --space é obrigatório.

Exemplos:

1
clickupfy tag list --space 123

1
clickupfy --json tag list --space 123

1
clickupfy --account dev tag list --space 123

1
clickupfy --account produto --json tag list --space 456

1
clickupfy --json tag list --space 456 > tags.json

Após uma escrita, consulte tag list --space <id> para conferir o catálogo ou task get <task-id> --raw para conferir as associações da tarefa.

clickupfy tag create <name> --space <id>

Cria uma tag no catálogo do Space com nome e cores. Retorna created, spaceId e name. A associação a tarefas é feita separadamente com task add-tag.

name, foreground e background são strings obrigatórias. As cores usam #RRGGBB. No CLI, use --foreground e --background. Nome vazio e cores inválidas são recusados.

Exemplos:

1
clickupfy tag create bug --space 123 --foreground "#ffffff" --background "#cc0000"

1
clickupfy tag create "em revisão" --space 123 --foreground "#000000" --background "#ffcc00"

1
clickupfy --json tag create backend --space 123 --foreground "#ffffff" --background "#112233"

1
clickupfy --account produto tag create documentação --space 456 --foreground "#ffffff" --background "#336699"

1
clickupfy tag create "QA / revisão" --space 123 --foreground "#ffffff" --background "#663399"

Após uma escrita, consulte tag list --space <id> para conferir o catálogo ou task get <task-id> --raw para conferir as associações da tarefa.

clickupfy tag update <tag> --space <id>

Renomeia a tag ou altera suas cores no Space. Consulta a definição atual e preserva os campos omitidos. Retorna updated, spaceId e name. Tag ausente e atualização sem campos são recusadas.

tagName é o nome atual obrigatório, no CLI, é o argumento <tag>. name, foreground e background são strings opcionais, com pelo menos um campo informado. No CLI, use --name, --foreground e --background.

Exemplos:

1
clickupfy tag update bug --space 123 --name defeito

1
clickupfy tag update bug --space 123 --foreground "#ffffff"

1
clickupfy tag update bug --space 123 --background "#cc0000"

1
clickupfy tag update "em revisão" --space 123 --name revisada --background "#00aa00"

1
clickupfy --account produto --json tag update backend --space 456 --foreground "#ffffff" --background "#112233"

Após uma escrita, consulte tag list --space <id> para conferir o catálogo ou task get <task-id> --raw para conferir as associações da tarefa.

clickupfy tag delete <tag> --space <id>

Exclui a tag do Space. Consulte as tarefas que a utilizam antes de executar essa alteração. Retorna deleted, spaceId e name. Para remover somente a associação a uma tarefa, use task remove-tag.

tagName é string obrigatória. No MCP, confirm: true é obrigatório. No CLI, --yes dispensa o prompt, sem terminal interativo, a confirmação precisa ser explícita. O cliente consulta a definição da tag para enviar o corpo DELETE exigido pela API.

Exemplos:

1
clickupfy tag delete bug --space 123 --yes

1
clickupfy tag delete "em revisão" --space 123 --yes

1
clickupfy --json tag delete backend --space 123 --yes

1
clickupfy --account produto tag delete documentação --space 456 --yes

1
clickupfy tag delete "QA / revisão" --space 123 --yes

Após uma escrita, consulte tag list --space <id> para conferir o catálogo ou task get <task-id> --raw para conferir as associações da tarefa.

clickupfy task remove-tag <task-id> <tag>

Remove uma tag da tarefa e mantém a definição no Space. Retorna removed, taskId e tagName. As outras associações da tarefa permanecem intactas.

taskId e tagName são strings obrigatórias. customTaskId é boolean opcional, desativado por padrão, no CLI, use --custom-task-id. IDs personalizados usam o workspace do perfil.

Exemplos:

1
clickupfy task remove-tag task-1 bug

1
clickupfy task remove-tag task-1 "em revisão"

1
clickupfy task remove-tag DEV-42 backend --custom-task-id

1
clickupfy --account produto --json task remove-tag task-2 documentação

1
clickupfy task remove-tag sub-1 "QA / revisão"

Após uma escrita, consulte tag list --space <id> para conferir o catálogo ou task get <task-id> --raw para conferir as associações da tarefa.