# pcli - Planka CLI A command-line interface for interacting with the [Planka](https://planka.app/) 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 ```bash 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](https://git.franklin.lab/steve.cliff/pcli/releases). ## 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 ```bash export PLANKA_URL="https://planka.example.com" export PLANKA_API_KEY="D89VszVs_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" ``` Or use command-line flags to override: ```bash 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 ```bash # List all projects pcli project list # Get a specific project pcli project get ``` ### Boards ```bash # List all accessible boards pcli board list # Get a board pcli board get # List board actions (activity log) pcli board actions --limit 50 ``` ### Cards ```bash # List cards by board (includes list names) pcli card list --board # List cards by list pcli card list --list # Get a card pcli card get # Create a card pcli card create --list --name "Task name" --description "Details" # Update a card pcli card update --name "New name" --description "Updated details" # Delete a card pcli card delete # Duplicate a card pcli card duplicate --name "Copy of task" # Move a card to another list pcli card move --list --position 65536 # Assign/unassign users pcli card assign --user pcli card unassign --user # Add/remove labels pcli card add-label --label pcli card remove-label --label # List card actions pcli card actions --limit 20 ``` ### Comments ```bash # List comments on a card pcli comment list --card # Create a comment pcli comment create --card --text "This is a comment" # Update a comment pcli comment update --text "Updated text" # Delete a comment pcli comment delete ``` ### Task Lists ```bash # Create a task list pcli task-list create --card --name "Checklist" # Get a task list pcli task-list get # Update a task list pcli task-list update --name "Updated name" # Delete a task list pcli task-list delete ``` ### Tasks ```bash # Create a task pcli task create --task-list --name "Do something" # Update a task pcli task update --completed true # Delete a task pcli task delete ``` ### Labels ```bash # Create a label pcli label create --board --name "Bug" --color "berry-red" # Update a label pcli label update --name "Critical Bug" --color "piggy-red" # Delete a label pcli label delete ``` ### Status ```bash # Show status summary of all boards and their lists pcli status ``` ## Output Formats ### JSON (default) All commands return JSON with a consistent envelope: ```json { "data": { ... }, "error": null } ``` On error: ```json { "data": null, "error": "error message" } ``` ### Table Use `--format=table` for human-readable output: ```bash 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: ```bash pcli --log-level=debug card list --board ``` Logs are written to stderr in JSON format and won't interfere with stdout output. ## Examples ### Create a card and add a comment ```bash # Create the card CARD_ID=$(pcli card create \ --list \ --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 ```bash # Get all cards from source list pcli card list --list | jq -r '.data[].id' | while read card_id; do pcli card move $card_id --list done ``` ### Export board structure ```bash # Get board with all lists pcli board get > board.json # Get all cards for the board pcli card list --board > 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](https://git.franklin.lab/steve.cliff/pcli).