pcli - Planka CLI

A command-line interface for interacting with the Planka project management API.

Features

• Single binary - No runtime dependencies, just download and run
• JSON-first output - Machine-parseable by default, with optional table format for humans
• Environment-based auth - Configure once via environment variables
• Full CRUD operations - Manage cards, comments, tasks, labels, and more
• Cursor-based pagination - Automatic handling of paginated API responses
• Structured logging - Debug-level HTTP request/response logging available

Installation

From Source

git clone https://git.franklin.lab/steve.cliff/pcli.git
cd pcli
go build -o pcli
sudo mv pcli /usr/local/bin/

Binary Download

Download the latest release from the releases page.

Configuration

pcli requires two environment variables:

• PLANKA_URL - Base URL of your Planka instance (e.g., https://planka.example.com)
• PLANKA_API_KEY - User-level API key for authentication

Setting Environment Variables

export PLANKA_URL="https://planka.example.com"
export PLANKA_API_KEY="D89VszVs_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Or use command-line flags to override:

pcli --url https://planka.example.com --api-key your-api-key project list

Getting an API Key

Generate an API key from your Planka user settings. The full key is only shown once at creation time (it is stored as a hash in the database), so store it securely.

Usage

Global Flags

• --format - Output format: json (default) or table
• --url - Planka API URL (overrides PLANKA_URL)
• --api-key - API key (overrides PLANKA_API_KEY)
• --log-level - Log level: debug, info, warn (default), error

Projects

# List all projects
pcli project list

# Get a specific project
pcli project get <project-id>

Boards

# List all accessible boards
pcli board list

# List boards filtered by project name
pcli board list --project "project1"

# Get a board
pcli board get <board-id>

# List board actions (activity log)
pcli board actions <board-id> --limit 50

Cards

# List cards by board (includes list names)
pcli card list --board <board-id>

# List cards by list
pcli card list --list <list-id>

# Get a card
pcli card get <card-id>

# Create a card
pcli card create --list <list-id> --name "Task name" --description "Details"

# Update a card
pcli card update <card-id> --name "New name" --description "Updated details"

# Delete a card
pcli card delete <card-id>

# Duplicate a card
pcli card duplicate <card-id> --name "Copy of task"

# Move a card to another list
pcli card move <card-id> --list <target-list-id> --position 65536

# Assign/unassign users
pcli card assign <card-id> --user <user-id>
pcli card unassign <card-id> --user <user-id>

# Add/remove labels
pcli card add-label <card-id> --label <label-id>
pcli card remove-label <card-id> --label <label-id>

# List card actions
pcli card actions <card-id> --limit 20

Comments

# List comments on a card
pcli comment list --card <card-id>

# Create a comment
pcli comment create --card <card-id> --text "This is a comment"

# Update a comment
pcli comment update <comment-id> --text "Updated text"

# Delete a comment
pcli comment delete <comment-id>

Task Lists

# Create a task list
pcli task-list create --card <card-id> --name "Checklist"

# Get a task list
pcli task-list get <task-list-id>

# Update a task list
pcli task-list update <task-list-id> --name "Updated name"

# Delete a task list
pcli task-list delete <task-list-id>

Tasks

# Create a task
pcli task create --task-list <task-list-id> --name "Do something"

# Update a task
pcli task update <task-id> --completed true

# Delete a task
pcli task delete <task-id>

Labels

# Create a label
pcli label create --board <board-id> --name "Bug" --color "berry-red"

# Update a label
pcli label update <label-id> --name "Critical Bug" --color "piggy-red"

# Delete a label
pcli label delete <label-id>

Status

# Show status summary of all boards and their lists
pcli status

# Show status filtered by project name
pcli status --project "MyProject"

Output Formats

JSON (default)

All commands return JSON with a consistent envelope:

{
  "data": { ... },
  "error": null
}

On error:

{
  "data": null,
  "error": "error message"
}

Table

Use --format=table for human-readable output:

pcli --format=table project list

Output:

ID                   NAME                 DESCRIPTION          HIDDEN
1357158568008091264  Development Project  A project for...     false

Logging

Enable debug logging to see HTTP requests and responses:

pcli --log-level=debug card list --board <board-id>

Logs are written to stderr in JSON format and won't interfere with stdout output.

Examples

Create a card and add a comment

# Create the card
CARD_ID=$(pcli card create \
  --list <list-id> \
  --name "Implement feature X" \
  --description "Details about feature X" \
  | jq -r '.data.id')

# Add a comment
pcli comment create --card $CARD_ID --text "Started working on this"

Move all cards from one list to another

# Get all cards from source list
pcli card list --list <source-list-id> | jq -r '.data[].id' | while read card_id; do
  pcli card move $card_id --list <target-list-id>
done

Export board structure

# Get board with all lists
pcli board get <board-id> > board.json

# Get all cards for the board
pcli card list --board <board-id> > cards.json

Future Enhancements

The following improvements are planned for future releases:

• Concurrent Processing: Use goroutines with worker pools for parallel board processing in the status command to improve performance with many boards
• Rate Limiting: Implement client-side rate limiting to prevent API abuse
• Enhanced Error Context: Include command context in all error messages for better debugging
• Connection Pooling: Add configurable HTTP client connection limits for better resource management
• Input Validation: Enhanced validation for all user inputs including URL formats and API key patterns

API Compatibility

Built against Planka v2.0 API. See planka-api.json for the full OpenAPI specification.

Contributing

Contributions welcome! Please open an issue or pull request on GitLab.