trelloctl 0.1.0__tar.gz

trelloctl-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.3
+Name: trelloctl
+Version: 0.1.0
+Summary: A command-line interface for Trello
+Author: Werner Robitza
+Author-email: Werner Robitza <werner.robitza@gmail.com>
+Requires-Dist: click>=8.3.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: keyring>=25.7.0
+Requires-Dist: rich>=14.3.2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# trelloctl
+
+[![PyPI version](https://img.shields.io/pypi/v/trelloctl.svg)](https://pypi.org/project/trelloctl)
+[![Python package](https://github.com/slhck/trelloctl/actions/workflows/python-package.yml/badge.svg)](https://github.com/slhck/trelloctl/actions/workflows/python-package.yml)
+
+A command-line interface for Trello, written in Python.
+
+## Requirements
+
+- Python 3.11+
+
+## Installation
+
+Simply run it via [uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```bash
+uvx trelloctl
+```
+
+Or install via [pipx](https://pipx.pypa.io/latest/installation/).
+Or manually via pip:
+
+```bash
+pip install trelloctl
+```
+
+## Usage
+
+### Authentication
+
+Before using the CLI, you need to authenticate with Trello:
+
+1. Go to the [Trello Power-Up Admin Portal](https://trello.com/power-ups/admin)
+2. Create a new Power-Up (required even for personal use)
+3. Copy your API key from the Power-Up's "API Key" section
+4. Run the login command:
+
+```bash
+trelloctl auth login
+```
+
+The CLI will guide you through entering your API key and generating a token. Credentials are stored securely in your system keychain.
+
+To check your authentication status:
+
+```bash
+trelloctl auth status
+```
+
+To remove stored credentials:
+
+```bash
+trelloctl auth logout
+```
+
+### Basic Command Examples
+
+```bash
+# List all boards
+trelloctl board list
+
+# List lists on a board (by name or ID)
+trelloctl list list "My Board"
+trelloctl list list Development
+
+# List cards in a list
+trelloctl list cards "To Do" --board Development
+
+# Show board details
+trelloctl board show Development
+
+# Create a card
+trelloctl card create "To Do" --board Development --name "New task"
+
+# Move a card to another list
+trelloctl card move <card_id> Done --board Development
+
+# Output as JSON
+trelloctl --format json board list
+
+# Output as CSV
+trelloctl --format csv board list
+```
+
+Names support partial matching (case-insensitive). If multiple items match, you'll be prompted to be more specific.
+
+## Command Reference
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--format`, `-f` | Output format: `table` (default), `json`, `csv`, `plain` |
+| `--profile`, `-p` | Configuration profile to use (default: `default`) |
+| `--version` | Show version and exit |
+| `--help` | Show help and exit |
+
+### `trelloctl auth`
+
+Authentication commands.
+
+| Command | Description |
+|---------|-------------|
+| `auth login` | Set up authentication with Trello |
+| `auth status` | Check authentication status |
+| `auth logout` | Remove stored credentials |
+
+### `trelloctl board`
+
+Board management commands.
+
+| Command | Description |
+|---------|-------------|
+| `board list [--filter]` | List all accessible boards |
+| `board show <board>` | Show details of a board |
+| `board create --name <name>` | Create a new board |
+| `board close <board>` | Close (archive) a board |
+| `board delete <board>` | Delete a board permanently |
+| `board labels <board>` | List labels on a board |
+| `board members <board>` | List members of a board |
+
+### `trelloctl list`
+
+List management commands.
+
+| Command | Description |
+|---------|-------------|
+| `list list <board>` | List all lists on a board |
+| `list show <list> --board <board>` | Show details of a list |
+| `list create <board> --name <name>` | Create a new list |
+| `list archive <list> --board <board>` | Archive a list |
+| `list cards <list> --board <board>` | List all cards in a list |
+
+### `trelloctl card`
+
+Card management commands.
+
+| Command | Description |
+|---------|-------------|
+| `card show <card_id>` | Show details of a card |
+| `card create <list> --board <board> --name <name>` | Create a new card |
+| `card move <card_id> <target_list> --board <board>` | Move a card to another list |
+| `card update <card_id> [--name] [--description] [--due]` | Update a card |
+| `card archive <card_id>` | Archive a card |
+| `card delete <card_id>` | Delete a card permanently |
+| `card assign <card_id> <member_id>` | Assign a member to a card |
+| `card unassign <card_id> <member_id>` | Remove a member from a card |
+| `card comment <card_id> <text>` | Add a comment to a card |
+| `card comments <card_id>` | List comments on a card |
+
+### Multiple Profiles
+
+You can use multiple Trello accounts by specifying a profile:
+
+```bash
+# Set up a work profile
+TRELLOCTL_PROFILE=work trelloctl auth login
+
+# Use the work profile
+trelloctl --profile work board list
+```
+
+## License
+
+MIT License
+
+Copyright (c) 2025 Werner Robitza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trelloctl-0.1.0/README.md

@@ -0,0 +1,185 @@
+# trelloctl
+
+[![PyPI version](https://img.shields.io/pypi/v/trelloctl.svg)](https://pypi.org/project/trelloctl)
+[![Python package](https://github.com/slhck/trelloctl/actions/workflows/python-package.yml/badge.svg)](https://github.com/slhck/trelloctl/actions/workflows/python-package.yml)
+
+A command-line interface for Trello, written in Python.
+
+## Requirements
+
+- Python 3.11+
+
+## Installation
+
+Simply run it via [uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```bash
+uvx trelloctl
+```
+
+Or install via [pipx](https://pipx.pypa.io/latest/installation/).
+Or manually via pip:
+
+```bash
+pip install trelloctl
+```
+
+## Usage
+
+### Authentication
+
+Before using the CLI, you need to authenticate with Trello:
+
+1. Go to the [Trello Power-Up Admin Portal](https://trello.com/power-ups/admin)
+2. Create a new Power-Up (required even for personal use)
+3. Copy your API key from the Power-Up's "API Key" section
+4. Run the login command:
+
+```bash
+trelloctl auth login
+```
+
+The CLI will guide you through entering your API key and generating a token. Credentials are stored securely in your system keychain.
+
+To check your authentication status:
+
+```bash
+trelloctl auth status
+```
+
+To remove stored credentials:
+
+```bash
+trelloctl auth logout
+```
+
+### Basic Command Examples
+
+```bash
+# List all boards
+trelloctl board list
+
+# List lists on a board (by name or ID)
+trelloctl list list "My Board"
+trelloctl list list Development
+
+# List cards in a list
+trelloctl list cards "To Do" --board Development
+
+# Show board details
+trelloctl board show Development
+
+# Create a card
+trelloctl card create "To Do" --board Development --name "New task"
+
+# Move a card to another list
+trelloctl card move <card_id> Done --board Development
+
+# Output as JSON
+trelloctl --format json board list
+
+# Output as CSV
+trelloctl --format csv board list
+```
+
+Names support partial matching (case-insensitive). If multiple items match, you'll be prompted to be more specific.
+
+## Command Reference
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--format`, `-f` | Output format: `table` (default), `json`, `csv`, `plain` |
+| `--profile`, `-p` | Configuration profile to use (default: `default`) |
+| `--version` | Show version and exit |
+| `--help` | Show help and exit |
+
+### `trelloctl auth`
+
+Authentication commands.
+
+| Command | Description |
+|---------|-------------|
+| `auth login` | Set up authentication with Trello |
+| `auth status` | Check authentication status |
+| `auth logout` | Remove stored credentials |
+
+### `trelloctl board`
+
+Board management commands.
+
+| Command | Description |
+|---------|-------------|
+| `board list [--filter]` | List all accessible boards |
+| `board show <board>` | Show details of a board |
+| `board create --name <name>` | Create a new board |
+| `board close <board>` | Close (archive) a board |
+| `board delete <board>` | Delete a board permanently |
+| `board labels <board>` | List labels on a board |
+| `board members <board>` | List members of a board |
+
+### `trelloctl list`
+
+List management commands.
+
+| Command | Description |
+|---------|-------------|
+| `list list <board>` | List all lists on a board |
+| `list show <list> --board <board>` | Show details of a list |
+| `list create <board> --name <name>` | Create a new list |
+| `list archive <list> --board <board>` | Archive a list |
+| `list cards <list> --board <board>` | List all cards in a list |
+
+### `trelloctl card`
+
+Card management commands.
+
+| Command | Description |
+|---------|-------------|
+| `card show <card_id>` | Show details of a card |
+| `card create <list> --board <board> --name <name>` | Create a new card |
+| `card move <card_id> <target_list> --board <board>` | Move a card to another list |
+| `card update <card_id> [--name] [--description] [--due]` | Update a card |
+| `card archive <card_id>` | Archive a card |
+| `card delete <card_id>` | Delete a card permanently |
+| `card assign <card_id> <member_id>` | Assign a member to a card |
+| `card unassign <card_id> <member_id>` | Remove a member from a card |
+| `card comment <card_id> <text>` | Add a comment to a card |
+| `card comments <card_id>` | List comments on a card |
+
+### Multiple Profiles
+
+You can use multiple Trello accounts by specifying a profile:
+
+```bash
+# Set up a work profile
+TRELLOCTL_PROFILE=work trelloctl auth login
+
+# Use the work profile
+trelloctl --profile work board list
+```
+
+## License
+
+MIT License
+
+Copyright (c) 2025 Werner Robitza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trelloctl-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "trelloctl"
+version = "0.1.0"
+description = "A command-line interface for Trello"
+readme = "README.md"
+authors = [
+    { name = "Werner Robitza", email = "werner.robitza@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.3.1",
+    "httpx>=0.28.1",
+    "keyring>=25.7.0",
+    "rich>=14.3.2",
+]
+
+[project.scripts]
+trelloctl = "trelloctl.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pre-commit>=4.2.0",
+    "pytest>=9.0.2",
+    "pytest-mock>=3.14.0",
+    "ruff>=0.15.0",
+]

trelloctl-0.1.0/src/trelloctl/__init__.py

@@ -0,0 +1,5 @@
+"""trelloctl - A command-line interface for Trello."""
+
+from importlib.metadata import version
+
+__version__ = version("trelloctl")

trelloctl-0.1.0/src/trelloctl/cli.py

@@ -0,0 +1,91 @@
+"""Main CLI entry point."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+
+from trelloctl import __version__
+from trelloctl.client import TrelloClient
+from trelloctl.config import Config
+from trelloctl.output import OutputFormat, print_error
+from trelloctl.resolver import Resolver
+
+
+class Context:
+    """CLI context object holding shared state."""
+
+    def __init__(self) -> None:
+        self.profile = os.environ.get("TRELLOCTL_PROFILE", "default")
+        self.config = Config(self.profile)
+        self.client: TrelloClient | None = None
+        self._resolver: Resolver | None = None
+        self.format = OutputFormat.TABLE
+
+    def ensure_client(self) -> TrelloClient:
+        """Ensure we have an authenticated client."""
+        if self.client is None:
+            api_key = self.config.get_api_key()
+            token = self.config.get_token()
+
+            if not api_key or not token:
+                print_error("Not authenticated. Run 'trelloctl auth login' first.")
+                sys.exit(1)
+
+            self.client = TrelloClient(api_key, token)
+
+        return self.client
+
+    @property
+    def resolver(self) -> Resolver:
+        """Get the name resolver."""
+        if self._resolver is None:
+            self._resolver = Resolver(self.ensure_client())
+        return self._resolver
+
+
+pass_context = click.make_pass_decorator(Context, ensure=True)
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="trelloctl")
+@click.option(
+    "--format",
+    "-f",
+    type=click.Choice(["table", "json", "csv", "plain"]),
+    default="table",
+    help="Output format",
+)
+@click.option(
+    "--profile",
+    "-p",
+    envvar="TRELLOCTL_PROFILE",
+    default="default",
+    help="Configuration profile to use",
+)
+@pass_context
+def main(ctx: Context, format: str, profile: str) -> None:
+    """trelloctl - Manage your Trello boards from the command line."""
+    ctx.format = OutputFormat(format)
+    ctx.profile = profile
+    ctx.config = Config(profile)
+
+
+def _register_commands() -> None:
+    """Register command groups with the main CLI."""
+    from trelloctl.commands import auth, board, card
+    from trelloctl.commands import list as list_cmd
+
+    main.add_command(auth.auth)
+    main.add_command(board.board)
+    main.add_command(card.card)
+    main.add_command(list_cmd.list_)
+
+
+_register_commands()
+
+
+if __name__ == "__main__":
+    main()

trelloctl-0.1.0/src/trelloctl/client.py

@@ -0,0 +1,179 @@
+"""Trello API client."""
+
+from typing import Any
+
+import httpx
+
+BASE_URL = "https://api.trello.com/1"
+
+
+class TrelloClient:
+    """HTTP client for Trello API."""
+
+    def __init__(self, api_key: str, token: str) -> None:
+        self.api_key = api_key
+        self.token = token
+        self._client = httpx.Client(timeout=30.0)
+
+    def _auth_params(self) -> dict[str, str]:
+        """Return authentication parameters."""
+        return {"key": self.api_key, "token": self.token}
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict | None = None,
+        json: dict | None = None,
+    ) -> Any:
+        """Make an authenticated request to Trello API."""
+        url = f"{BASE_URL}{path}"
+        all_params = self._auth_params()
+        if params:
+            all_params.update(params)
+
+        response = self._client.request(method, url, params=all_params, json=json)
+        response.raise_for_status()
+
+        if response.status_code == 204:
+            return None
+        return response.json()
+
+    def get(self, path: str, params: dict | None = None) -> Any:
+        """Make a GET request."""
+        return self._request("GET", path, params=params)
+
+    def post(
+        self, path: str, params: dict | None = None, json: dict | None = None
+    ) -> Any:
+        """Make a POST request."""
+        return self._request("POST", path, params=params, json=json)
+
+    def put(
+        self, path: str, params: dict | None = None, json: dict | None = None
+    ) -> Any:
+        """Make a PUT request."""
+        return self._request("PUT", path, params=params, json=json)
+
+    def delete(self, path: str, params: dict | None = None) -> Any:
+        """Make a DELETE request."""
+        return self._request("DELETE", path, params=params)
+
+    # Board methods
+    def get_boards(self, filter: str = "open") -> list[dict]:
+        """Get all boards for the authenticated user."""
+        return self.get("/members/me/boards", params={"filter": filter})
+
+    def get_board(self, board_id: str) -> dict:
+        """Get a board by ID."""
+        return self.get(f"/boards/{board_id}")
+
+    def create_board(self, name: str, desc: str = "") -> dict:
+        """Create a new board."""
+        return self.post("/boards", params={"name": name, "desc": desc})
+
+    def close_board(self, board_id: str, closed: bool = True) -> dict:
+        """Close or reopen a board."""
+        return self.put(f"/boards/{board_id}", params={"closed": str(closed).lower()})
+
+    def delete_board(self, board_id: str) -> None:
+        """Delete a board."""
+        self.delete(f"/boards/{board_id}")
+
+    def get_board_lists(self, board_id: str, filter: str = "open") -> list[dict]:
+        """Get all lists on a board."""
+        return self.get(f"/boards/{board_id}/lists", params={"filter": filter})
+
+    def get_board_labels(self, board_id: str) -> list[dict]:
+        """Get all labels on a board."""
+        return self.get(f"/boards/{board_id}/labels")
+
+    def get_board_members(self, board_id: str) -> list[dict]:
+        """Get all members of a board."""
+        return self.get(f"/boards/{board_id}/members")
+
+    # List methods
+    def get_list(self, list_id: str) -> dict:
+        """Get a list by ID."""
+        return self.get(f"/lists/{list_id}")
+
+    def create_list(self, board_id: str, name: str, pos: str = "bottom") -> dict:
+        """Create a new list on a board."""
+        return self.post(
+            "/lists", params={"idBoard": board_id, "name": name, "pos": pos}
+        )
+
+    def archive_list(self, list_id: str, closed: bool = True) -> dict:
+        """Archive or unarchive a list."""
+        return self.put(f"/lists/{list_id}", params={"closed": str(closed).lower()})
+
+    def get_list_cards(self, list_id: str) -> list[dict]:
+        """Get all cards in a list."""
+        return self.get(f"/lists/{list_id}/cards")
+
+    # Card methods
+    def get_card(self, card_id: str) -> dict:
+        """Get a card by ID."""
+        return self.get(f"/cards/{card_id}")
+
+    def create_card(
+        self,
+        list_id: str,
+        name: str,
+        desc: str = "",
+        pos: str = "bottom",
+        due: str | None = None,
+        labels: list[str] | None = None,
+        members: list[str] | None = None,
+    ) -> dict:
+        """Create a new card."""
+        params: dict[str, Any] = {
+            "idList": list_id,
+            "name": name,
+            "desc": desc,
+            "pos": pos,
+        }
+        if due:
+            params["due"] = due
+        if labels:
+            params["idLabels"] = ",".join(labels)
+        if members:
+            params["idMembers"] = ",".join(members)
+        return self.post("/cards", params=params)
+
+    def update_card(self, card_id: str, **kwargs: Any) -> dict:
+        """Update a card."""
+        return self.put(f"/cards/{card_id}", params=kwargs)
+
+    def move_card(self, card_id: str, list_id: str, pos: str = "bottom") -> dict:
+        """Move a card to a different list."""
+        return self.put(f"/cards/{card_id}", params={"idList": list_id, "pos": pos})
+
+    def archive_card(self, card_id: str, closed: bool = True) -> dict:
+        """Archive or unarchive a card."""
+        return self.put(f"/cards/{card_id}", params={"closed": str(closed).lower()})
+
+    def delete_card(self, card_id: str) -> None:
+        """Delete a card."""
+        self.delete(f"/cards/{card_id}")
+
+    def add_card_member(self, card_id: str, member_id: str) -> list[dict]:
+        """Add a member to a card."""
+        return self.post(f"/cards/{card_id}/idMembers", params={"value": member_id})
+
+    def remove_card_member(self, card_id: str, member_id: str) -> list[dict]:
+        """Remove a member from a card."""
+        return self.delete(f"/cards/{card_id}/idMembers/{member_id}")
+
+    def add_card_comment(self, card_id: str, text: str) -> dict:
+        """Add a comment to a card."""
+        return self.post(f"/cards/{card_id}/actions/comments", params={"text": text})
+
+    def get_card_comments(self, card_id: str) -> list[dict]:
+        """Get comments on a card."""
+        return self.get(f"/cards/{card_id}/actions", params={"filter": "commentCard"})
+
+    # Member methods
+    def get_me(self) -> dict:
+        """Get the authenticated user."""
+        return self.get("/members/me")

trelloctl-0.1.0/src/trelloctl/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for Trello CLI."""