CLI & MCP Server

GoalPath's CLI does two things: gives you terminal access to your projects, and turns your AI coding assistant into a project-aware collaborator.

When connected, your assistant can see what's assigned, update item status, check off subtasks, and post progress notes — without you switching tabs or copy-pasting item IDs.

Install the CLI

bash

npm install -g @goalpath/cli

Authenticate

bash

goalpath login

Paste your API key when prompted. You can generate one at Profile > API Keys in GoalPath, or go directly to goalpath.app/profile/api-keys.

You can also authenticate non-interactively with `goalpath login --api-key gp_xxxxx` — useful for CI environments or scripted setups.

Link your repository

bash

goalpath project link

This creates a .goalpath file in your repo root. Commit it — when your teammates clone the repo, their CLI and AI assistant will automatically know which GoalPath project this codebase belongs to.

If you work on multiple projects, you can override the linked project with the GOALPATH_PROJECT_ID environment variable.

Connect your AI assistant

The CLI includes an MCP (Model Context Protocol) server that AI assistants use to interact with GoalPath. The fastest way to set it up:

bash

goalpath mcp init

This auto-detects which AI tools you have installed — Claude Code, Claude Desktop, Cursor, VS Code — and adds GoalPath to their MCP configuration. It merges into existing config without overwriting anything.

You can also target a specific tool:

bash

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

If you prefer to configure manually, add this to your tool's MCP config file (`.mcp.json` for Claude Code, `claude_desktop_config.json` for Claude Desktop):

json

{
  "mcpServers": {
    "goalpath": {
      "command": "goalpath",
      "args": ["mcp", "serve"]
    }
  }
}

What your assistant can do

Once connected, your AI assistant has access to 30+ tools. Here are the ones that matter most:

The everyday workflow

What you ask	What happens
"What's assigned to me?"	Calls `list_my_items` — shows your items with status and priority
"Show me the details for this item"	Calls `get_item` — returns the full description, subtasks, and comments
"Start working on the login bug"	Calls `set_item_status` — marks it as Started in GoalPath
"Check off the first subtask"	Calls `check_task` — stakeholders see the checkbox update in real time
"Post a comment with the PR link"	Calls `add_comment` — adds a progress note visible to the whole team
"Mark it as finished"	Calls `set_item_status` — moves it to Finished

Milestones and planning

Your assistant can also list milestones, read PRDs from milestone descriptions, create new items, move items between milestones, and check forecasts. This is especially useful for planning sessions where you want to break a milestone into items without leaving your editor.

Highlights and blockers

When your assistant hits a blocker or has a question about requirements, it can flag items directly:

set_item_highlight("Blocked", "Waiting for API credentials") — flags the item and explains why
set_item_highlight("Question", "Should this support mobile?") — surfaces the question to the team

These show up immediately in GoalPath for stakeholders and teammates to see.

How autonomous agents use it

GoalPath offers a full set of AI skills that turn your assistant into an autonomous collaborator — from discovering ideas to shipping PRs. Here's the workflow when using /goalpath-work or /goalpath-implement:

Picks up an item — reads the description and subtasks
Sets status to Started — the team sees work has begun
Does the coding work — implements the feature or fix
Checks off subtasks — progress is visible in real time, not batched at the end
Posts a comment — links the PR or summarizes what changed
Marks it Finished — signals that the work is ready for review

The result: stakeholders see progress as it happens. No one needs to write a status update or schedule a sync meeting.

CLI commands

For quick terminal access without an AI assistant:

bash

goalpath items --mine              # Your assigned items
goalpath items --status Started    # Filter by status
goalpath items --milestone "v2.1"  # Filter by milestone
goalpath status                    # Project summary
goalpath project list              # All your projects

Configuration reference

Where config lives

File	Purpose	Scope
`~/.goalpath/config.json`	API key, default project	Per user
`.goalpath`	Linked project ID	Per repo (commit this)

Project resolution

When the CLI needs to know which project to use, it checks in this order:

GOALPATH_PROJECT_ID environment variable (highest priority)
.goalpath file in the current directory or any parent
defaultProjectId from ~/.goalpath/config.json

Environment variables

Variable	Purpose
`GOALPATH_API_KEY`	API key (overrides config file)
`GOALPATH_URL`	Base URL (default: goalpath.app)
`GOALPATH_PROJECT_ID`	Project ID (overrides .goalpath file)