npm package: @memfoldai/plane-cli
Description: CLI for the Plane project management API, powered by Plane's MCP server
Latest version: 0.1.1

# @memfoldai/plane-cli

A command-line interface for the [Plane](https://plane.so) project management API. Built on top of Plane's official MCP server using [MCPorter](https://github.com/steipete/mcporter).

Provides 113 commands covering projects, work items, cycles, modules, initiatives, epics, milestones, and more.

## Installation

```bash
npm install -g @memfoldai/plane-cli
```

Or run directly with npx:

```bash
npx @memfoldai/plane-cli list-projects
```

## Configuration

The CLI requires two environment variables:

| Variable | Required | Description |
|----------|----------|-------------|
| `PLANE_API_KEY` | Yes | Your Plane API key (Personal Access Token) |
| `PLANE_WORKSPACE_SLUG` | Yes | Your workspace slug identifier |
| `PLANE_BASE_URL` | No | Override for self-hosted instances (defaults to `https://mcp.plane.so/api-key/mcp`) |

### Setup

```bash
export PLANE_API_KEY="your-api-key"
export PLANE_WORKSPACE_SLUG="your-workspace-slug"
```

You can get your API key from your Plane workspace settings under **Settings > API Tokens**.

For self-hosted Plane instances:

```bash
export PLANE_BASE_URL="https://your-plane-instance.com/api-key/mcp"
```

## Usage

```bash
plane-cli <command> [options]
```

### Projects

```bash
# List all projects
plane-cli list-projects

# Create a project
plane-cli create-project --name "My Project" --identifier "MP"

# Get a specific project
plane-cli retrieve-project --project-id <uuid>

# Update a project
plane-cli update-project --project-id <uuid> --name "Renamed Project"

# Delete a project
plane-cli delete-project --project-id <uuid>
```

### Work Items

```bash
# List work items in a project
plane-cli list-work-items --project-id <uuid>

# Create a work item
plane-cli create-work-item --project-id <uuid> --name "Fix login bug"

# Search across workspace
plane-cli search-work-items --query "authentication"

# Get a work item by project identifier and sequence number
plane-cli retrieve-work-item-by-identifier --project-identifier "MP" --sequence-number 42
```

### Cycles

```bash
# List cycles
plane-cli list-cycles --project-id <uuid>

# Create a cycle
plane-cli create-cycle --project-id <uuid> --name "Sprint 1" --start-date "2024-01-01" --end-date "2024-01-14"

# Add work items to a cycle
plane-cli add-work-items-to-cycle --project-id <uuid> --cycle-id <uuid> --work-item-ids item1,item2
```

### Modules

```bash
# List modules
plane-cli list-modules --project-id <uuid>

# Create a module
plane-cli create-module --project-id <uuid> --name "Authentication Module"
```

### Initiatives

```bash
# List initiatives
plane-cli list-initiatives

# Create an initiative
plane-cli create-initiative --name "Q1 Goals"
```

### Users & Workspace

```bash
# Get current user info
plane-cli get-me

# List workspace members
plane-cli get-workspace-members
```

### Output Formats

All commands support output format options:

```bash
# JSON output
plane-cli list-projects --output json

# Markdown output
plane-cli list-projects --output markdown

# Raw MCP envelope
plane-cli list-projects --output raw
```

### Timeout

Override the default 30-second timeout:

```bash
plane-cli list-work-items --project-id <uuid> --timeout 60000
```

## Available Commands

The CLI covers the full Plane API:

- **Projects**: list, create, retrieve, update, delete, members, features, worklog summary
- **Work Items**: list, create, retrieve, update, delete, search, activities, comments, links, relations
- **Work Logs**: list, create, update, delete
- **Cycles**: list, create, retrieve, update, delete, archive/unarchive, manage work items, transfer
- **Modules**: list, create, retrieve, update, delete, archive/unarchive, manage work items
- **Initiatives**: list, create, retrieve, update, delete
- **Intake Work Items**: list, create, retrieve, update, delete
- **Work Item Properties**: list, create, retrieve, update, delete
- **Work Item Types**: list, create, retrieve, update, delete
- **States**: list, create, retrieve, update, delete
- **Labels**: list, create, retrieve, update, delete
- **Epics**: list, create, retrieve, update, delete
- **Milestones**: list, create, retrieve, update, delete, manage work items
- **Workspace**: members, features

Run `plane-cli --help` for the full list.

## Development

### Regenerating the CLI

If Plane adds new API tools, regenerate the CLI source:

```bash
npm run generate
```

This requires `uvx` (Python) and valid `PLANE_API_KEY`/`PLANE_WORKSPACE_SLUG` env vars to connect to the MCP server for schema discovery.

### Building

```bash
npm run build
```

## License

MIT