Getting started with the CLI

goaltrack is a command-line tool modeled on the GitHub CLI (gh). With the same permissions you have on the web, you view, create and update issues, and you download wiki pages as Markdown files, edit them, and upload them again. AI coding tools such as Claude Code, Codex and Cursor call this CLI from the shell to do the same. Anything you can’t do in the app, you can’t do with the CLI either.

Install

The npm release is being prepared. The install command will appear here once it is published. Until then, don't installgoaltrack with npm — a package someone else uploads under the same name could be installed.

Requires Node 20 or later. There are no install scripts.

Sign-in instructions will appear here after the npm release. You confirm a code in your browser and allow it (device authorization), and one sign-in covers every workspace you belong to.

Choosing a workspace: -W <slug> · GOALTRACK_WORKSPACE · goaltrack workspace set-default <slug>.
Self-hosted servers: --hostname gt.example.com or GOALTRACK_HOST. Each host has its own sign-in.
Unattended runs (CI · servers): put a personal key (gtk_) from Settings › API in GOALTRACK_TOKEN. The value printed by goaltrack auth token expires after 1 hour, so don’t use it for unattended runs.
Tokens are kept in the OS credential store (macOS Keychain · Windows Credential Manager · Linux Secret Service). Without one, the CLI stores them in a file in the config directory (permissions 0600) and prints a one-line warning.

Common commands

What you want to do	Command
See my issues	`goaltrack issue list --assignee @me`
Issue details (with comments)	`goaltrack issue view ENG-42 --comments`
Create an issue	`goaltrack issue create -t "Title" --team ENG`
Change status or labels	`goaltrack issue edit ENG-42 --status "In Review" --add-label backend`
Comment · close	`goaltrack issue comment ENG-42 -b "…"` · `goaltrack issue close ENG-42`
Find · download a wiki page	`goaltrack doc search "payments"` · `goaltrack doc view payments-spec > spec.md`
Upload an edited wiki page	`goaltrack doc edit payments-spec --body-file spec.md --expected-version 7`
Create an initiative · project	`goaltrack initiative create -t "H1 2027 payments"` · `goaltrack project create -t "Payments v2" --initiative "H1 2027 payments" --target-date 2027-03-31`
Edit a project	`goaltrack project edit "Payments v2" --status active --lead @me`
Create · list milestones	`goaltrack milestone create -p "Payments v2" -t "Beta"` · `goaltrack milestone list -p "Payments v2"`
Put an issue in a project and milestone	`goaltrack issue edit ENG-42 -p "Payments v2" --milestone "Beta"`
Call the same REST API directly	`goaltrack api work_items -q '.items[0].short_id'`

Writes that replace a whole body need --expected-version N (value = view --json version) or --force — if someone changed it after you read it, the CLI stops with VERSION_CONFLICT instead of overwriting. Milestones live inside a project, so milestone commands and --milestone look the name up in that project (-p) — if it is not found or two share the name, the CLI exits 1 with the candidates. There are no delete commands. -F is the short form of --body-file (- reads standard input). See every command with goaltrack help.

`--json` fields

Outside a terminal (pipes · redirects · an AI tool’s shell) the CLI prints tab-separated rows, one per line, without a header. When a machine reads the output, use --json <fields> — --json with no fields lists the available fields. Filter with -q '<jq expression>'.

Target	Fields
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 works only with issue view.

Exit codes

Code	Meaning
`0`	Success
`1`	Failure — the first stderr line is `error: <CODE>: <message>`, where `<CODE>` is the error code as is
`2`	Cancelled (Ctrl-C)
`4`	Sign-in required (no token · disconnected)

<CODE> values when the server did not answer, or the CLI stopped on its own:

Code	Meaning · what to do
`RATE_LIMITED`	Rate limited (the CLI already waited and retried twice). Wait the seconds shown on the next line, then run it again
`REQUEST_TIMEOUT`	A read got no response. Running it again is safe
`REQUEST_TIMEOUT_UNCONFIRMED`	A write got no response, or the response was cut off — the server may already have applied it. Check the result before sending it again (otherwise the same issue or comment can be created twice)
`NETWORK_ERROR`	Could not connect to the server
`HTTP_<status>`	The server failed without a code you can branch on (e.g. HTTP_404) — decide by the status code
`USAGE`	Wrong usage — the server was not called. Includes giving arguments to a command that takes none (list · create …) and more than one key to a command that takes one (issue view · issue comment · doc view · doc edit · workspace set-default · api). issue edit · close · reopen take several keys
`FILE_NOT_READABLE`	Could not read the file given to -F, to @file in goaltrack api, or to --input
`NO_TEAM`	issue create in a workspace with no team — create a team in the web app first

Environment variables

Name	Meaning
`GOALTRACK_TOKEN`	Token that overrides saved credentials (unattended runs = personal key `gtk_`). Sent only to goaltrack.dyld.kr unless `GOALTRACK_HOST` is set
`GOALTRACK_HOST`	Server (default goaltrack.dyld.kr)
`GOALTRACK_WORKSPACE`	Workspace slug
`GOALTRACK_PROMPT_DISABLED`	Never prompt, even in a terminal
`GOALTRACK_DEBUG=api`	Print request and response lines to stderr (tokens truncated to 8 characters)
`NO_COLOR`	Turn off color

Guidance for AI coding tools

The guidance paragraph will appear here after the npm release. It is the paragraph you paste into your project's CLAUDE.md or AGENTS.md so AI coding tools use the CLI correctly.

See and disconnect connections

Your CLI sign-in appears under Settings › Developer tool connections. Click [Disconnect], or run goaltrack auth logout in the terminal, and the next request is signed out (exit code 4).

A connected tool reads issues, pages, projects, initiatives and milestones with your permissions (and changes them if you allowed writes) and takes that content to its side. How it handles that data follows the tool’s own policy — connect only tools you trust, and disconnect the ones you no longer use. Workspace owners and admins can see and disconnect members’ connections, or turn connections off for the whole workspace, under Settings › Developer tool connections.