CLI 시작하기

goaltrack 은 GitHub CLI(gh)를 본뜬 명령줄 도구입니다. 웹에서 쓰는 것과 같은 권한으로 이슈를 보고·만들고·고치고, 위키 문서를 마크다운 파일로 내려받아 고쳐 올립니다. Claude Code · Codex · Cursor 같은 AI 코딩 툴은 이 CLI 를 셸에서 불러 같은 일을 합니다. 화면에서 못 하는 일은 CLI 로도 못 합니다.

설치

npm 배포를 준비하고 있습니다. 배포되면 이 자리에 설치 명령이 나옵니다. 그 전에는 남이 같은 이름으로 올린 패키지가 설치될 수 있으니npm 으로 goaltrack 을 설치하지 마세요.

Node 20 이상이 필요하고, 설치 스크립트는 없습니다.

워크스페이스 고르기: -W <slug> · GOALTRACK_WORKSPACE · goaltrack workspace set-default <slug>.
자체 운영 서버: --hostname gt.example.com 또는 GOALTRACK_HOST. 호스트마다 로그인이 따로입니다.
무인 실행(CI·서버): 설정 › API 에서 발급한 개인 키(gtk_)를 GOALTRACK_TOKEN 에 넣습니다. goaltrack auth token 이 내는 값은 1시간 뒤 만료되니 무인 실행에 쓰지 마세요.
토큰은 OS 자격증명 저장소(macOS 키체인 · Windows 자격 증명 관리자 · Linux Secret Service)에 둡니다. 저장소가 없으면 설정 디렉터리의 파일(권한 0600)에 저장하고 경고를 한 줄 냅니다.

자주 쓰는 명령

하려는 일	명령
내 이슈 보기	`goaltrack issue list --assignee @me`
이슈 자세히(댓글 포함)	`goaltrack issue view ENG-42 --comments`
이슈 만들기	`goaltrack issue create -t "제목" --team ENG`
상태·라벨 바꾸기	`goaltrack issue edit ENG-42 --status "In Review" --add-label backend`
댓글 달기 · 닫기	`goaltrack issue comment ENG-42 -b "…"` · `goaltrack issue close ENG-42`
위키 문서 찾기 · 내려받기	`goaltrack doc search "결제"` · `goaltrack doc view payments-spec > spec.md`
위키 문서 고쳐 올리기	`goaltrack doc edit payments-spec --body-file spec.md --expected-version 7`
프로젝트·이니셔티브 만들기	`goaltrack initiative create -t "2027 상반기 결제"` · `goaltrack project create -t "결제 v2" --initiative "2027 상반기 결제" --target-date 2027-03-31`
프로젝트 고치기	`goaltrack project edit "결제 v2" --status active --lead @me`
마일스톤 만들기 · 보기	`goaltrack milestone create -p "결제 v2" -t "베타"` · `goaltrack milestone list -p "결제 v2"`
이슈를 프로젝트·마일스톤에 잇기	`goaltrack issue edit ENG-42 -p "결제 v2" --milestone "베타"`
같은 REST 를 직접	`goaltrack api work_items -q '.items[0].short_id'`

본문을 통째로 바꾸는 쓰기는 --expected-version N(값 = view --json version) 또는 --force 가 있어야 합니다 — 읽은 뒤 누군가 고쳤으면 덮지 않고 VERSION_CONFLICT 로 끝납니다. 마일스톤은 프로젝트 안에 있어 milestone 명령과 --milestone 은 그 프로젝트(-p)에서 이름을 찾습니다 — 못 찾거나 같은 이름이 둘이면 종료 코드 1 과 후보 목록을 냅니다. 지우는 명령은 없습니다. -F 는 --body-file 의 짧은 이름입니다(- 를 주면 표준 입력). 전체 명령은 goaltrack help 로 봅니다.

`--json` 필드

터미널이 아니면(파이프 · 리다이렉트 · AI 툴의 셸) 머리 줄 없이 탭으로 나눈 한 줄 한 행을 냅니다. 기계가 읽을 때는 --json <필드> 를 쓰세요 — 필드 없이 --json 만 주면 쓸 수 있는 필드 목록이 나옵니다. -q '<jq 식>' 로 거를 수 있습니다.

대상	필드
issue	`key` · `id` · `url` · `title` · `body` · `status` · `statusType` · `priority` · `assignee` · `team` · `labels` · `project` · `milestone` · `cycle` · `parent` · `createdAt` · `updatedAt` · `version` · `comments`
doc	`id` · `slug` · `url` · `title` · `body` · `space` · `parent` · `createdAt` · `updatedAt` · `version`
project · initiative	`id` · `url` · `name` · `status` · `lead` · `targetDate` · `updatedAt` · `version`
milestone	`id` · `name` · `status` · `targetDate` · `project` · `issueCount` · `doneIssueCount` · `updatedAt` · `version`
workspace	`slug` · `name` · `role` · `isDefault` · `cliAllowed`

comments 는 issue view 에서만 씁니다.

종료 코드

코드	뜻
`0`	성공
`1`	실패 — stderr 첫 줄이 `error: <CODE>: <message>` 이고 `<CODE>` 는 에러 코드 그대로입니다
`2`	취소(Ctrl-C)
`4`	로그인 필요(토큰 없음 · 끊긴 연결)

서버 응답이 없거나 CLI 가 스스로 멈출 때의 <CODE>:

코드	뜻 · 할 일
`RATE_LIMITED`	요청 한도에 걸렸습니다(CLI 가 이미 두 번 기다렸다 다시 보냈습니다). 다음 줄의 초만큼 기다린 뒤 다시 실행합니다
`REQUEST_TIMEOUT`	읽기 요청에 응답이 오지 않았습니다. 그대로 다시 실행해도 됩니다
`REQUEST_TIMEOUT_UNCONFIRMED`	쓰기 요청에 응답이 오지 않았거나 응답이 중간에 끊겼습니다 — 서버가 이미 처리했을 수 있습니다. 결과를 확인한 뒤 다시 보냅니다(같은 이슈·댓글이 두 번 생길 수 있습니다)
`NETWORK_ERROR`	서버에 연결하지 못했습니다
`HTTP_<status>`	서버가 분기할 수 있는 코드를 주지 않은 실패입니다(예: HTTP_404) — 상태 코드로 판단합니다
`USAGE`	사용법 오류 — 서버를 부르지 않았습니다. 인자를 받지 않는 명령(list · create …)에 인자를 주거나, 키 하나만 받는 명령(issue view · issue comment · doc view · doc edit · workspace set-default · api)에 둘 이상을 준 것도 여기입니다. 여러 키는 issue edit · close · reopen 이 받습니다
`FILE_NOT_READABLE`	-F 파일 · goaltrack api 의 @파일 · --input 파일을 읽지 못했습니다
`NO_TEAM`	팀이 없는 워크스페이스에서 issue create — 웹에서 팀을 먼저 만듭니다

환경 변수

이름	뜻
`GOALTRACK_TOKEN`	저장된 로그인보다 앞서는 토큰(무인 실행 = 개인 키 `gtk_`). `GOALTRACK_HOST` 가 없으면 goaltrack.dyld.kr 에만 보냅니다
`GOALTRACK_HOST`	서버(기본 goaltrack.dyld.kr)
`GOALTRACK_WORKSPACE`	워크스페이스 slug
`GOALTRACK_PROMPT_DISABLED`	터미널에서도 묻지 않습니다
`GOALTRACK_DEBUG=api`	요청·응답 줄을 stderr 로(토큰은 앞 8자만)
`NO_COLOR`	색을 끕니다

AI 코딩 툴에 붙일 안내

npm 배포 뒤에 여기에 안내 단락이 나옵니다. 프로젝트의 CLAUDE.md 나 AGENTS.md 에 붙여 넣어 AI 코딩 툴이 CLI 를 바르게 쓰게 하는 단락입니다.

연결 보기 · 끊기

설정 › 개발 도구 연결 에 내 CLI 로그인이 보입니다. [끊기] 를 누르거나 터미널에서 goaltrack auth logout 을 실행하면 다음 요청부터 로그인이 풀립니다(종료 코드 4).

연결한 도구는 내 권한으로 이슈·문서·프로젝트·이니셔티브·마일스톤을 읽고(쓰기를 허용했으면 바꾸고) 그 내용을 자기 쪽으로 가져갑니다. 가져간 데이터를 어떻게 다루는지는 그 도구의 정책을 따릅니다 — 믿는 도구만 연결하고, 쓰지 않는 연결은 끊으세요. 워크스페이스 소유자·관리자는 설정 › 개발 도구 연결 에서 멤버의 연결을 보고 끊거나, 워크스페이스 전체의 연결을 끌 수 있습니다.