GoalPath CLI

Manage your GoalPath projects from the terminal — and give your AI coding assistant direct access to your roadmap, milestones, and items.

Why

If you use Claude Code, Cursor, or another AI assistant, the GoalPath CLI turns it into a project-aware collaborator. Your assistant can check what's assigned, update item status, add comments, and track progress — all through the MCP protocol.

For humans, the CLI provides quick access to project status, item lists, and milestone overviews without leaving the terminal.

Install

npm install -g @goalpath/cli

Setup

1. Authenticate

goalpath login

Paste your API key from goalpath.app/profile/api-keys.

2. Link your repo (recommended)

goalpath project link

Creates a .goalpath file — commit it so your team shares the same project context.

3. Connect your AI assistant

goalpath mcp init

Auto-detects Claude Code, Claude Desktop, Cursor, and VS Code — adds GoalPath to their MCP config. Run it once and you're set.

You can also target a specific tool:

goalpath mcp init claude-desktop
goalpath mcp init cursor
goalpath mcp init vscode

CLI Commands

goalpath items --mine          # Your assigned items
goalpath items --status Started # Filter by status
goalpath status                # Project summary
goalpath project list          # All your projects
goalpath project link          # Link repo to project
goalpath mcp init              # Configure AI assistant integration
goalpath login --api-key <key> # Authenticate (non-interactive)

MCP Tools

The MCP server gives AI assistants 30+ tools to work with GoalPath directly.

The core workflow:

| Tool | What it does | | -------------------- | -------------------------------------------- | | list_my_items | Items assigned to current user | | get_item | Full item details with subtasks | | set_item_status | Mark items as Started, Finished, etc. | | check_task | Check off subtasks (visible to stakeholders) | | add_comment | Post progress notes or PR links | | set_item_highlight | Flag items as Blocked or Question |

Also available: list_milestones, get_milestone, create_milestone, update_milestone, list_items, search_items, create_item, list_projects, get_project, list_teams, list_comments, add_task, get_velocity_history, get_wip_count, get_milestone_forecast, and more.

How AI assistants use it

Your assistant picks up an item, works through it, and keeps GoalPath updated as it goes:

1. list_my_items() — sees what's assigned
2. get_item(id) — reads the full description and subtasks
3. set_item_status("Started") — marks it in progress
4. does the coding work
5. check_task() — checks off subtasks as they're completed
6. add_comment() — posts the PR link
7. set_item_status("Finished") — marks it done

Stakeholders see progress in real time without anyone writing a status update.

Configuration

User config: ~/.goalpath/config.json

{
  "apiKey": "gp_xxxxxxxxxxxx",
  "baseUrl": "https://goalpath.app",
  "defaultProjectId": "your-project-id"
}

Repo link: .goalpath (commit this)

{ "projectId": "your-project-id" }

Project resolution order:

1. GOALPATH_PROJECT_ID env var
2. .goalpath file in current or parent directory
3. defaultProjectId from user config

Environment variables:

• GOALPATH_API_KEY — overrides config file
• GOALPATH_URL — custom base URL (default: https://goalpath.app)
• GOALPATH_PROJECT_ID — overrides .goalpath and config

Links

• GoalPath
• Documentation
• Support