Communitygithub.com

mwpryer/asnx

⚡ CLI de Asana con prioridad en agentes e introspección de esquemas

¿Qué es asnx?

asnx es una interfaz de línea de comandos para Asana diseñada específicamente para su uso por parte de agentes de IA como Claude Code, Cursor o Codex. Ofrece un sistema de comandos plano y predecible (`asnx <entidad> <acción>`) que elimina las ambigüedades típicas de una API REST. Su funcionalidad principal incluye la introspección del esquema completo de la API de Asana mediante `asnx describe`, autenticación flexible con resolución automática de tokens, y paginación explícita pero controlada manualmente. Es especialmente útil para que un agente pueda explorar, obtener y modificar datos de Asana (tareas, proyectos, espacios de trabajo, usuarios, metas, etc.) sin necesidad de conocer la API de antemano. El CLI maneja entradas mediante banderas o JSON en bruto y siempre devuelve una envoltura JSON estructurada con metadatos y datos. La documentación incluye casos especiales y advertencias prácticas para evitar errores comunes como la dependencia de consistencia eventual en búsquedas o la necesidad de enviar campos juntos.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add mwpryer/asnx

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

asnx: Asana CLI

asnx <entidad> <acción> [<gid>] [--banderas...]

El CLI siempre es plano: asnx <entidad> <acción>. Las acciones de sub-recursos y verbos se mantienen explícitas, por ejemplo asnx tasks subtasks, asnx tasks create-subtasks y asnx tasks add-followers.

Usa asnx describe [<entidad> [<acción>]] para introspección del esquema.

Autenticación

Resolución: --account <nombre> > variable de entorno ASANA_TOKEN > cuenta única almacenada.

asnx auth status verifica el token resuelto contra la API; úsalo para diagnosticar errores 401.

Entrada

Las escrituras aceptan banderas individuales o un cuerpo JSON en bruto. --json gana en caso de conflicto.

asnx tasks create --json '{"name":"corrección","projects":["def"]}'

--json espera solo los campos de solicitud en bruto, no un envoltorio completo de Asana como { "data": ... }.

Salida

Los comandos exitosos emiten un envoltorio JSON con meta y data:

{
  "meta": {
    "command": "tasks.list",
    "status": 200,
    "nextPage": null
  },
  "data": [ ... ]
}
  • meta.command es siempre entidad.acción (un punto), por ejemplo tasks.list, tasks.subtasks, o project-briefs.create-for-project.
  • data es la carga útil de Asana sin envolver: objeto para recursos individuales, arreglo para listas.
  • meta.nextPage es un desplazamiento de paginación (cadena) o null. Pásalo como --offset.

Los errores van a stderr como {"error":{"status":...,"message":...,"help":...}}. status es null para errores locales (uso, transporte). El código de salida siempre es 1 en caso de error.

Reglas

  • Usa --dry-run para previsualizar escrituras antes de enviarlas.
  • Usa --opt-fields en solicitudes GET para mantener las respuestas pequeñas.
  • La paginación es manual: verifica meta.nextPage, pásalo como --offset.
  • No adivines GID, consulta primero. Empieza con asnx workspaces list, luego por ejemplo asnx tasks search <workspace-gid> --text "corrección".
  • Si los comandos de entidad aparecen como desconocidos, falta la caché del esquema: ejecuta asnx schema update.
  • Los filtros con puntos de Asana se mantienen con puntos en el CLI, por ejemplo --projects.any o --due-on.before.

Casos especiales

  • start_on requiere due_on: envíalos siempre juntos.
  • me es un alias posicional de GID, no una acción. Usa users get me, no users me.
  • tasks for-project devuelve todas las tareas, incluidas las completadas, por defecto. Para obtener solo tareas incompletas, pasa --completed-since <timestamp-reciente> (por ejemplo, ahora); Asana entonces devuelve tareas que están incompletas o que se completaron desde ese momento.
  • tasks duplicate y projects duplicate no transfieren todas las asociaciones. Una tarea duplicada vuelve sin membresía de proyecto (projects: []) a menos que pases --include nombrando los elementos a copiar, por ejemplo --include projects,subtasks,assignee.
  • stories for-task y stories for-goal devuelven comentarios y eventos del sistema juntos. Los comentarios son las entradas con "type": "comment"; filtra del lado del cliente.
  • tasks search es eventualmente consistente. Verifica escrituras recientes con tasks get o tasks for-project, no con search.
  • attachments create es multipart en el lado de Asana y este CLI solo maneja JSON; la acción se muestra pero siempre falla. Usa la API sin procesar para cargas de archivos.
  • project-briefs create-for-project puede rechazar --text plano con Rich text should be wrapped in <body> tag. Si eso ocurre, reintenta con --html-text '<body>...</body>'.
  • <entidad> remove-members --members me (portfolios, projects, goals, teams) revoca tu propio acceso.

Skills relacionados