Refactor release workflow and update documentation for Homebrew installation

.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"

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
+brew tap voydz/homebrew-tap
-python3 -m venv .venv
+brew install planka-cli
-source .venv/bin/activate
+```
-pip install -e .
 
-# 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.

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:**
+1.  **Install via Homebrew tap:**
-    Navigate to the skill's scripts directory and install dependencies:
     ```bash
-    cd scripts/
+    brew tap voydz/homebrew-tap
-    pip install -r requirements.txt
+    brew install planka-cli
     ```
 
 2.  **Configuration:**
-    Use the `login` command to store credentials in a `.env` file next to the binary
+    Use the `login` command to store credentials:
-    (or next to `scripts/planka_cli.py` when running from source):
     ```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
+# Show help
-python3 scripts/planka_cli.py status
+planka-cli
 
-# Save credentials next to the binary/script
+# Check connection
-python3 scripts/planka_cli.py login --url https://planka.example --username alice --password secret
+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 <BOARD_ID>
+planka-cli lists list <BOARD_ID>
 
 # List Cards in a List
-python3 scripts/planka_cli.py cards list <LIST_ID>
+planka-cli cards list <LIST_ID>
 
 # Create a Card
-python3 scripts/planka_cli.py cards create <LIST_ID> "Card title"
+planka-cli cards create <LIST_ID> "Card title"
 
 # Update a Card
-python3 scripts/planka_cli.py cards update <CARD_ID> --name "New title"
+planka-cli cards update <CARD_ID> --name "New title"
+planka-cli cards update <CARD_ID> --list-id <LIST_ID>
+planka-cli cards update <CARD_ID> --list-id <LIST_ID> --position top
 
 # Delete a Card
-python3 scripts/planka_cli.py cards delete <CARD_ID>
+planka-cli cards delete <CARD_ID>
 
 # Notifications
-python3 scripts/planka_cli.py notifications all
+planka-cli notifications all
-python3 scripts/planka_cli.py notifications unread
+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 <CARD_ID> --name "Done: Ship CLI"
+planka-cli cards update 1619901252164912137 --name "Done: Ship CLI"
 ```

docs/tap-automation.md

@@ -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-<version>-macos.tar.gz` to the release
-- run `brew bump-formula-pr` against `voydz/homebrew-tap`

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"),