A schema-driven Asana CLI with first-class AI agent support.
asx is generated from the Asana OpenAPI spec, not hand-written. Commands come straight from the schema, so when Asana ships a new endpoint you can pull it in yourself with asx schema update instead of waiting on a release. Command names follow the spec too, so they change when Asana renames an endpoint, whatever the asx version. The same schema makes the whole surface introspectable, with every command, flag, and response shape described in JSON.
asx was built for agents from the start. --json takes the raw API payload one-to-one. --opt-fields keeps responses from swamping an agent's context. --dry-run shows the exact request before it is sent, and flags are checked against the OpenAPI types, so bad calls fail locally instead of at the API.
Requires Node.js 24+ and an Asana Personal Access Token. To create one, go to My apps in Asana and choose Create new token under Personal access tokens.
npm install -g @mwpryer/asx# Store a named account (token is read from stdin)
asx auth add work
# Or set a token via environment variable
export ASANA_TOKEN=<pat>
# Build the command index
asx schema update
# Interact with Asana
asx tasks search <workspace-gid> --text "bugfix"
asx tasks create --name "migration" --workspace <workspace-gid> --projects <project-gid>Stored accounts live in ~/.config/asx/accounts.json (respects XDG_CONFIG_HOME).
asx ships with an agent skill that gives coding agents the small bit of context they need to drive asx and introspect commands themselves.
npx skills add mwpryer/asxEvery command follows the same shape:
asx <entity> <action> [<gid>] [--flags...]
The CLI stays flat. Sub-resources and verbs are spelled out as their own actions, for example asx tasks subtasks, asx tasks create-subtasks, and asx tasks add-followers.
Use --help at every level to discover what is available:
asx --help
asx tasks --help
asx tasks create --help
asx tasks create-subtasks --helpWhat makes it usable for agents:
- Introspectable.
asx describe [entity] [action]emits the command surface as JSON, so an agent can build a call without scraping--help. - Stable JSON envelope. Every response is JSON on stdout. Errors go to stderr in the same shape.
- Safe planning.
--dry-runreturns the exact HTTP request that would be sent, so the agent can preview before sending. - Schema-validated input. Flags are generated and validated against the OpenAPI types, so bad input is rejected before the request goes out.
--account <name> > ASANA_TOKEN env var > single stored account.
asx auth add <name> reads the token from stdin (input hidden on TTY, pipe-friendly).
| Flag | Description |
|---|---|
--account <name> |
Account to use for this request |
--opt-fields a,b |
Comma-separated fields to return |
--dry-run |
Return the built HTTP request without sending it |
--json '{...}' |
Raw JSON body, merged over value flags (--json wins per key) |
--limit N |
Page size for list commands |
--offset <token> |
Pagination cursor from a previous response |
A value that starts with - needs =, for example --notes="- item".
Commands emit a JSON envelope to stdout on success:
asx tasks search <workspace-gid> --text "migration" --opt-fields name,due_on{
"meta": {
"command": "tasks.search",
"status": 200,
"nextPage": null
},
"data": [ ... ]
}data is the unwrapped Asana payload, either an object for single resources or an array for lists. nextPage is a pagination offset or null; pass it back as --offset.
Errors go to stderr:
{
"error": {
"status": 400,
"message": "...",
"help": "..."
}
}status is null for local errors (usage, transport). The exit code is 1 on any error.

