Released v1
This commit is contained in:
Steve Cliff
@@ -0,0 +1,286 @@
|
||||
# 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 <project-id>
|
||||
```
|
||||
|
||||
### Boards
|
||||
|
||||
```bash
|
||||
# List all accessible boards
|
||||
pcli board list
|
||||
|
||||
# Get a board
|
||||
pcli board get <board-id>
|
||||
|
||||
# List board actions (activity log)
|
||||
pcli board actions <board-id> --limit 50
|
||||
```
|
||||
|
||||
### Cards
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```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 <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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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](https://git.franklin.lab/steve.cliff/pcli).
|
||||
Reference in New Issue
Block a user