# Trello Tools
[](https://pypi.org/project/trello-tools)
[](https://pypi.org/project/trello-tools)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/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)
```bash
pip install trello-tools
trello-tools --help
```
### Option 2: Download Standalone Executable
No Python required! Download the latest `trello-tools.exe` from [GitHub Releases](https://github.com/jhaisley/trello-tools/releases).
### Option 3: Install from Source
```bash
git clone https://github.com/jhaisley/trello-tools.git
cd trello-tools
pip install -e .
```
## Table of Contents
- [Trello Tools](#trello-tools)
- [Description](#description)
- [History](#history)
- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Trello API](#trello-api)
- [Gemini API (for AI labeling)](#gemini-api-for-ai-labeling)
- [Set a Default Board](#set-a-default-board)
- [Usage](#usage)
- [General Help](#general-help)
- [Board Commands](#board-commands)
- [Card Commands](#card-commands)
- [Label Commands](#label-commands)
- [Automated Tasks](#automated-tasks)
- [Development](#development)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)
- [Disclaimer](#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)
```bash
pip install trello-tools
trello-tools --help
```
### ⚡ Standalone Executable (No Python Required)
Download the latest `trello-tools.exe` (~40MB) from [GitHub Releases](https://github.com/jhaisley/trello-tools/releases):
1. Go to [Releases](https://github.com/jhaisley/trello-tools/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)
```bash
# 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](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**:
```bash
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:
```bash
trello-tools config load
```
### Gemini API (for AI labeling)
1. **Get your API Key**:
- Go to [https://makersuite.google.com/](https://makersuite.google.com/) to get your Gemini API key.
2. **Set your API key**:
```bash
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:
```bash
trello-tools boards show
```
The board ID is the long string of characters after the board name.
2. **Set the default board**:
```bash
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.
```bash
trello-tools --help
trello-tools boards --help
trello-tools cards --help
```
### Board Commands
- **Show all boards**:
```bash
trello-tools boards show
```
- **Create a new board**:
```bash
trello-tools boards create "My New Board"
```
- **List all lists on a board**:
```bash
trello-tools boards lists --board-id "your_board_id"
```
### Card Commands
- **Create a new card**:
```bash
trello-tools cards create "your_list_id" "My New Card"
```
- **Move a card to another list**:
```bash
trello-tools cards move "your_card_id" "your_new_list_id"
```
- **Add a comment to a card**:
```bash
trello-tools cards comment "your_card_id" "This is a comment."
```
### Label Commands
- **List all labels on a board**:
```bash
trello-tools labels list --board-id "your_board_id"
```
- **Create a new label**:
```bash
trello-tools labels create "My New Label" "blue" --board-id "your_board_id"
```
### Automated Tasks
- **Apply a label to all unlabeled cards**:
```bash
trello-tools label "My Label" --board-id "your_board_id"
```
- **Automatically label cards using AI**:
```bash
trello-tools ai-label --board-id "your_board_id"
```
- **Archive inactive cards**:
```bash
trello-tools archive --days 30 --board-id "your_board_id"
```
## Development
### Setting Up Development Environment
```bash
# 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
```bash
# 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
```text
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](VERSION_MANAGEMENT.md) for detailed development workflows.
## Testing
To run the tests, you will need to install the development dependencies and then run `pytest`:
```bash
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](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](https://trello.com).
Raw data
{
"_id": null,
"home_page": null,
"name": "trello-tools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "cli, productivity, project-management, trello",
"author": null,
"author_email": "Jordan Haisley <jordanhaisley@google.com>",
"download_url": "https://files.pythonhosted.org/packages/b9/86/e311548ef96e2880f2695368ebf85bec18a6e0e1046593c5ea6368d2c485/trello_tools-0.2.0.tar.gz",
"platform": null,
"description": "# Trello Tools\n\n[](https://pypi.org/project/trello-tools)\n[](https://pypi.org/project/trello-tools)\n[](https://opensource.org/licenses/MIT)\n[](https://pypi.org/project/trello-tools)\n\nA powerful command-line interface (CLI) for interacting with Trello. Manage your boards, lists, cards, and labels without leaving the terminal.\n\n## \ud83d\ude80 Quick Start\n\n### Option 1: Install from PyPI (Recommended)\n```bash\npip install trello-tools\ntrello-tools --help\n```\n\n### Option 2: Download Standalone Executable\nNo Python required! Download the latest `trello-tools.exe` from [GitHub Releases](https://github.com/jhaisley/trello-tools/releases).\n\n### Option 3: Install from Source\n```bash\ngit clone https://github.com/jhaisley/trello-tools.git\ncd trello-tools\npip install -e .\n```\n\n## Table of Contents\n\n- [Trello Tools](#trello-tools)\n - [Description](#description)\n - [History](#history)\n - [Features](#features)\n - [Installation](#installation)\n - [Configuration](#configuration)\n - [Trello API](#trello-api)\n - [Gemini API (for AI labeling)](#gemini-api-for-ai-labeling)\n - [Set a Default Board](#set-a-default-board)\n - [Usage](#usage)\n - [General Help](#general-help)\n - [Board Commands](#board-commands)\n - [Card Commands](#card-commands)\n - [Label Commands](#label-commands)\n - [Automated Tasks](#automated-tasks)\n - [Development](#development)\n - [Testing](#testing)\n - [Contributing](#contributing)\n - [License](#license)\n - [Disclaimer](#disclaimer)\n\n## Description\n\nThis 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.\n\n## History\n\nThis 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.\n\nThe CLI has since been used for various purposes, including:\n- Managing technical support tickets\n- Tracking outages\n- Creating boards for new clients and projects\n- CI/CD remediation and integration\n\nGiven its wide range of uses, the project has been made public to be used by a wider audience.\n\n## Features\n\n### \ud83d\udccb **Board Management**\n- **View all boards**: List all your Trello boards with IDs\n- **Create new boards**: Set up new projects instantly\n- **List management**: View all lists on any board\n- **Board reporting**: Generate activity reports\n\n### \ud83c\udccf **Card Operations**\n- **Create cards**: Add new cards to any list\n- **Move cards**: Transfer cards between lists seamlessly\n- **Comment system**: Add comments to cards for collaboration\n- **Bulk operations**: Process multiple cards efficiently\n\n### \ud83c\udff7\ufe0f **Smart Labeling**\n- **Manual labeling**: Apply labels to unlabeled cards in bulk\n- **AI-powered labeling**: Automatically categorize cards using Google Gemini AI\n- **Label management**: Create, delete, and organize labels\n- **Intelligent suggestions**: Get context-aware label recommendations\n\n### \ud83e\udd16 **AI Features** \n- **Google Gemini integration**: Leverage AI for intelligent card processing\n- **Automatic categorization**: Smart labeling based on card content\n- **Context understanding**: AI analyzes card titles and descriptions\n- **Batch processing**: Handle multiple cards with AI assistance\n\n### \u2699\ufe0f **Configuration & Setup**\n- **Easy API setup**: Simple configuration for Trello and Gemini APIs\n- **Default boards**: Set frequently-used boards as defaults\n- **Secure storage**: API keys stored securely in local database\n- **Environment support**: Load configuration from `.env` files\n\n### \ud83d\udd27 **Advanced Tools**\n- **Automated archiving**: Archive inactive cards based on age\n- **Export functionality**: Backup boards to Loomic format\n- **Database management**: Local SQLite database for settings\n- **Comprehensive help**: Built-in help system for all commands\n\n### \ud83d\udcbb **Multiple Distribution Options**\n- **PyPI package**: `pip install trello-tools`\n- **Standalone executable**: No Python required (~40MB)\n- **Source installation**: Full development setup\n- **Cross-platform**: Works on Windows, macOS, and Linux\n\n\n## Installation\n\n### \ud83d\udce6 From PyPI (Recommended)\n\n```bash\npip install trello-tools\ntrello-tools --help\n```\n\n### \u26a1 Standalone Executable (No Python Required)\n\nDownload the latest `trello-tools.exe` (~40MB) from [GitHub Releases](https://github.com/jhaisley/trello-tools/releases):\n\n1. Go to [Releases](https://github.com/jhaisley/trello-tools/releases)\n2. Download `trello-tools.exe` from the latest release\n3. Run it directly: `trello-tools.exe --help`\n\nPerfect for users who don't have Python installed!\n\n### \ud83d\udd27 From Source (Development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/jhaisley/trello-tools.git\ncd trello-tools\n\n# Install with uv (recommended for development)\nuv sync\nuv run trello-tools --help\n\n# Or install with pip\npip install -e .\ntrello-tools --help\n```\n\n## Configuration\n\nBefore you can use the Trello CLI, you need to configure your Trello API credentials and, optionally, your Gemini API key.\n\n### Trello API\n\n1. **Get your API Key and Token**:\n - Go to [https://trello.com/app-key](https://trello.com/app-key) to get your API key.\n - From that page, you can also generate a token.\n\n2. **Set your credentials**:\n You can set your credentials in two ways:\n\n - **Using the `config trello` command**:\n ```bash\n trello-tools config trello\n ```\n You will be prompted to enter your API key, API secret, and token.\n\n - **Using a `.env` file**:\n Create a `.env` file in your home directory (`~/.env`) with the following content:\n ```\n TRELLO_API_KEY=\"your_api_key\"\n TRELLO_API_SECRET=\"your_api_secret\"\n TRELLO_TOKEN=\"your_token\"\n ```\n Then, load the configuration:\n ```bash\n trello-tools config load\n ```\n\n### Gemini API (for AI labeling)\n\n1. **Get your API Key**:\n - Go to [https://makersuite.google.com/](https://makersuite.google.com/) to get your Gemini API key.\n\n2. **Set your API key**:\n ```bash\n trello-tools config gemini\n ```\n You will be prompted to enter your API key.\n\n### Set a Default Board\n\nYou can set a default board to avoid having to specify the board ID for every command.\n\n1. **Find your board ID**:\n You can find your board ID by running:\n ```bash\n trello-tools boards show\n ```\n The board ID is the long string of characters after the board name.\n\n2. **Set the default board**:\n ```bash\n trello-tools config set-default-board \"your_board_id\"\n ```\n\n## Usage\n\nThe Trello CLI is organized into several subcommands.\n\n### General Help\n\nYou can get help for any command or subcommand by using the `--help` flag.\n\n```bash\ntrello-tools --help\ntrello-tools boards --help\ntrello-tools cards --help\n```\n\n### Board Commands\n\n- **Show all boards**:\n ```bash\n trello-tools boards show\n ```\n\n- **Create a new board**:\n ```bash\n trello-tools boards create \"My New Board\"\n ```\n\n- **List all lists on a board**:\n ```bash\n trello-tools boards lists --board-id \"your_board_id\"\n ```\n\n### Card Commands\n\n- **Create a new card**:\n ```bash\n trello-tools cards create \"your_list_id\" \"My New Card\"\n ```\n\n- **Move a card to another list**:\n ```bash\n trello-tools cards move \"your_card_id\" \"your_new_list_id\"\n ```\n\n- **Add a comment to a card**:\n ```bash\n trello-tools cards comment \"your_card_id\" \"This is a comment.\"\n ```\n\n### Label Commands\n\n- **List all labels on a board**:\n ```bash\n trello-tools labels list --board-id \"your_board_id\"\n ```\n\n- **Create a new label**:\n ```bash\n trello-tools labels create \"My New Label\" \"blue\" --board-id \"your_board_id\"\n ```\n\n### Automated Tasks\n\n- **Apply a label to all unlabeled cards**:\n ```bash\n trello-tools label \"My Label\" --board-id \"your_board_id\"\n ```\n\n- **Automatically label cards using AI**:\n ```bash\n trello-tools ai-label --board-id \"your_board_id\"\n ```\n\n- **Archive inactive cards**:\n ```bash\n trello-tools archive --days 30 --board-id \"your_board_id\"\n ```\n\n## Development\n\n### Setting Up Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/jhaisley/trello-tools.git\ncd trello-tools\n\n# Install with uv (recommended)\nuv sync\n\n# Or install with pip\npip install -e .[dev]\n```\n\n### Development Tools\n\n- **Testing**: `uv run pytest` or `pytest`\n- **Linting**: `uv run ruff check .`\n- **Formatting**: `uv run ruff format .`\n- **Type checking**: Built into ruff\n- **Security scanning**: `uv run bandit -r src/`\n\n### Building and Releasing\n\n```bash\n# Build packages\nuv build\n\n# Build standalone executable\npython build_executable.py\n\n# Version management\nuv run bump2version patch # or minor, major\n\n# Full release process\npython version_manager.py patch --release\n```\n\n### Project Structure\n\n```text\ntrello-tools/\n\u251c\u2500\u2500 src/trello_cli/ # Main package code\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 dist/ # Built packages and executables\n\u251c\u2500\u2500 build_executable.py # Executable building script\n\u251c\u2500\u2500 version_manager.py # Version and release management\n\u251c\u2500\u2500 VERSION_MANAGEMENT.md # Version management guide\n\u2514\u2500\u2500 pyproject.toml # Project configuration\n```\n\nSee [VERSION_MANAGEMENT.md](VERSION_MANAGEMENT.md) for detailed development workflows.\n\n## Testing\n\nTo run the tests, you will need to install the development dependencies and then run `pytest`:\n\n```bash\npip install -e .[dev]\npytest\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a pull request.\n\n1. Fork the repository.\n2. Create a new branch (`git checkout -b feature/your-feature`).\n3. Make your changes.\n4. Commit your changes (`git commit -am 'Add some feature'`).\n5. Push to the branch (`git push origin feature/your-feature`).\n6. Create a new Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\nThis 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](https://trello.com).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A CLI for interacting with Trello.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/jhaisley/trello-tools",
"Issues": "https://github.com/jhaisley/trello-tools/issues",
"Repository": "https://github.com/jhaisley/trello-tools"
},
"split_keywords": [
"cli",
" productivity",
" project-management",
" trello"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5f2391ff35e2b982f05d6bdfcdad03b9da36ba5588c1a9abf2a125b357f271c4",
"md5": "93151a2fa14d7c07925b257d8085ad2c",
"sha256": "69b679a97e1618dc9f9fb60d77a72949d10fed29cb457b0bcc7da6da6ce72e81"
},
"downloads": -1,
"filename": "trello_tools-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "93151a2fa14d7c07925b257d8085ad2c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 14176,
"upload_time": "2025-07-25T17:41:05",
"upload_time_iso_8601": "2025-07-25T17:41:05.840974Z",
"url": "https://files.pythonhosted.org/packages/5f/23/91ff35e2b982f05d6bdfcdad03b9da36ba5588c1a9abf2a125b357f271c4/trello_tools-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b986e311548ef96e2880f2695368ebf85bec18a6e0e1046593c5ea6368d2c485",
"md5": "74abf9ca69f1f03409c9a56812990397",
"sha256": "1137c4b644d4f3f85c877a9602a6867b5d2b744aff7711cc1b96c57f7ed85fdf"
},
"downloads": -1,
"filename": "trello_tools-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "74abf9ca69f1f03409c9a56812990397",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 81876,
"upload_time": "2025-07-25T17:41:07",
"upload_time_iso_8601": "2025-07-25T17:41:07.175953Z",
"url": "https://files.pythonhosted.org/packages/b9/86/e311548ef96e2880f2695368ebf85bec18a6e0e1046593c5ea6368d2c485/trello_tools-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 17:41:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jhaisley",
"github_project": "trello-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "trello-tools"
}
JSON
