Communitygithub.com

mwpryer/asnx

⚡ Asana-CLI für KI-Agenten mit Schema-Introspection

Was ist asnx?

asnx ist ein speziell für KI-Agenten (z. B. Claude Code, Cursor, Codex) entwickeltes Kommandozeilenwerkzeug für Asana. Es bietet eine flache, konsistente Befehlssyntax (`asnx <entity> <action>`) und unterstützt die automatische Schema-Introspection via `asnx describe`, sodass Agenten die verfügbaren Entitäten und Aktionen eigenständig erkunden können. Die Authentifizierung erfolgt über Umgebungsvariablen (z. B. `ASANA_TOKEN`) oder gespeicherte Konten. Die Ausgabe erfolgt immer als strukturiertes JSON mit Meta-Informationen, was die Weiterverarbeitung durch KI-Agenten erleichtert. Paginierung wird manuell durch `--offset` gesteuert, und es gibt eine `--dry-run`-Option für sichere Schreibvorgänge. Known Issues wie die JSON-only-Beschränkung bei Datei-Uploads oder die `start_on`+`due_on`-Abhängigkeit sind im Dokument dokumentiert.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add mwpryer/asnx

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

asnx: Asana-CLI

asnx <entity> <action> [<gid>] [--flags...]

Die CLI ist immer flach: asnx <entity> <action>. Sub-Ressourcen- und Verb-Aktionen bleiben explizit, z. B. asnx tasks subtasks, asnx tasks create-subtasks und asnx tasks add-followers.

Verwende asnx describe [<entity> [<action>]] für die Schema-Introspection.

Authentifizierung

Auflösung: --account <name> > ASANA_TOKEN-Umgebungsvariable > einzelnes gespeichertes Konto.

asnx auth status überprüft das aufgelöste Token gegen die API; verwende es, um 401-Fehler zu diagnostizieren.

Eingabe

Schreiboperationen akzeptieren entweder einzelne Flags oder einen rohen JSON-Textkörper. --json gewinnt bei Konflikten.

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

--json erwartet nur die rohen Anfragefelder, nicht den vollständigen Asana-{ "data": ... }-Umschlag.

Ausgabe

Erfolgreiche Befehle geben einen JSON-Umschlag mit meta und data aus:

{
  "meta": {
    "command": "tasks.list",
    "status": 200,
    "nextPage": null
  },
  "data": [ ... ]
}
  • meta.command ist immer entity.action (ein Punkt), z. B. tasks.list, tasks.subtasks oder project-briefs.create-for-project.
  • data ist die entpackte Asana-Nutzlast: Objekt für einzelne Ressourcen, Array für Listen.
  • meta.nextPage ist ein Paginierungs-Offset (String) oder null. Übergib es als --offset.

Fehler gehen auf stderr als {"error":{"status":...,"message":...,"help":...}}. status ist null für lokale Fehler (Verwendung, Transport). Der Exit-Code ist bei Fehlern immer 1.

Regeln

  • Verwende --dry-run, um Schreibvorgänge vor dem Senden in der Vorschau anzuzeigen.
  • Verwende --opt-fields bei GET-Anfragen, um Antworten klein zu halten.
  • Paginierung erfolgt manuell: Überprüfe meta.nextPage und übergib es als --offset.
  • Rate keine GIDs, frage zuerst ab. Beginne mit asnx workspaces list, dann z. B. asnx tasks search <workspace-gid> --text "bugfix".
  • Falls Entitätsbefehle als unbekannt zurückkommen, fehlt der Schema-Cache: Führe asnx schema update aus.
  • Gepunktete Asana-Filter bleiben auf der CLI gepunktet, z. B. --projects.any oder --due-on.before.

Fallstricke

  • start_on erfordert due_on: Sende beide immer zusammen.
  • me ist ein positioneller GID-Alias, keine Aktion. Verwende users get me, nicht users me.
  • tasks for-project gibt standardmäßig alle Aufgaben zurück, einschließlich abgeschlossener. Um nur unvollständige Aufgaben zu erhalten, übergib --completed-since <aktueller-Zeitstempel> (z. B. jetzt); Asana gibt dann Aufgaben zurück, die unvollständig sind oder seit diesem Zeitpunkt abgeschlossen wurden.
  • tasks duplicate und projects duplicate übertragen nicht jede Verknüpfung. Eine duplizierte Aufgabe wird ohne Projektmitgliedschaft zurückgegeben (projects: []), es sei denn, du übergibst --include mit den zu kopierenden Elementen, z. B. --include projects,subtasks,assignee.
  • stories for-task und stories for-goal geben Kommentare und Systemereignisse zusammen zurück. Kommentare sind die Einträge mit "type": "comment"; filtere client-seitig.
  • tasks search ist nur eventuell konsistent. Überprüfe aktuelle Schreibvorgänge mit tasks get oder tasks for-project, nicht mit search.
  • attachments create ist auf Asana-Seite Multipart und diese CLI ist nur JSON; die Aktion wird angezeigt, schlägt aber immer fehl. Verwende die rohe API für Datei-Uploads.
  • project-briefs create-for-project kann einfaches --text mit Rich text sollte in ein <body>-Tag eingewickelt sein. ablehnen. Falls das passiert, wiederhole mit --html-text '<body>...</body>'.
  • <entity> remove-members --members me (Portfolios, Projekte, Ziele, Teams) entzieht deinen eigenen Zugriff.

Verwandte Skills