project-tool (plane-workitem-cli)

A production-ready CLI tool that integrates with Plane to create work items (tickets) directly from your terminal.

📦 Installation

npm install -g plane-workitem-cli

🔐 Login

If you need to re-authenticate or set up credentials later:

project-tool login

This will prompt for your Plane PAT and workspace slug, then save the config.

🚀 First Time Setup

On first run, the tool will automatically prompt you for:

1. Plane Personal Access Token (PAT)
   Generate one from: Plane → Profile Settings → API Tokens

2. Workspace Slug
   Your Plane workspace identifier (e.g., my-team)

3. Project Selection
   The tool fetches all projects in your workspace and lets you search/select one interactively.

Configuration is saved to ~/.project-tool.json.

📖 Commands

Create a Ticket

project-tool create-ticket -t "Bug: Login fails" -d "User cannot login with Google"

Flags:

• -t, --title — Title (required)
• -d, --description — Description (optional)

Output:

Success! Work item ID: abc123-def456

Switch Project

project-tool set-project

Re-opens the searchable project selector to choose a different project.

Change Workspace

project-tool set-workspace

Prompts for a new workspace slug and resets project selection.

View Configuration

project-tool whoami

Shows current config with masked token:

Token: plan****1234
Workspace: my-team
Project: abc123-def456

Logout

project-tool logout

Deletes the config file (~/.project-tool.json).

🔧 Configuration

Stored at ~/.project-tool.json:

{
  "token": "plane_api_xxx",
  "workspaceSlug": "my-team",
  "projectId": "selected_project_id"
}

📋 Requirements

• Node.js ≥ 18.x
• Plane account with API access

🛠️ Development

git clone https://github.com/yourusername/project-tool.git
cd project-tool
npm install
npm link  # Enables local `project-tool` command

📄 License

MIT