npm package: @goalpath/cli
Description: GoalPath CLI - manage your projects from the terminal
Author: GoalPath
Latest version: 1.0.1

# 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

```bash
npm install -g @goalpath/cli
```

## Setup

### 1. Authenticate

```bash
goalpath login
```

Paste your API key from [goalpath.app/profile/api-keys](https://goalpath.app/profile/api-keys).

### 2. Link your repo (recommended)

```bash
goalpath project link
```

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

### 3. Connect your AI assistant

```bash
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:

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

## CLI Commands

```bash
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`

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

**Repo link:** `.goalpath` (commit this)

```json
{ "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](https://goalpath.app)
- [Documentation](https://goalpath.app/docs)
- [Support](mailto:hello@goalpath.app)