Trello Tools

A powerful command-line interface (CLI) for interacting with Trello. Manage your boards, lists, cards, and labels without leaving the terminal.

🚀 Quick Start

Option 1: Install from PyPI (Recommended)

pip install trello-tools
trello-tools --help

Option 2: Download Standalone Executable

No Python required! Download the latest trello-tools.exe from GitHub Releases.

Option 3: Install from Source

git clone https://github.com/jhaisley/trello-tools.git
cd trello-tools
pip install -e .

Table of Contents

• Trello Tools
  • Description
  • History
  • Features
  • Installation
  • Configuration
    • Trello API
    • Gemini API (for AI labeling)
    • Set a Default Board
  • Usage
    • General Help
    • Board Commands
    • Card Commands
    • Label Commands
    • Automated Tasks
  • Development
  • Testing
  • Contributing
  • License
  • Disclaimer

Description

This CLI provides a comprehensive set of commands to manage your Trello boards. It's built with Python, Typer, and the py-trello library. It also includes a feature to automatically label cards using the Gemini API.

History

This project started as a single-purpose utility called tlabeler to automatically label unlabeled Trello cards using AI. This helped with personal organization and sorting. After others saw its usefulness and wanted to use it, the project expanded to include more general-purpose commands for manual use and scripting.

The CLI has since been used for various purposes, including:

• Managing technical support tickets
• Tracking outages
• Creating boards for new clients and projects
• CI/CD remediation and integration

Given its wide range of uses, the project has been made public to be used by a wider audience.

Features

📋 Board Management

• View all boards: List all your Trello boards with IDs
• Create new boards: Set up new projects instantly
• List management: View all lists on any board
• Board reporting: Generate activity reports

🃏 Card Operations

• Create cards: Add new cards to any list
• Move cards: Transfer cards between lists seamlessly
• Comment system: Add comments to cards for collaboration
• Bulk operations: Process multiple cards efficiently

🏷️ Smart Labeling

• Manual labeling: Apply labels to unlabeled cards in bulk
• AI-powered labeling: Automatically categorize cards using Google Gemini AI
• Label management: Create, delete, and organize labels
• Intelligent suggestions: Get context-aware label recommendations

🤖 AI Features

• Google Gemini integration: Leverage AI for intelligent card processing
• Automatic categorization: Smart labeling based on card content
• Context understanding: AI analyzes card titles and descriptions
• Batch processing: Handle multiple cards with AI assistance

⚙️ Configuration & Setup

• Easy API setup: Simple configuration for Trello and Gemini APIs
• Default boards: Set frequently-used boards as defaults
• Secure storage: API keys stored securely in local database
• Environment support: Load configuration from .env files

🔧 Advanced Tools

• Automated archiving: Archive inactive cards based on age
• Export functionality: Backup boards to Loomic format
• Database management: Local SQLite database for settings
• Comprehensive help: Built-in help system for all commands

💻 Multiple Distribution Options

• PyPI package: pip install trello-tools
• Standalone executable: No Python required (~40MB)
• Source installation: Full development setup
• Cross-platform: Works on Windows, macOS, and Linux

Installation

📦 From PyPI (Recommended)

pip install trello-tools
trello-tools --help

⚡ Standalone Executable (No Python Required)

Download the latest trello-tools.exe (~40MB) from GitHub Releases:

1. Go to Releases
2. Download trello-tools.exe from the latest release
3. Run it directly: trello-tools.exe --help

Perfect for users who don't have Python installed!

🔧 From Source (Development)

# Clone the repository
git clone https://github.com/jhaisley/trello-tools.git
cd trello-tools

# Install with uv (recommended for development)
uv sync
uv run trello-tools --help

# Or install with pip
pip install -e .
trello-tools --help

Configuration

Before you can use the Trello CLI, you need to configure your Trello API credentials and, optionally, your Gemini API key.

Trello API

1. Get your API Key and Token:

   • Go to https://trello.com/app-key to get your API key.
   • From that page, you can also generate a token.

2. Set your credentials: You can set your credentials in two ways:

   • Using the config trello command:

     trello-tools config trello

     You will be prompted to enter your API key, API secret, and token.

   • Using a .env file: Create a .env file in your home directory (~/.env) with the following content:

     TRELLO_API_KEY="your_api_key"
     TRELLO_API_SECRET="your_api_secret"
     TRELLO_TOKEN="your_token"
     

     Then, load the configuration:

     trello-tools config load

Gemini API (for AI labeling)

1. Get your API Key:

   • Go to https://makersuite.google.com/ to get your Gemini API key.

2. Set your API key:

   trello-tools config gemini

   You will be prompted to enter your API key.

Set a Default Board

You can set a default board to avoid having to specify the board ID for every command.

1. Find your board ID: You can find your board ID by running:

   trello-tools boards show

   The board ID is the long string of characters after the board name.

2. Set the default board:

   trello-tools config set-default-board "your_board_id"

Usage

The Trello CLI is organized into several subcommands.

General Help

You can get help for any command or subcommand by using the --help flag.

trello-tools --help
trello-tools boards --help
trello-tools cards --help

Board Commands

• Show all boards:

  trello-tools boards show

• Create a new board:

  trello-tools boards create "My New Board"

• List all lists on a board:

  trello-tools boards lists --board-id "your_board_id"

Card Commands

• Create a new card:

  trello-tools cards create "your_list_id" "My New Card"

• Move a card to another list:

  trello-tools cards move "your_card_id" "your_new_list_id"

• Add a comment to a card:

  trello-tools cards comment "your_card_id" "This is a comment."

Label Commands

• List all labels on a board:

  trello-tools labels list --board-id "your_board_id"

• Create a new label:

  trello-tools labels create "My New Label" "blue" --board-id "your_board_id"

Automated Tasks

• Apply a label to all unlabeled cards:

  trello-tools label "My Label" --board-id "your_board_id"

• Automatically label cards using AI:

  trello-tools ai-label --board-id "your_board_id"

• Archive inactive cards:

  trello-tools archive --days 30 --board-id "your_board_id"

Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/jhaisley/trello-tools.git
cd trello-tools

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .[dev]

Development Tools

• Testing: uv run pytest or pytest
• Linting: uv run ruff check .
• Formatting: uv run ruff format .
• Type checking: Built into ruff
• Security scanning: uv run bandit -r src/

Building and Releasing

# Build packages
uv build

# Build standalone executable
python build_executable.py

# Version management
uv run bump2version patch  # or minor, major

# Full release process
python version_manager.py patch --release

Project Structure

trello-tools/
├── src/trello_cli/         # Main package code
├── tests/                  # Test suite
├── dist/                   # Built packages and executables
├── build_executable.py     # Executable building script
├── version_manager.py      # Version and release management
├── VERSION_MANAGEMENT.md   # Version management guide
└── pyproject.toml          # Project configuration

See VERSION_MANAGEMENT.md for detailed development workflows.

Testing

To run the tests, you will need to install the development dependencies and then run pytest:

pip install -e .[dev]
pytest

Contributing

Contributions are welcome! Please feel free to submit a pull request.

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature).
3. Make your changes.
4. Commit your changes (git commit -am 'Add some feature').
5. Push to the branch (git push origin feature/your-feature).
6. Create a new Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This project is not affiliated with, endorsed by, or in any way officially connected with Trello, Inc. or any of its subsidiaries or its affiliates. The official Trello website can be found at https://trello.com.