Felix Rudat
118 lines
2.8 KiB
Markdown
118 lines
2.8 KiB
Markdown
# Planka CLI
|
|
|
|
[](https://github.com/voydz/planka-cli/releases)
|
|
[](https://github.com/voydz/homebrew-tap)
|
|
|
|
Cut through the UI and drive your Planka boards from the terminal. This CLI lets you
|
|
scan work, create cards, and stay on top of notifications with fast, scriptable commands.
|
|
|
|
## Why it exists
|
|
|
|
- Keep momentum without context switching to the browser.
|
|
- Script common workflows (triage, cleanup, nightly status pulls).
|
|
- Work with Planka from any machine that has Python installed.
|
|
|
|
## Quick start
|
|
|
|
Requirements: A Planka account. For Homebrew installs, macOS + Homebrew. For source/pipx
|
|
installs, Python 3.11+.
|
|
|
|
### Install (Homebrew, recommended)
|
|
|
|
```bash
|
|
brew tap voydz/homebrew-tap
|
|
brew install planka-cli
|
|
```
|
|
|
|
### Install (other options)
|
|
|
|
```bash
|
|
# Install from GitHub
|
|
pipx install git+https://github.com/voydz/planka-cli
|
|
```
|
|
|
|
### Login
|
|
|
|
```bash
|
|
planka-cli login --url https://planka.example --username alice --password secret
|
|
```
|
|
|
|
### Run
|
|
|
|
```bash
|
|
planka-cli status
|
|
planka-cli projects list
|
|
planka-cli boards list
|
|
```
|
|
|
|
## Authentication
|
|
|
|
`login` stores credentials in `~/.config/planka-cli/tokens/credentials.json` by default.
|
|
Override with `--tokenstore PATH` or the `PLANKATOKENS` environment variable. You can also
|
|
set credentials via environment variables. Note: `--tokenstore` is a global option and
|
|
must appear before the command name.
|
|
|
|
```bash
|
|
export PLANKA_URL=https://planka.example
|
|
export PLANKA_USERNAME=alice
|
|
export PLANKA_PASSWORD=secret
|
|
```
|
|
|
|
## Common commands
|
|
|
|
```bash
|
|
planka-cli
|
|
planka-cli status
|
|
planka-cli login --url https://planka.example --username alice --password secret
|
|
planka-cli logout
|
|
|
|
planka-cli projects list
|
|
planka-cli boards list [PROJECT_ID]
|
|
planka-cli lists list <BOARD_ID>
|
|
planka-cli cards list <LIST_ID>
|
|
planka-cli cards show <CARD_ID>
|
|
|
|
planka-cli cards create <LIST_ID> "Card title" --description "Details"
|
|
planka-cli cards update <CARD_ID> --name "New title"
|
|
planka-cli cards delete <CARD_ID>
|
|
|
|
planka-cli notifications all
|
|
planka-cli notifications unread
|
|
```
|
|
|
|
## Maintainers
|
|
|
|
Developer docs live in `docs/`. Release automation notes are in `docs/tap-automation.md`.
|
|
|
|
### Local dev
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -e .
|
|
```
|
|
|
|
### Project layout
|
|
|
|
- `scripts/planka_cli.py` CLI entrypoint
|
|
- `docs/` supporting documentation
|
|
- `pyproject.toml` packaging metadata
|
|
- `Makefile` helpers for setup and binary builds
|
|
|
|
### Development
|
|
|
|
```bash
|
|
make setup
|
|
make run
|
|
make lint
|
|
make test
|
|
make check
|
|
make build
|
|
```
|
|
|
|
### TBD
|
|
|
|
- Release workflow only builds the macOS binary.
|
|
- Release workflow assumes a GitHub release is already published.
|
|
- No signing/notarization or multi-platform release assets yet.
|