Trello CLI v2.2

Official Python CLI for Trello - Extensible workflow management with plugin system and comprehensive board auditing.

✨ Features

🧠 Claude AI Context Analysis - Intelligent opinions on every card movement
🔌 Plugin System - Extensible architecture for custom functionality
🔍 Board Audit - Expose workflow chaos and structural problems (available as plugin!)
🤖 Optimized for Claude Code - AI-first design with discovery commands
🏃 Sprint Planning - Complete sprint lifecycle management
📦 Bulk Operations - Process multiple cards efficiently
📊 Board Standardization - Enforce Agile/Scrum best practices
🔍 Advanced Queries - Filter and analyze cards
⚡ Quick Workflows - Shortcuts for common operations
🎯 50+ Commands - Comprehensive board management

🆕 What's New in v2.2

🧠 Claude AI Context Analysis + Plugin System

Two major innovations in this release:

1. Intelligent Card Movement Analysis ⭐

Every card movement now includes Claude AI analysis:

What: Understands what the card is about (title, description, labels)
Why: Analyzes why the movement matters in context
Concerns: Identifies risks (overdue items, incomplete checklists, unmet criteria)
Recommendations: Provides actionable insights

Enhanced Commands:

trello move-card <card_id><list_id># General movement with analysis
trello quick-start <card_id># Start work with context insight
trello quick-test <card_id># Testing phase with validation analysis
trello quick-done <card_id># Completion with quality assessment

Example Output:

✅ Moved card 'Frontend: System Health Dashboard' to list '⚙️ In Progress'
💡 CLAUDE AI ANALYSIS
────────────────────────────────────────────────────────────
This card focuses on building a comprehensive monitoring dashboard...
Moving to "In Progress" signals the team is prioritizing observability...
The 12-16 hour estimate seems optimistic considering the scope includes
6 API integrations, real-time polling, and responsive design...

2. Production-Ready Plugin System

Language-agnostic (Python, Bash, JS, Ruby, Go, etc.)
Environment injection (credentials, config paths)
Metadata validation and discovery
Timeout protection and error handling

3. Official Board Audit Plugin

8 critical workflow validations
Health score system (0-100)
JSON output for CI/CD integration
600+ lines of production-ready code

Previous in v2.1:

29 new commands across 5 categories (Quick, Sprint, Bulk, Query, Standardization)
See CLAUDE.md for complete v2.1 features

📦 Installation

Prerequisites

pip3 install py-trello

Setup

Clone or download this repository
Add to PATH (already done if using from ~/Documents/trello-cli-python)
Configure API credentials:

trello config

Get your credentials from:

API Key: https://trello.com/app-key
Token: Follow the link provided during config

Optional: Claude AI Integration

For intelligent card movement analysis, configure Claude AI:

# Create .env file with your Anthropic API keyecho'ANTHROPIC_API_KEY=sk-ant-api03-YOUR_KEY_HERE'> .env
# Or set as environment variableexport ANTHROPIC_API_KEY=sk-ant-api03-YOUR_KEY_HERE

Get your API key from: https://console.anthropic.com/

Note: The system works without Claude AI (graceful degradation). With the API key, card movements include intelligent analysis.

🚀 Quick Start

For Claude Code Users

🎯 Essential Command:

trello help-json # Get ALL commands in JSON format

Key Discovery Commands:

trello boards # List all boards
trello board-overview <board_id># Complete board structure
trello board-ids <board_id># Quick ID reference
trello search-cards <board_id>"query"# Find cards anywhere

📖 Full Guide: CLAUDE.md

🔌 Plugin System - Extensibility at its Core

The Trello CLI features a production-ready plugin system that allows you to extend functionality without modifying core code.

Why This Matters

Even the board auditor runs as a plugin. If critical analysis logic can live externally, anything can.

This isn't just a feature - it's an architectural statement: The core doesn't need to change for the CLI to evolve.

Quick Start with Plugins

# List available plugins
trello plugin list
# See plugin details
trello plugin info board-audit
# Run the official board auditor plugin
trello plugin run board-audit <board_id># JSON output for CI/CD integration
trello plugin run board-audit <board_id> --json

🔍 Featured Plugin: Board Audit

Exposes the structural chaos that Trello hides.

Your board looks organized, but underneath:

❌ Cards in "Done" without due dates (can't measure velocity)
❌ Cards in "Done" with incomplete checklists (false completion)
❌ Overdue cards not marked complete (zombie tasks)
⚠️ Active cards without due dates (no accountability)
⚠️ Execution cards without owners (orphaned work)
⚠️ Empty checklists (fake productivity signals)

Real Example:

$ trello plugin run board-audit 68fcf05e481843db13204397
🔍 BOARD AUDIT REPORT - AI Portfolio Sprint 1
Health Score: 60/100 - 🟠 NEEDS ATTENTION
Critical Issues: 1
- 17 cards in Done without due dates
High Priority: 2
- 11 active cards without due dates
- 11 execution cards without owners

Health Score System:

90-100: 🟢 EXCELLENT - Board ready for production
70-89: 🟡 GOOD - Minor issues detected
50-69: 🟠 NEEDS ATTENTION - Significant workflow problems
0-49: 🔴 CRITICAL - Severe structural problems

Official Plugins Included

board-audit.py - Comprehensive workflow auditor (600+ lines, production-ready)
example-python.py - Python plugin template
example-bash.sh - Bash plugin template

Creating Your Own Plugins

Plugins can be written in any language (Python, Bash, JavaScript, Ruby, Go, etc.)

Example plugin structure:

#!/usr/bin/env python3# trello-plugin# name: My Plugin# description: What it does# usage: plugin run my-plugin [args]# author: Your Name# version: 1.0.0importosimportsys# Access injected credentialsapi_key=os.environ.get('TRELLO_API_KEY')
token=os.environ.get('TRELLO_TOKEN')
# Your plugin logic here...

Available Environment Variables:

TRELLO_API_KEY - Your API key
TRELLO_TOKEN - Your API token
TRELLO_USER_ID - Your user ID
TRELLO_BASE_URL - Trello API base URL
TRELLO_CLI_VERSION - CLI version
TRELLO_CONFIG_DIR - Config directory
TRELLO_PLUGIN_DIR - Plugin directory

📖 Full Plugin Guide: PLUGINS.md

📚 Command Categories

1. Discovery & Help (5 commands)

trello help# Show all commands
trello help-json # Get commands in JSON
trello board-overview <id># Board structure + metrics
trello board-ids <id># All IDs in one place
trello search-cards <id>"q"# Find cards by text

2. Quick Workflows (5 commands)

trello quick-start <card_id># Move to "In Progress" + comment
trello quick-test <card_id># Move to "Testing" + comment
trello quick-done <card_id># Move to "Done" + comment
trello my-cards <board_id># Show all assigned cards
trello card-age <list_id># See how old cards are

3. Sprint Planning (4 commands)

trello sprint-start <board_id># Start sprint (interactive)
trello sprint-status <board_id># Sprint progress dashboard
trello sprint-close <board_id># Close sprint + cleanup
trello sprint-velocity <board_id># Calculate team velocity

4. Bulk Operations (5 commands)

# Move multiple cards
trello bulk-move-cards <source_list><target_list> ["filter"]
# Label multiple cards
trello bulk-add-label cards.txt "red""Priority"# Set due dates in bulk
trello bulk-set-due cards.txt "2025-12-31"# Archive multiple cards
trello bulk-archive-cards <list_id> ["filter"]
# Create cards from CSV/JSON
trello bulk-create-cards <list_id> cards.csv

5. Advanced Queries (5 commands)

trello cards-by-label <board_id>"red"# Find by label
trello cards-due-soon <board_id> [days] # Due soon (default: 7d)
trello cards-overdue <board_id># Overdue cards
trello list-metrics <list_id># List analytics
trello board-health <board_id># Health check (score 0-100)

6. Board Standardization ⭐ NEW (4 commands)

trello list-templates # Show available templates
trello standardize-lists <id> agile # Apply template to board
trello scrum-check <board_id># Validate Agile conformity
trello migrate-cards <list><board># Move cards between boards

7. Basic CRUD (15+ commands)

# Boards
trello boards
trello create-board "Name"# Lists
trello lists <board_id>
trello create-list <board_id>"Name"
trello archive-list <list_id># Cards
trello cards <list_id>
trello add-card <list_id>"Title" ["Description"]
trello show-card <card_id>
trello update-card <card_id>"Description"
trello move-card <card_id><list_id># Enhancements
trello add-label <card_id>"color" ["name"]
trello add-checklist <card_id>"Name"
trello add-checkitem <card_id>"Checklist""Item"
trello set-due <card_id>"YYYY-MM-DD"
trello add-comment <card_id>"Text"

🎯 Common Use Cases

Use Case 1: Daily Workflow

# Morning: Check your cards
trello my-cards <board_id># Start working on a card
trello quick-start <card_id># Move to testing
trello quick-test <card_id># Mark as done
trello quick-done <card_id>

Use Case 2: Sprint Planning

# Check board health
trello scrum-check <board_id>
trello board-health <board_id># Start new sprint
trello sprint-start <board_id># Monitor progress
trello sprint-status <board_id># Close sprint
trello sprint-close <board_id>
trello sprint-velocity <board_id>

Use Case 3: Board Standardization

# Standardize all company boards
trello list-templates
trello standardize-lists <board_id> agile --dry-run
trello standardize-lists <board_id> agile
# Validate conformity
trello scrum-check <board_id>

Use Case 4: Bulk Cleanup

# Find overdue cards
trello cards-overdue <board_id># Archive old cards
trello bulk-archive-cards <list_id>"2023"# Move stale cards to backlog
trello card-age <list_id>
trello bulk-move-cards <source><backlog>

📖 Documentation

Essential Docs (in root)

README.md - This file
CLAUDE.md - Complete Claude Code integration guide

Additional Docs (in docs/)

docs/README.md - Documentation index
TESTING_GUIDE.md - Pytest setup
REPORTING_GUIDE.md - Export reports to HTML/PDF

Developer Docs

PROJECT_SUMMARY.md - Architecture
CONTRIBUTING.md - How to contribute
MIGRATION.md - v1→v2 migration

🎨 Board Templates

Three standard templates available:

1. Agile/Scrum (Full) - 12 lists

💡 Ideas → 📥 Inbox → 📋 Backlog → 📋 To Prioritize → 🔍 Refinement
→ ✅ Ready → 📐 Design → 📝 Sprint → ⚙️ In Progress → 🧪 Testing → ✅ Done → 📚 Architecture

2. Kanban (Simple) - 3 lists

📝 To Do → ⚙️ In Progress → ✅ Done

3. Basic Workflow - 4 lists

📋 Backlog → 📝 To Do → ⚙️ In Progress → ✅ Done

Apply with:

trello standardize-lists <board_id><template>

🔍 Scrum Conformity Checks

The scrum-check command validates:

✅ Required Lists - Backlog, Ready, Sprint, In Progress, Testing, Done
⚙️ WIP Limits - In Progress should have ≤3-5 cards
📝 Sprint Size - Sprint should have 5-15 cards
🧪 Testing Queue - Testing should have ≤3-5 cards
📋 Backlog Health - Should have 10-50 cards

Score: 0-100 with recommendations

🟢 EXCELLENT (90-100)
🟡 GOOD (70-89)
🟠 NEEDS WORK (50-69)
🔴 CRITICAL (<50)

trello scrum-check <board_id>

🛠️ Development

Project Structure

trello-cli-python/
├── trello_cli/
│ ├── commands/ # All command modules
│ │ ├── board.py
│ │ ├── list.py
│ │ ├── card.py
│ │ ├── bulk.py # Bulk operations
│ │ ├── quick.py # Quick shortcuts
│ │ ├── sprint.py # Sprint planning
│ │ ├── query.py # Advanced queries
│ │ ├── standardize.py # Board standardization
│ │ └── ...
│ ├── utils/ # Utilities
│ └── cli.py # Main CLI entry
├── tests/ # Test suite
├── docs/ # Documentation
└── trello # Executable

Running Tests

pytest tests/
pytest --cov=trello_cli tests/

🤝 Contributing

See CONTRIBUTING.md

📝 Examples

Example 1: Bulk Card Creation

# cards.csvtitle,description,due_date,labelsFeature A,Description A,2025-12-25,red:P0Feature B,Description B,2025-12-30,blue:Feature

trello bulk-create-cards <list_id> cards.csv

Example 2: Automated Reports

#!/bin/bash# Generate daily report
DATE=$(date +%Y-%m-%d)
trello scrum-check <board_id>>"reports/${DATE}_report.txt"
trello board-health <board_id>>>"reports/${DATE}_report.txt"

Example 3: Sprint Automation

# Start sprint on Monday
trello sprint-start <board_id># Daily standup - check status
trello sprint-status <board_id># Friday - close sprint
trello sprint-close <board_id>
trello sprint-velocity <board_id>

🎓 For Claude Code

Claude Code should always start with:

trello help-json

This returns all available commands in machine-readable format.

Key commands for AI:

board-overview - Understand board structure
search-cards - Find cards without knowing their location
scrum-check - Validate board health
bulk-* commands - Process multiple items efficiently

📖 Complete Guide: CLAUDE.md

📊 Statistics

Total Commands: 48
Command Categories: 7
Board Templates: 3
Lines of Code: ~5,000
Test Coverage: Expanding

🔗 Links

GitHub: bernardurizaorozco/trello-cli-python
Issues: Report bugs
Trello API: Documentation

📄 License

MIT License - See LICENSE

👤 Author

Bernard Uriza Orozco

🙏 Acknowledgments

Built with py-trello
Designed for Claude Code
Inspired by Agile/Scrum best practices

Version: 2.1.0 Last Updated: 2025-10-27

Name		Name	Last commit message	Last commit date
.claude/commands		.claude/commands
claude-daemon		claude-daemon
docs		docs
examples		examples
mcp_server		mcp_server
plugins		plugins
tests		tests
trello_cli		trello_cli
.claude_mcp_config.json		.claude_mcp_config.json
.clauderc		.clauderc
.gitignore		.gitignore
CHANGELOG_MCP.md		CHANGELOG_MCP.md
CLAUDE.md		CLAUDE.md
CLAUDE_DAEMON_INDEX.md		CLAUDE_DAEMON_INDEX.md
CLAUDE_DAEMON_VISION.md		CLAUDE_DAEMON_VISION.md
DAEMON_INTEGRATION_GUIDE.md		DAEMON_INTEGRATION_GUIDE.md
LICENSE		LICENSE
PLUGINS.md		PLUGINS.md
README.md		README.md
SETUP_CLAUDE_AI.md		SETUP_CLAUDE_AI.md
load_env.sh		load_env.sh
promote.sh		promote.sh
requirements.txt		requirements.txt
setup.py		setup.py
setup_mcp.py		setup_mcp.py
test_claude_integration.sh		test_claude_integration.sh
trello		trello

Latest commit

History

Folders and files

Repository files navigation