Communitygithub.com

asnx

⚡ CLI Asana axé agent, avec introspection de schéma

Qu'est-ce que asnx ?

`asnx` est une interface en ligne de commande (CLI) conçue spécifiquement pour les agents IA, permettant d'interagir avec l'API Asana de manière structurée et prévisible. Son principal atout est l'introspection de schéma : les agents peuvent découvrir les entités, actions et paramètres disponibles via la commande `describe`, sans avoir besoin d'une documentation externe ou d'un code personnalisé. La CLI impose une structure plate (`asnx <entité> <action>`) et gère l'authentification via variable d'environnement `ASANA_TOKEN` ou comptes stockés. Elle produit une sortie JSON uniforme avec des métadonnées (commande, statut, pagination), ce qui permet aux agents de parser facilement les réponses. `asnx` est idéal pour les workflows automatisés où un agent doit créer, lire, mettre à jour ou supprimer des tâches, projets, utilisateurs et autres ressources Asana, en profitant de fonctionnalités comme le mode `--dry-run` pour la prévisualisation, la pagination manuelle via `--offset`, et la gestion des champs optionnels avec `--opt-fields` pour optimiser la bande passante. Son markdown fournit également des conseils pratiques pour éviter les pièges courants (comme la nécessité d'envoyer `due_on` avec `start_on`, ou la différence entre `tasks search` et `tasks for-project` en termes de cohérence des données).

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

asnx : CLI Asana

asnx <entité> <action> [<gid>] [--drapeaux...]

La CLI est toujours plate : asnx <entité> <action>. Les actions de sous-ressource et de verbe restent explicites, par exemple asnx tasks subtasks, asnx tasks create-subtasks et asnx tasks add-followers.

Utilisez asnx describe [<entité> [<action>]] pour l'introspection du schéma.

Authentification

Résolution : --account <nom> > variable d'environnement ASANA_TOKEN > compte stocké unique.

asnx auth status vérifie le jeton résolu auprès de l'API ; utilisez-le pour diagnostiquer les erreurs 401.

Entrée

Les écritures acceptent soit des drapeaux individuels, soit un corps JSON brut. --json l'emporte en cas de conflit.

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

--json attend uniquement les champs bruts de la requête, pas une enveloppe Asana complète { "data": ... }.

Sortie

Les commandes réussies émettent une enveloppe JSON avec meta et data :

{
  "meta": {
    "command": "tasks.list",
    "status": 200,
    "nextPage": null
  },
  "data": [ ... ]
}
  • meta.command est toujours entité.action (un point), par exemple tasks.list, tasks.subtasks, ou project-briefs.create-for-project.
  • data est la charge utile Asana désenveloppée : objet pour les ressources uniques, tableau pour les listes.
  • meta.nextPage est un décalage de pagination (chaîne) ou null. Passez-le en tant que --offset.

Les erreurs vont sur stderr sous la forme {"error":{"status":...,"message":...,"help":...}}. status est null pour les erreurs locales (utilisation, transport). Le code de sortie est toujours 1 en cas d'erreur.

Règles

  • Utilisez --dry-run pour prévisualiser les écritures avant de les envoyer.
  • Utilisez --opt-fields sur les requêtes GET pour garder les réponses légères.
  • La pagination est manuelle : vérifiez meta.nextPage, passez-le en tant que --offset.
  • Ne devinez pas les GID, interrogez d'abord. Commencez par asnx workspaces list, puis par exemple asnx tasks search <workspace-gid> --text "bugfix".
  • Si les commandes d'entité reviennent comme inconnues, le cache de schéma est manquant : exécutez asnx schema update.
  • Les filtres Asana pointés restent pointés sur la CLI, par exemple --projects.any ou --due-on.before.

Pièges

  • start_on nécessite due_on : envoyez toujours les deux ensemble.
  • me est un alias de GID positionnel, pas une action. Utilisez users get me, pas users me.
  • tasks for-project renvoie toutes les tâches, y compris les tâches terminées, par défaut. Pour obtenir uniquement les tâches incomplètes, passez --completed-since <timestamp-récent> (par exemple maintenant) ; Asana renvoie alors les tâches qui sont incomplètes ou qui ont été terminées depuis ce moment.
  • tasks duplicate et projects duplicate ne transfèrent pas toutes les associations. Une tâche dupliquée revient sans appartenance à un projet (projects: []) sauf si vous passez --include en nommant les éléments à copier, par exemple --include projects,subtasks,assignee.
  • stories for-task et stories for-goal renvoient les commentaires et les événements système ensemble. Les commentaires sont les entrées avec "type": "comment" ; filtrez côté client.
  • tasks search est éventuellement cohérent. Vérifiez les écritures récentes avec tasks get ou tasks for-project, pas search.
  • attachments create est multipart du côté d'Asana et cette CLI est uniquement JSON ; l'action apparaît mais échoue toujours. Utilisez l'API brute pour les téléchargements de fichiers.
  • project-briefs create-for-project peut rejeter le --text simple avec Rich text should be wrapped in <body> tag. Si cela se produit, réessayez avec --html-text '<body>...</body>'.
  • <entité> remove-members --members me (portfolios, projets, objectifs, équipes) révoque votre propre accès.

Skills associés