GoalPath CLI

Give your AI coding assistant direct access to your GoalPath roadmap, milestones, and items, with automatic project resolution from your repo.

When to use the CLI vs. the hosted server

GoalPath has two MCP connection methods:

• Hosted server (https://goalpath.app/api/mcp): Zero install, works everywhere. Recommended for Claude Desktop, Claude.ai, Claude mobile, and any tool that supports remote MCP.
• CLI (this package): Adds automatic project resolution via .goalpath files and terminal commands. Use it when you want your AI assistant to know which project a repo belongs to without manual configuration.

Both expose the same 26 tools. Use whichever fits your workflow, or both.

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

goalpath project link

Creates a .goalpath file. Commit it so your team shares the same project context. This is the CLI's main advantage over the hosted server: your AI assistant automatically knows which project this codebase belongs to.

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.

If your project has any of CLAUDE.md, AGENTS.md, .cursorrules, or .github/copilot-instructions.md, the command also offers to append a GoalPath section explaining the #GP-N commit-tagging convention. The block is wrapped in <!-- goalpath:start --> markers so re-running the command updates it in place — no duplication, no clobbering your content.

Finally, it prints a one-liner showing how to install the goalpath-skills plugin for richer in-editor workflows.

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 38 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_comments, add_task, 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
• MCP Server & CLI docs
• Support