asnx: Asana CLI
asnx <entity> <action> [<gid>] [--flags...]
CLI 始终保持扁平结构:asnx <entity> <action>。子资源和动词操作保持显式,例如 asnx tasks subtasks、asnx tasks create-subtasks 和 asnx tasks add-followers。
使用 asnx describe [<entity> [<action>]] 进行模式自省。
认证
优先级:--account <name> > ASANA_TOKEN 环境变量 > 单一已存储账户。
asnx auth status 会验证已解析的令牌是否有效;用于诊断 401 错误。
输入
写入操作接受单个参数标志或原始 JSON 体。如果同时指定,--json 优先级更高。
asnx tasks create --json '{"name":"bugfix","projects":["def"]}'
--json 只接受原始请求字段,不包含完整的 Asana { "data": ... } 封装。
输出
成功执行的命令会输出包含 meta 和 data 的 JSON 信封:
{
"meta": {
"command": "tasks.list",
"status": 200,
"nextPage": null
},
"data": [ ... ]
}
meta.command始终是entity.action(一个点),例如tasks.list、tasks.subtasks或project-briefs.create-for-project。data是解包后的 Asana 载荷:单个资源为对象,列表为数组。meta.nextPage是分页偏移量(字符串)或null。将其作为--offset传递。
错误信息输出到 stderr,格式为 {"error":{"status":...,"message":...,"help":...}}。对于本地错误(用法、传输),status 为 null。发生错误时退出码始终为 1。
规则
- 在发送写入操作前,使用
--dry-run进行预览。 - 在 GET 请求中使用
--opt-fields以保持响应小巧。 - 分页是手动的:检查
meta.nextPage,并作为--offset传递。 - 不要猜测 GID,先进行查询。从
asnx workspaces list开始,然后例如asnx tasks search <workspace-gid> --text "bugfix"。 - 如果实体命令返回未知,说明模式缓存缺失:运行
asnx schema update。 - 带点的 Asana 过滤器在 CLI 中保持带点形式,例如
--projects.any或--due-on.before。
注意事项
start_on需要due_on:始终一起发送。me是位置参数 GID 的别名,不是动作。使用users get me,而不是users me。tasks for-project默认返回所有任务,包括已完成的。要仅获取未完成的任务,请传递--completed-since <最近的时间戳>(例如当前时间);Asana 随后会返回在该时间之后未完成或已完成的任务。tasks duplicate和projects duplicate不会复制所有关联。重复的任务默认没有项目成员资格(projects: []),除非你传递--include指定要复制的元素,例如--include projects,subtasks,assignee。stories for-task和stories for-goal同时返回评论和系统事件。评论是那些"type": "comment"的条目;需要在客户端过滤。tasks search是最终一致性的。请使用tasks get或tasks for-project验证最近的写入,而非search。attachments create在 Asana 端是多部分上传,此 CLI 仅支持 JSON;该动作会显示但始终失败。请使用原始 API 进行文件上传。project-briefs create-for-project可能会拒绝纯--text,提示“Rich text should be wrapped in tag.”。如果发生这种情况,请使用--html-text '<body>...</body>'重试。<entity> remove-members --members me(适用于组合、项目、目标、团队)会撤销你自己的访问权限。