Paean CLI

Connect your local development environment with Paean AI cloud for intelligent task management and AI agent workflows.

Paean CLI is a dual-mode command-line tool that serves both as:

• A human-friendly CLI for developers to manage tasks and authenticate
• An MCP (Model Context Protocol) server for AI agent integration with Cursor, Claude Code, and other AI coding assistants

Features

• Task Management: View, create, complete, and manage tasks from the command line
• MCP Server Mode: Seamless integration with AI coding assistants via MCP protocol
• Dual Authentication: Support for both QR code login and browser-based OAuth
• Context Generation: Generate context files for AI agents with current task information
• Project Detection: Automatically detects project type and associates tasks

Installation

# Install globally via npm
npm install -g paean

# Or use directly with npx
npx paean --help

Quick Start

1. Authenticate

# Browser-based login (recommended)
paean login

# QR code login (scan with Paean mobile app)
paean login --qr

2. View Tasks

# List all tasks
paean tasks

# List pending tasks only
paean tasks --status pending

# Output as JSON
paean tasks --json

3. Manage Tasks

# Create a new task
paean tasks add "Implement user authentication"

# Complete a task
paean tasks complete <task-id> --summary "Added JWT authentication"

# Update task priority
paean tasks update <task-id> --priority high

4. Generate Context for AI

# Generate context file
paean context

# Output to stdout
paean context --stdout

# Output as JSON
paean context --json

MCP Server Mode

Paean CLI can run as an MCP server, allowing AI coding assistants to read tasks and update their status.

Configure in Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "paean": {
      "command": "npx",
      "args": ["paean", "serve"]
    }
  }
}

Configure in Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "paean": {
      "command": "npx",
      "args": ["paean", "serve"]
    }
  }
}

Available MCP Resources

| Resource URI | Description | | ------------------------- | ------------------------------------ | | paean://tasks/pending | Current pending tasks | | paean://tasks/completed | Recently completed tasks | | paean://tasks/all | All tasks with full details | | paean://context | Full project context | | paean://pending-changes | AI-suggested changes awaiting review |

Available MCP Tools

| Tool | Description | | ----------------------- | ---------------------------------------------- | | paean_complete_task | Mark a task as completed | | paean_create_task | Create a new task (supports subtasks) | | paean_update_task | Update task status/priority | | paean_list_tasks | List tasks with filters (includes subtasks) | | paean_accept_change | Accept an AI-suggested change | | paean_reject_change | Reject an AI-suggested change | | paean_add_subtask | Add a subtask to an existing task | | paean_complete_subtask| Mark a subtask as completed | | paean_update_subtask | Update subtask content or completion status | | paean_delete_subtask | Delete a subtask from a task |

Commands Reference

paean login

Authenticate with Paean AI.

paean login           # Browser-based login
paean login --qr      # QR code login
paean login --check   # Check current auth status

paean logout

Sign out and clear stored credentials.

paean logout
paean logout --force  # Skip confirmation

paean tasks

View and manage tasks.

paean tasks                          # List all tasks
paean tasks --status pending         # Filter by status
paean tasks --priority high          # Filter by priority
paean tasks --json                   # JSON output

paean tasks add "Task description"   # Create task
paean tasks complete <id>            # Complete task
paean tasks update <id>              # Update task
paean tasks delete <id>              # Delete task

paean tasks pending                  # View AI-suggested changes
paean tasks accept <changeId>        # Accept change
paean tasks reject <changeId>        # Reject change

paean context

Generate context file for AI agents.

paean context                    # Write to .paean/context.md
paean context --output custom.md # Custom output path
paean context --json             # JSON format
paean context --stdout           # Print to stdout

paean serve

Start MCP server for AI agent integration.

paean serve           # Start MCP server (stdio)
paean serve --debug   # Enable debug logging

paean validate

Check if current changes satisfy pending tasks.

paean validate                  # Validate pending tasks
paean validate --auto-complete  # Auto-complete validated tasks
paean validate --json           # JSON output

Configuration

Configuration is stored in ~/.paean/config.json:

{
  "token": "your-jwt-token",
  "email": "[email protected]",
  "apiUrl": "https://api.paean.ai",
  "webUrl": "https://app.paean.ai",
  "defaultPriority": "medium",
  "outputFormat": "table"
}

View config path:

paean --config

Programmatic Usage

Paean CLI can also be used as a library:

import {
  qrLogin,
  browserLogin,
  getTodoList,
  completeTodoItem,
  startMcpServer,
} from "paean";

// Authenticate
const result = await browserLogin();
if (result.success) {
  // Get tasks
  const tasks = await getTodoList({ status: "pending" });
  console.log(tasks.data.items);

  // Complete a task
  await completeTodoItem("task-id", "Completed the feature");
}

A2A Workflow

Paean CLI enables an Agent-to-Agent (A2A) workflow:

1. Manager (Paean AI Cloud): Creates and organizes tasks based on business requirements
2. Worker (Claude/Cursor): Reads tasks via MCP, implements changes, reports completion
3. Reviewer (Human): Reviews AI suggestions and approves changes

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Paean AI      │────▶│   Paean CLI     │────▶│  Cursor/Claude  │
│   (Manager)     │     │   (MCP Bridge)  │     │   (Worker)      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │   Create tasks        │   Read via MCP        │
        │                       │   Complete tasks      │
        ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Human (Reviewer)                         │
│              Reviews changes, accepts/rejects suggestions        │
└─────────────────────────────────────────────────────────────────┘

Security

• Local Storage: Credentials are stored locally in ~/.paean/
• Localhost Only: Browser OAuth callbacks only accept localhost URLs
• Token-Based: Uses JWT tokens that expire and can be revoked
• No Password Storage: Passwords are never stored locally

Requirements

• Node.js 18.0.0 or higher
• npm or yarn

Contributing

Contributions are welcome! Please see our contributing guidelines.

License

MIT License - see LICENSE file for details.

Links

• Website: https://paean.ai
• API Documentation: https://api.paean.ai/docs
• Support: [email protected]