From ac29893867caff05c7f53dae9dda46262af9495f Mon Sep 17 00:00:00 2001 From: Felix Rudat Date: Tue, 27 Jan 2026 09:36:58 +0100 Subject: [PATCH] Refactor release workflow and update documentation for Homebrew installation --- .github/workflows/release.yml | 2 +- README.md | 39 +++++++++++++++----- SKILL.md | 69 +++++++++++++++++++++-------------- docs/tap-automation.md | 31 ---------------- scripts/planka_cli.py | 6 +++ 5 files changed, 77 insertions(+), 70 deletions(-) delete mode 100644 docs/tap-automation.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 65c32af..09de7dd 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -47,7 +47,7 @@ jobs: git config --global user.name "github-actions[bot]" git config --global user.email "github-actions[bot]@users.noreply.github.com" brew tap voydz/homebrew-tap - brew bump-formula-pr --tap voydz/homebrew-tap planka-cli \ + brew bump-formula-pr planka-cli \ --url "$URL" \ --sha256 "$SHA256" \ --version "$VERSION" diff --git a/README.md b/README.md index 31244c0..8f79c4c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # Planka CLI +[![Release](https://img.shields.io/github/v/release/voydz/planka-cli)](https://github.com/voydz/planka-cli/releases) +[![Homebrew Tap](https://img.shields.io/badge/homebrew-voydz%2Fhomebrew--tap-blue?logo=homebrew)](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. @@ -11,17 +14,20 @@ scan work, create cards, and stay on top of notifications with fast, scriptable ## Quick start -Requirements: Python 3.10+ and a Planka account. +Requirements: A Planka account. For Homebrew installs, macOS + Homebrew. For source/pipx +installs, Python 3.10+. -### Install (local or from Git) +### Install (Homebrew, recommended) ```bash -# Local dev -python3 -m venv .venv -source .venv/bin/activate -pip install -e . +brew tap voydz/homebrew-tap +brew install planka-cli +``` -# Or install from GitHub +### Install (other options) + +```bash +# Install from GitHub pipx install git+https://github.com/voydz/planka-cli ``` @@ -54,6 +60,7 @@ 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 @@ -71,14 +78,26 @@ planka-cli notifications all planka-cli notifications unread ``` -## Project layout +## 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 +### Development ```bash make setup @@ -86,7 +105,7 @@ make run make build ``` -## TBD +### TBD - Release workflow only builds the macOS binary. - Release workflow assumes a GitHub release is already published. diff --git a/SKILL.md b/SKILL.md index 6567990..5e66bad 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,7 +1,7 @@ --- name: planka description: Manage Planka (Kanban) projects, boards, lists, cards, and notifications via a custom Python CLI. -metadata: {"clawdbot":{"emoji":"📋","requires":{"bins":["python3"],"env":["PLANKA_URL","PLANKA_USERNAME","PLANKA_PASSWORD"]}}} +metadata: {"clawdbot":{"emoji":"📋","requires":{"bins":["planka-cli"]}}} --- # Planka CLI @@ -10,16 +10,14 @@ This skill provides a CLI wrapper around the `plankapy` library to interact with ## Setup -1. **Dependencies:** - Navigate to the skill's scripts directory and install dependencies: +1. **Install via Homebrew tap:** ```bash - cd scripts/ - pip install -r requirements.txt + brew tap voydz/homebrew-tap + brew install planka-cli ``` 2. **Configuration:** - Use the `login` command to store credentials in a `.env` file next to the binary - (or next to `scripts/planka_cli.py` when running from source): + Use the `login` command to store credentials: ```bash planka-cli login --url https://planka.example --username alice --password secret # or: python3 scripts/planka_cli.py login --url https://planka.example --username alice --password secret @@ -27,62 +25,77 @@ This skill provides a CLI wrapper around the `plankapy` library to interact with ## Usage -Run the CLI using Python from the `scripts` directory (or referenced via absolute path): +Run the CLI with the installed `planka-cli` binary: ```bash -# Check connection -python3 scripts/planka_cli.py status +# Show help +planka-cli -# Save credentials next to the binary/script -python3 scripts/planka_cli.py login --url https://planka.example --username alice --password secret +# Check connection +planka-cli status + +# Login to planka instance +planka-cli login --url https://planka.example --username alice --password secret # Remove stored credentials -python3 scripts/planka_cli.py logout +planka-cli logout # List Projects -python3 scripts/planka_cli.py projects list +planka-cli projects list # List Boards (optionally by project ID) -python3 scripts/planka_cli.py boards list [PROJECT_ID] +planka-cli boards list [PROJECT_ID] # List Lists in a Board -python3 scripts/planka_cli.py lists list +planka-cli lists list # List Cards in a List -python3 scripts/planka_cli.py cards list +planka-cli cards list # Create a Card -python3 scripts/planka_cli.py cards create "Card title" +planka-cli cards create "Card title" # Update a Card -python3 scripts/planka_cli.py cards update --name "New title" +planka-cli cards update --name "New title" +planka-cli cards update --list-id +planka-cli cards update --list-id --position top # Delete a Card -python3 scripts/planka_cli.py cards delete +planka-cli cards delete # Notifications -python3 scripts/planka_cli.py notifications all -python3 scripts/planka_cli.py notifications unread +planka-cli notifications all +planka-cli notifications unread ``` ## Examples **List all boards:** ```bash -python3 scripts/planka_cli.py boards list +planka-cli boards list ``` -**Show cards in list ID 42:** +**Show cards in list ID 1619901252164912136:** ```bash -python3 scripts/planka_cli.py cards list 42 +planka-cli cards list 1619901252164912136 ``` -**Create a card in list ID 42:** +**Create a card in list ID 1619901252164912136:** ```bash -python3 scripts/planka_cli.py cards create 42 "Ship CLI" +planka-cli cards create 1619901252164912136 "Ship CLI" +``` + +**Move a card to another list:** +```bash +planka-cli cards update 1619901252164912137 --list-id 1619901252164912136 +``` + +**Move a card to another list and pin it to the top:** +```bash +planka-cli cards update 1619901252164912137 --list-id 1619901252164912136 --position top ``` **Mark a card done by updating its name:** ```bash -python3 scripts/planka_cli.py cards update --name "Done: Ship CLI" +planka-cli cards update 1619901252164912137 --name "Done: Ship CLI" ``` diff --git a/docs/tap-automation.md b/docs/tap-automation.md deleted file mode 100644 index 3fb69f5..0000000 --- a/docs/tap-automation.md +++ /dev/null @@ -1,31 +0,0 @@ -# Tap automation - -This repo includes a GitHub Actions workflow that builds a macOS release asset and -opens a formula bump PR in the tap repo using `brew bump-formula-pr`. - -## One-time setup (tap bootstrap) - -Create the tap repo using Homebrew: - -```bash -brew tap-new voydz/homebrew-tap -``` - -Copy the `Formula/` contents from this repo's `homebrew-tap/` folder into the new -tap repo, commit, and push to GitHub. - -## Required secrets - -Add a repository secret in this repo: - -- `HOMEBREW_GITHUB_API_TOKEN`: a GitHub PAT with access to the private tap repo - (needs `repo` scope for a private repository). - -## Release flow - -Create a GitHub release in `voydz/planka-cli` with a tag like `v0.1.0`. The -workflow will: - -- build the binary with PyInstaller -- upload `planka-cli--macos.tar.gz` to the release -- run `brew bump-formula-pr` against `voydz/homebrew-tap` diff --git a/scripts/planka_cli.py b/scripts/planka_cli.py index 938f362..c8db0ed 100644 --- a/scripts/planka_cli.py +++ b/scripts/planka_cli.py @@ -52,6 +52,12 @@ app.add_typer(lists_app, name="lists") app.add_typer(cards_app, name="cards") app.add_typer(notifications_app, name="notifications") +@app.callback(invoke_without_command=True) +def main(ctx: typer.Context): + """Planka CLI.""" + if ctx.invoked_subcommand is None: + click.echo(ctx.get_help()) + def get_env_config() -> tuple[Optional[str], Optional[str], Optional[str]]: return ( os.getenv("PLANKA_URL"),