trelctl 1.0.0__tar.gz

trelctl-1.0.0/.env.example

@@ -0,0 +1,2 @@
+TRELLO_API_KEY=your_trello_api_key_here
+TRELLO_TOKEN=your_trello_oauth_token_here

trelctl-1.0.0/.envrc

@@ -0,0 +1,2 @@
+source_env_if_exists ~/.envrc
+source_env_if_exists .venv/bin/activate

trelctl-1.0.0/.gitignore

@@ -0,0 +1,3 @@
+.env
+temp/
+tmp/

trelctl-1.0.0/.pymarkdown.yaml

@@ -0,0 +1,15 @@
+system:
+  exclude_path: "temp/,tmp/"
+extensions:
+  markdown-tables:
+    enabled: true
+plugins:
+  md007:
+    enabled: true
+    indent: 4
+  md013:
+    enabled: false
+  md024:
+    enabled: false
+  md040:
+    enabled: false

trelctl-1.0.0/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "cSpell.words": [
+        "dependancies",
+        "trelctl"
+    ]
+}

trelctl-1.0.0/.yamllint

@@ -0,0 +1,21 @@
+---
+extends: default
+rules:
+  document-start: disable
+  braces:
+    max-spaces-inside: 1
+    min-spaces-inside: 0
+  brackets:
+    max-spaces-inside: 1
+    min-spaces-inside: 0
+    level: warning
+  commas:
+    level: warning
+  comments:
+    min-spaces-from-content: 1
+  indentation:
+    level: warning
+  line-length:
+    level: warning
+    max: 999
+  truthy: disable

trelctl-1.0.0/CLAUDE.md

@@ -0,0 +1,257 @@
+# trelctl
+
+A Python CLI tool for managing Trello boards via the Trello REST API.
+
+Trello REST API docs: [Atlassian Trello REST API](https://developer.atlassian.com/cloud/trello/rest/)
+
+## Sub commands
+
+### create board
+
+Create a new Trello board with a specified name.
+
+### import lists
+
+Parse a CSV file and create lists in a specified board. Each CSV row becomes one list.
+
+### import cards
+
+Parse a CSV file and create cards in a specified board and list. Each CSV row becomes one card.
+
+### get lists
+
+Get all lists from a board in CSV format.
+
+API reference: [get lists](https://developer.atlassian.com/cloud/trello/rest/api-group-boards/#api-boards-id-lists-get)
+
+### get cards
+
+Get all cards from a board (optionally filtered by list) in CSV format.
+
+API reference: [get cards](https://developer.atlassian.com/cloud/trello/rest/api-group-boards/#api-boards-id-cards-get)
+
+### get members
+
+Get all members of a board in CSV format.
+
+API reference: [get members](https://developer.atlassian.com/cloud/trello/rest/api-group-boards/#api-boards-id-members-get)
+
+## Tech Stack
+
+- Language: Python 3.14+
+- Package management: `uv` (run `uv sync` to install dependencies)
+- `typer` for CLI argument parsing
+- `httpx` for HTTP API calls (no external frameworks)
+- `csv` stdlib for CSV parsing
+- Type hints on all functions; dataclasses for data structures
+
+## Project Structure
+
+```
+trelctl/
+├── pyproject.toml
+├── trelctl/
+│   ├── __init__.py
+│   ├── main.py                  # Entry point, CLI app setup
+│   ├── commands/
+│   │   ├── create_board.py      # `create board` subcommand
+│   │   ├── import_lists.py      # `import lists` subcommand
+│   │   ├── import_cards.py      # `import cards` subcommand
+│   │   ├── get_lists.py         # `get lists` subcommand
+│   │   ├── get_members.py       # `get members` subcommand
+│   │   └── get_cards.py         # `get cards` subcommand
+│   ├── trello/
+│   │   ├── __init__.py
+│   │   ├── client.py            # HTTP client, auth, base request helpers
+│   │   ├── boards.py            # Board lookup and creation
+│   │   ├── lists.py             # List lookup and creation
+│   │   ├── cards.py             # Card creation and retrieval
+│   │   └── labels.py            # Label lookup
+│   └── parser.py                # CSV parsing and row mapping
+├── tests/
+│   ├── test_parser.py
+│   └── test_labels.py
+├── .env.example
+├── Makefile
+└── README.md
+```
+
+## CLI Interface
+
+```
+trelctl create board <name>
+trelctl import lists --board <name-or-id> <file.csv>
+trelctl import cards --board <name-or-id> --list <name-or-id> <file.csv>
+trelctl get lists --board <name-or-id>
+trelctl get cards --board <name-or-id> [--list <name-or-id>]
+trelctl get members --board <name-or-id>
+```
+
+Common flags:
+- `--board` - Board name or ID to target
+- `--dry-run` (import commands only) - Validate the CSV and resolve board/list/labels via the API, but do not write any data
+
+Examples:
+
+```
+trelctl create board "My Board"
+trelctl import lists --board "My Board" lists.csv
+trelctl import cards --board "My Board" --list "Backlog" cards.csv
+trelctl get lists --board "My Board"
+trelctl get cards --board "My Board" --list "Backlog"
+trelctl get members --board "My Board"
+```
+
+## Authentication
+
+Read from environment variables only. Validate both are set before making any API calls.
+
+| Variable        | Description             |
+|-----------------|-------------------------|
+| TRELLO_API_KEY  | Trello Power-Up API key |
+| TRELLO_TOKEN    | User OAuth token        |
+
+Fail with a clear error message if either is missing.
+
+## CSV Formats
+
+### lists
+
+| Column | Required | Format     | Example   |
+|--------|----------|------------|-----------|
+| `name` | Yes      | Plain text | `Backlog` |
+
+Rows with an empty `name` are skipped with a warning to stderr.
+
+### cards
+
+Fixed column headers (case-sensitive). Column order does not matter. `name` is required; all others are optional.
+
+| Column        | Required | Format                            | Example                          |
+|---------------|----------|-----------------------------------|----------------------------------|
+| `name`        | Yes      | Plain text                        | `Fix login bug`                  |
+| `description` | No       | Plain text                        | `Steps to reproduce...`          |
+| `labels`      | No       | Comma-separated label names       | `Bug,High Priority`              |
+| `due_date`    | No       | `YYYY-MM-DD`                      | `2026-04-15`                     |
+| `checklist`   | No       | Pipe-separated items              | `Write tests\|Review PR\|Deploy` |
+| `members`     | No       | Pipe-separated Trello member IDs  | `abc123def456\|ghi789jkl0`       |
+
+`members` values must be Trello alphanumeric member IDs, not usernames or email addresses.
+
+### members
+
+| Column | Required | Format     | Example        |
+|--------|----------|------------|----------------|
+| `name` | Yes      | Plain text | `abc123def456` |
+
+## Trello API Integration
+
+Base URL: `https://api.trello.com/1`
+
+Authentication: append `?key={TRELLO_API_KEY}&token={TRELLO_TOKEN}` to all requests.
+
+### Board resolution (all commands that take `--board`)
+
+`GET /members/me/boards` - find board by name (case-insensitive) or treat value as ID directly.
+
+If `--board` does not match any name and is not a valid-looking ID, exit with an error.
+
+### create board
+
+`POST /boards` with `name=<name>`.
+
+Print `Created board: "<name>" (id: <boardId>)` on success.
+
+### import lists
+
+Resolution before processing rows:
+
+1. Resolve board (see above)
+
+Per-row list creation: `POST /boards/{boardId}/lists` with `name=<name>`.
+
+Print `Created list: "<name>" (id: <listId>)` per row.
+
+### import cards
+
+Resolution before processing rows:
+
+1. Resolve board (see above)
+2. `GET /boards/{boardId}/lists` - find list by name (case-insensitive) or treat value as ID directly
+3. `GET /boards/{boardId}/labels` - fetch all labels to resolve names to IDs
+
+If `--list` does not match any name and is not a valid-looking ID, exit with an error.
+
+Per-row card creation:
+
+1. `POST /cards` with fields:
+   - `name`
+   - `desc` (optional)
+   - `idList` (resolved list ID)
+   - `idLabels` (comma-separated resolved label IDs, optional)
+   - `due` (RFC3339 datetime from `due_date`, optional)
+   - `idMembers` (comma-separated member IDs from `members` column, optional)
+
+2. If `checklist` column is non-empty:
+   - `POST /cards/{cardId}/checklists` with `name=Checklist`
+   - For each pipe-separated item: `POST /checklists/{checklistId}/checkItems` with `name=<item>`
+
+Label handling:
+- Match label names to existing board labels (case-insensitive)
+- If a label name does not exist on the board, print a warning to stderr and skip that label (do not create new labels)
+
+Print `Created card: "<name>" (id: <cardId>)` per row.
+
+### get lists
+
+1. Resolve board (see above)
+2. `GET /boards/{boardId}/lists` - fetch all lists
+3. Write CSV with columns: `name`
+
+### get cards
+
+1. Resolve board (see above)
+2. If `--list` provided, resolve list and fetch `GET /lists/{listId}/cards`; otherwise `GET /boards/{boardId}/cards`
+3. For each card with checklists, fetch `GET /cards/{cardId}/checklists` to populate the `checklist` column
+4. Write CSV with the same columns as the import cards format: `name`, `description`, `labels`, `due_date`, `checklist`, `members`
+
+Get cards CSV uses the same column format as import so files can be round-tripped.
+
+### get members
+
+1. Resolve board (see above)
+2. `GET /boards/{boardId}/members` - fetch all members
+3. Write CSV with columns: `name`
+
+### Error handling
+
+- Stop on the first API error. Print the command context, HTTP status, and response body to stderr, then exit non-zero
+- Do not retry
+
+## Output
+
+- Import commands: print one line per created resource, then `Done. Created N <resource>(s).`
+- Get commands: write to stdout in csv format. Users can pipe the output to a file.
+- Warnings and errors go to stderr
+
+## Makefile
+
+Targets: `build`, `test`, `lint`, `run`.
+
+- `build`: `uv build`
+- `test`: `uv run pytest`
+- `lint`: `uv run ruff check .` and `uvx ty check`
+- `run`: `uv run trelctl`
+
+## Gotchas
+
+- **Rate limits**: Trello enforces 100 API requests per 10 seconds per token. Cards with checklists require 2+ extra calls each (one for the checklist, one per item). Do not implement throttling unless asked.
+- **Checklist API order**: Create the checklist on the card first (`POST /cards/{id}/checklists`), then add items to it (`POST /checklists/{id}/checkItems`) — two separate calls per card with a checklist.
+
+## Testing
+
+- Unit tests for CSV parser: valid rows, missing name, bad date format, pipe-separated checklist/members parsing
+- Unit tests for label resolution logic
+- Unit tests for get CSV formatting (round-trip: get columns match import columns)
+- Mock `httpx` calls using `pytest-mock` or `respx`; do not make real API calls in tests
+- Tests in `tests/`: `tests/test_parser.py`, `tests/test_labels.py` etc.

trelctl-1.0.0/LICENSE

@@ -0,0 +1,23 @@
+# LICENSE
+
+MIT License
+
+Copyright (c) 2026 Craig Hurley
+
+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.

trelctl-1.0.0/Makefile

@@ -0,0 +1,96 @@
+#!/usr/bin/env make
+
+.DEFAULT_GOAL := help
+
+PACKAGE_NAME		:= $(shell grep '^name = ' pyproject.toml | sed 's/name = "\(.*\)"/\1/')
+PACKAGE_TEST_DIR	:= $(TMPDIR)
+PYTHON_VERSION		:= 3.14
+VENV_DIR			:= .venv
+
+help: ## Print this help
+	@echo 'Usage:'
+	@echo '  make <target>'
+	@echo ''
+	@echo 'Targets:'
+	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*##"}; {printf "  %-25s %s\n", $$1, $$2}'
+.PHONY: help
+
+build: clean test ## Build the package (clean, test, build)
+	@echo $@
+	uv build
+.PHONY: build
+
+check-version: ## Check if git tag equals version in pyproject.toml
+	@echo $@
+	@TAG=$$(git tag -l --points-at HEAD); \
+	echo "$$TAG" | grep -E "^[0-9]+\.[0-9]+\.[0-9]+"; \
+	grep "version = \"$$TAG\"" pyproject.toml
+.PHONY: check-version
+
+clean: ## Clean files and directories
+	@echo $@
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".mypy_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "*.ruff_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "build" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "dist" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "test" -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete
+	find . -type f -name "*.pyo" -delete
+	find . -type f -name ".coverage" -delete
+.PHONY: clean
+
+deploy-prod: build ## Deploy to prod pypi.org (build, deploy)
+	@echo $@
+	uv run twine upload dist/*
+.PHONY: deploy-prod
+
+deploy-test: build ## Deploy to test pypi.org (build, deploy)
+	@echo $@
+	uv run twine upload --repository testpypi dist/*
+.PHONY: deploy-test
+
+install: ## Install local venv and dev packages
+	@echo $@
+	uv venv --clear $(VENV_DIR) --python $(PYTHON_VERSION)
+	uv pip install -U --group dev
+.PHONY: install
+
+lint: ## Run formatter, linters etc.
+	@echo $@
+	uvx ruff format
+	uvx ruff check --fix
+	uvx ty check -q
+	uvx pymarkdownlnt scan "**/*.md"
+	uvx yamllint -c .yamllint ./
+.PHONY: lint
+
+test: ## Run tests
+	@echo $@
+	uv run pytest tests/
+.PHONY: test
+
+validate-local-package: ## Install the locally built package and perform basic validation
+	@echo $@
+	@DEST="$(PACKAGE_TEST_DIR)$(PACKAGE_NAME)"; \
+	mkdir -p "$$DEST"; \
+	cd "$$DEST" && \
+	trap 'rm -fr $(VENV_DIR)' EXIT; \
+	uv venv --clear $(VENV_DIR) --python $(PYTHON_VERSION) && \
+	VIRTUAL_ENV=$(VENV_DIR) uv pip install -U "$(CURDIR)/dist/$(PACKAGE_NAME)-"*.whl && \
+	VIRTUAL_ENV=$(VENV_DIR) uv run $(PACKAGE_NAME) --help
+.PHONY: validate-local-package
+
+validate-pypi-package: ## Install the package from pypi.org and perform basic validation
+	@echo $@
+	@TAG=$$(git tag -l --points-at HEAD); \
+	DEST="$(PACKAGE_TEST_DIR)$(PACKAGE_NAME)"; \
+	mkdir -p "$$DEST"; \
+	cd "$$DEST" && \
+	trap 'rm -fr $(VENV_DIR)' EXIT; \
+	uv venv --clear $(VENV_DIR) --python $(PYTHON_VERSION) && \
+	VIRTUAL_ENV=$(VENV_DIR) uv pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple $(PACKAGE_NAME)==$$TAG && \
+	VIRTUAL_ENV=$(VENV_DIR) uv run $(PACKAGE_NAME) --help
+.PHONY: validate-pypi-package

trelctl-1.0.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: trelctl
+Version: 1.0.0
+Summary: CLI tool for managing Trello boards via the Trello REST API
+Project-URL: Homepage, https://github.com/craighurley/trelctl
+Project-URL: Repository, https://github.com/craighurley/trelctl
+Project-URL: Issues, https://github.com/craighurley/trelctl/issues
+Author-email: Craig Hurley <craighurley78@gmail.com>
+Maintainer-email: Craig Hurley <craighurley78@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,trello
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+# trelctl
+
+A CLI tool for managing Trello boards via the Trello REST API.
+
+## Installation
+
+```bash
+uv tool install trelctl
+```
+
+Or run directly without installing:
+
+```bash
+uvx trelctl
+```
+
+## Setup
+
+### 1. Get your Trello credentials
+
+- **API Key**: Go to [trello.com/power-ups/admin](https://trello.com/power-ups/admin), create a Power-Up, and copy the API key.
+- **Token**: From the same page, generate a token with read/write access to your boards.
+
+### 2. Set environment variables
+
+Copy `.env.example` to `.env` and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+```env
+TRELLO_API_KEY=your_trello_api_key_here
+TRELLO_TOKEN=your_trello_oauth_token_here
+```
+
+Alternatively, export them in your shell:
+
+```bash
+export TRELLO_API_KEY=your_api_key
+export TRELLO_TOKEN=your_token
+```
+
+## Commands
+
+### create board
+
+Create a new Trello board.
+
+```bash
+trelctl create board "My Board"
+```
+
+Output:
+
+```
+Created board: "My Board" (id: abc123)
+```
+
+### import lists
+
+Create lists in a board from a CSV file.
+
+```bash
+trelctl import lists --board "My Board" lists.csv
+trelctl import lists --board "My Board" --dry-run lists.csv
+```
+
+CSV format:
+
+| Column | Required | Example   |
+|--------|----------|-----------|
+| `name` | Yes      | `Backlog` |
+
+Example `lists.csv`:
+
+```csv
+name
+Backlog
+In Progress
+Done
+```
+
+`--dry-run` validates the file and resolves the board without creating anything.
+
+### import cards
+
+Create cards in a board list from a CSV file.
+
+```bash
+trelctl import cards --board "My Board" --list "Backlog" cards.csv
+trelctl import cards --board "My Board" --list "Backlog" --dry-run cards.csv
+```
+
+CSV format:
+
+| Column        | Required | Format                      | Example                          |
+|---------------|----------|-----------------------------|----------------------------------|
+| `name`        | Yes      | Plain text                  | `Fix login bug`                  |
+| `description` | No       | Plain text                  | `Steps to reproduce...`          |
+| `labels`      | No       | Comma-separated label names | `Bug,High Priority`              |
+| `due_date`    | No       | `YYYY-MM-DD`                | `2026-04-15`                     |
+| `checklist`   | No       | Pipe-separated items        | `Write tests\|Review PR\|Deploy` |
+| `members`     | No       | Pipe-separated member IDs   | `abc123def456\|ghi789jkl0`       |
+
+- Labels must already exist on the board. Unknown label names are skipped with a warning.
+- `members` values must be Trello member IDs (alphanumeric), not usernames or email addresses.
+- Column order does not matter. `name` is the only required column.
+
+Example `cards.csv`:
+
+```csv
+name,description,labels,due_date,checklist,members
+Fix login bug,Reproduce on mobile,Bug,2026-04-15,Write test|Fix bug|Deploy,
+Add dark mode,,Enhancement,,,,
+```
+
+`--dry-run` validates the file, resolves the board, list, and labels, but creates nothing.
+
+### get lists
+
+Export all lists from a board to CSV.
+
+```bash
+trelctl get lists --board "My Board"
+trelctl get lists --board "My Board" > lists.csv
+```
+
+Output columns: `name`
+
+### get cards
+
+Export all cards from a board (or a specific list) to CSV.
+
+```bash
+trelctl get cards --board "My Board"
+trelctl get cards --board "My Board" --list "Backlog"
+trelctl get cards --board "My Board" > cards.csv
+```
+
+Output columns: `name`, `description`, `labels`, `due_date`, `checklist`, `members`
+
+The output uses the same format as `import cards`, so exported files can be re-imported.
+
+### get members
+
+Export all members of a board to CSV.
+
+```bash
+trelctl get members --board "My Board"
+trelctl get members --board "My Board" > members.csv
+```
+
+Output columns: `name` (Trello member IDs)
+
+## Board and list resolution
+
+All `--board` and `--list` options accept either a name or an ID:
+
+- **Name**: matched case-insensitively against your boards/lists.
+- **ID**: used directly if no name match is found.
+
+If neither matches, the command exits with an error.
+
+## Round-tripping
+
+`get cards` output is compatible with `import cards` input, which allows you to export cards from one board and import them into another:
+
+```bash
+trelctl get cards --board "Source Board" > cards.csv
+trelctl import cards --board "Target Board" --list "Backlog" cards.csv
+```
+
+## Development
+
+```bash
+make install     # install dependencies
+make test        # run tests
+make lint        # run linters
+make build       # build package
+```