asnx: Asana CLI
asnx <entity> <action> [<gid>] [--flags...]
CLI는 항상 평면적(flat)입니다: asnx <entity> <action>. 하위 리소스와 동사 액션은 명시적으로 유지됩니다. 예를 들어 asnx tasks subtasks, asnx tasks create-subtasks, asnx tasks add-followers와 같습니다.
스키마 인트로스펙션(introspection)을 위해 asnx describe [<entity> [<action>]]를 사용하세요.
인증(Auth)
해결 순서: --account <name> > ASANA_TOKEN 환경 변수 > 저장된 단일 계정.
asnx auth status는 확인된 토큰을 API에 대해 검증합니다. 401 오류 진단에 사용하세요.
입력(Input)
쓰기(writes)는 개별 플래그 또는 원시 JSON 본문을 허용합니다. 충돌 시 --json이 우선합니다.
asnx tasks create --json '{"name":"bugfix","projects":["def"]}'
--json은 전체 Asana { "data": ... } 봉투가 아닌, 원시 요청 필드만 예상합니다.
출력(Output)
성공적인 명령은 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입니다.
규칙(Rules)
--dry-run을 사용하여 쓰기 전에 미리보기를 확인하세요.- GET 요청에는
--opt-fields를 사용하여 응답을 작게 유지하세요. - 페이지네이션은 수동입니다:
meta.nextPage를 확인하고--offset으로 전달하세요. - GID를 추측하지 말고 먼저 조회하세요.
asnx workspaces list로 시작한 다음, 예:asnx tasks search <workspace-gid> --text "bugfix". - 엔티티 명령이 unknown으로 반환되면 스키마 캐시가 없는 것입니다:
asnx schema update를 실행하세요. - 점으로 구분된 Asana 필터는 CLI에서도 점을 유지합니다. 예:
--projects.any또는--due-on.before.
주의사항(Gotchas)
start_on은due_on이 필요합니다: 항상 함께 보내세요.me는 위치 기반 GID 별칭이지 액션이 아닙니다.users me대신users get me를 사용하세요.tasks for-project는 기본적으로 완료된 작업을 포함한 모든 작업을 반환합니다. 완료되지 않은 작업만 얻으려면--completed-since <recent-timestamp>(예: now)를 전달하세요. Asana는 그 시점 이후로 완료되지 않았거나 완료된 작업을 반환합니다.tasks duplicate및projects duplicate는 모든 연결 관계를 가져오지 않습니다. 복제된 작업은--include로 복사할 요소(예:--include projects,subtasks,assignee)를 지정하지 않으면 프로젝트 멤버십이 없습니다(projects: []).stories for-task및stories for-goal은 댓글과 시스템 이벤트를 함께 반환합니다. 댓글은"type": "comment"인 항목입니다. 클라이언트 측에서 필터링하세요.tasks search는 최종적 일관성(eventually-consistent)을 가집니다. 최근 쓰기는tasks get또는tasks for-project로 확인하고search로 확인하지 마세요.attachments create는 Asana 측에서 multipart이며 이 CLI는 JSON 전용입니다. 액션은 표시되지만 항상 실패합니다. 파일 업로드는 원시 API를 사용하세요.project-briefs create-for-project는 일반--text를Rich text should be wrapped in <body> tag.와 함께 거부할 수 있습니다. 그런 경우--html-text '<body>...</body>'로 재시도하세요.<entity> remove-members --members me(포트폴리오, 프로젝트, 목표, 팀)는 자신의 접근 권한을 취소합니다.