Communitygithub.com

asnx

⚡ CLI Asana focado em agentes com introspecção de esquema

O que é asnx?

O `asnx` é uma interface de linha de comando (CLI) projetada para interação eficiente com a API do Asana, priorizando o uso por agentes de IA. Sua estrutura plana (`asnx <entidade> <ação>`) facilita a construção programática de comandos, enquanto o comando `asnx describe` fornece introspecção completa de esquemas, permitindo que agentes descubram entidades, ações e parâmetros disponíveis sem documentação externa. O suporte a flags como `--dry-run`, `--json` para entrada de dados e `--opt-fields` para controle de resposta otimiza o fluxo de trabalho. A saída padronizada em JSON, com metadados de comando, paginação via `meta.nextPage` e tratamento de erros estruturado, torna a CLI ideal para automação e integração com ferramentas como Claude Code, Cursor e Codex, que podem invocar o `asnx` para gerenciar tarefas, projetos, e outros recursos do Asana de forma confiável e previsível.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add mwpryer/asnx

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

asnx: CLI Asana

asnx <entidade> <ação> [<gid>] [--flags...]

A CLI é sempre plana: asnx <entidade> <ação>. Ações de sub-recursos e verbos permanecem explícitas, por exemplo asnx tasks subtasks, asnx tasks create-subtasks, e asnx tasks add-followers.

Use asnx describe [<entidade> [<ação>]] para introspecção de esquema.

Autenticação

Resolução: --account <nome> > variável de ambiente ASANA_TOKEN > conta armazenada única.

asnx auth status verifica o token resolvido junto à API; use-o para diagnosticar erros 401.

Entrada

Gravações aceitam flags individuais ou um corpo JSON bruto. --json vence em caso de conflito.

asnx tasks create --json '{"name":"correção","projects":["def"]}'

--json espera apenas campos brutos da requisição, não um envelope completo { "data": ... } do Asana.

Saída

Comandos bem-sucedidos emitem um envelope JSON com meta e data:

{
  "meta": {
    "command": "tasks.list",
    "status": 200,
    "nextPage": null
  },
  "data": [ ... ]
}
  • meta.command é sempre entidade.ação (um ponto), ex.: tasks.list, tasks.subtasks, ou project-briefs.create-for-project.
  • data é o payload não encapsulado do Asana: objeto para recursos únicos, array para listas.
  • meta.nextPage é um offset de paginação (string) ou null. Passe-o como --offset.

Erros vão para stderr como {"error":{"status":...,"message":...,"help":...}}. status é null para erros locais (uso, transporte). O código de saída é sempre 1 em caso de erro.

Regras

  • Use --dry-run para pré-visualizar gravações antes de enviá-las.
  • --opt-fields em requisições GET para manter as respostas enxutas.
  • Paginação é manual: verifique meta.nextPage, passe como --offset.
  • Não adivinhe GIDs, consulte primeiro. Comece com asnx workspaces list, depois, ex.: asnx tasks search <workspace-gid> --text "correção".
  • Se comandos de entidade forem desconhecidos, o cache de esquema está faltando: execute asnx schema update.
  • Filtros pontilhados do Asana permanecem pontilhados na CLI, por exemplo --projects.any ou --due-on.before.

Pegadinhas

  • start_on requer due_on: envie ambos juntos.
  • me é um alias de GID posicional, não uma ação. Use users get me, não users me.
  • tasks for-project retorna todas as tarefas, incluindo as concluídas, por padrão. Para obter apenas tarefas incompletas, passe --completed-since <carimbo-de-tempo-recente> (ex.: agora); o Asana então retorna tarefas que estão incompletas ou foram concluídas desde aquele momento.
  • tasks duplicate e projects duplicate não transferem todas as associações. Uma tarefa duplicada retorna sem associação a projetos (projects: []) a menos que você passe --include nomeando os elementos a copiar, ex.: --include projects,subtasks,assignee.
  • stories for-task e stories for-goal retornam comentários e eventos do sistema juntos. Comentários são as entradas com "type": "comment"; filtre no lado do cliente.
  • tasks search é eventualmente consistente. Verifique gravações recentes com tasks get ou tasks for-project, não com search.
  • attachments create é multipart no lado do Asana e esta CLI é apenas JSON; a ação aparece mas sempre falha. Use a API bruta para uploads de arquivos.
  • project-briefs create-for-project pode rejeitar --text simples com Rich text should be wrapped in <body> tag. Se isso acontecer, tente novamente com --html-text '<body>...</body>'.
  • <entidade> remove-members --members me (portfolios, projetos, metas, equipes) revoga seu próprio acesso.

Habilidades Relacionadas