Trello CLI Unofficial

An unofficial Trello CLI using Power-Up authentication, built with Bun for maximum performance. Features automated dependency management with Bun installation during setup.

🚀 Features

• ⚡ Ultra-fast: Built with Bun (10-50x faster than Node.js)
• 🔐 Power-Up Authentication: Compatible with Trello's newer authentication system
• 💾 Persistent Configuration: Automatically saves your token
• 🎯 Interactive Interface: Intuitive menu with interactive prompts
• 📋 Complete Management: Boards, lists, cards with detailed information
• ✏️ CRUD Operations: Create, read, update, and delete cards
• 📦 Move Cards: Between lists in the same board
• 👀 Detailed Views: Show comprehensive board and card details
• 📊 Multiple Output Formats: Table, JSON, CSV formats
• 🏷️ Rich Metadata: Labels, members, checklists, and attachments support
• 🛠️ Traditional CLI: Also works as a command-line tool
• 🌍 Internationalization: Support for Portuguese (pt-BR) and English (en) with auto-detection
• 🤖 Automated CI/CD: Semantic versioning and NPM publishing on every release
• 🧪 Quality Gates: 95% test coverage threshold enforced in CI/CD
• 🔐 Secure Publishing: NPM provenance with GitHub Actions OIDC

📦 Installation

Prerequisites

• Node.js 16+ (Required)
• Bun (Required) - Deve ser instalado separadamente
• Trello account with Power-Up enabled
• Supported Platforms: Linux, macOS, Windows

NPM Installation (Recommended)

O CLI requer Bun para funcionar. Instale-o primeiro:

# 1. Instale o Bun primeiro
curl -fsSL https://bun.sh/install | bash
# ou no Windows: powershell -c "irm bun.sh/install.ps1 | iex"

# 2. Instale o CLI
npm install -g trello-cli-unofficial

# 3. Use
tcu --version

Ready to use immediately!

tcu --version

Windows Installation

Para usuários Windows, primeiro instale o Bun, depois o CLI:

# 1. Instale o Bun
powershell -c "irm bun.sh/install.ps1 | iex"

# 2. Instale o CLI
npm install -g trello-cli-unofficial

# 3. Use
tcu --version

Nota: No Windows, você pode precisar reiniciar o terminal após instalar o Bun.

Manual Installation (Development)

# Clone the repository
git clone https://github.com/JaegerCaiser/trello-cli-unofficial.git
cd trello-cli-unofficial

# Install dependencies
bun install

# Install globally (optional)
bun link

🔧 Configuration

First Run Setup

On first run, the CLI will guide you through setup:

# Run the CLI
tcu

# Or if running from source
bun run main.ts

The CLI will ask for your Trello token. To get it:

1. Go to https://trello.com/power-ups/admin
2. Create a new Power-Up or use an existing one
3. Copy the "API Key" and generate a token
4. Paste the token when prompted (starts with ATTA...)

Manual Configuration

# Configure token interactively
tcu setup

# View current configuration
tcu config

Configuration File

The token is automatically saved in ~/.trello-cli-unofficial/config.json:

{
  "apiKey": "630a01228b85df706aa520f3611e6490",
  "token": "ATTA..."
}

Environment Variables

You can configure the CLI using environment variables instead of the configuration file:

# Copy the example file
cp .env.example .env

# Edit with your credentials
nano .env

Available environment variables:

• TRELLO_API_KEY: Your Trello API key (optional, defaults to built-in key)
• TRELLO_TOKEN: Your Trello token (optional, will be prompted if not set)

Example .env file:

# Trello CLI Unofficial - Environment Variables
TRELLO_TOKEN=ATTA...
TRELLO_API_KEY=your-custom-api-key

Security Note: Never commit your .env file to version control. The .env.example file contains safe defaults.

Internationalization (i18n)

The CLI automatically detects your system language and displays messages in the appropriate language.

Supported Languages

• 🇧🇷 Portuguese (pt-BR) - Default for Portuguese-speaking systems
• 🇺🇸 English (en) - Default for other systems

Language Detection

The language is automatically detected from your system's LANG environment variable:

# Force Portuguese
LANG=pt_BR.UTF-8 tcu

# Force English
LANG=en_US.UTF-8 tcu

Manual Language Switching

import { changeLanguage } from "trello-cli-unofficial";

// Switch to Portuguese
changeLanguage("pt-BR");

// Switch to English
changeLanguage("en");

📖 Usage

Interactive Mode (Recommended)

# Start interactive mode
tcu

# Or the full command name
trello-cli-unofficial

Main menu options:

• 📋 View my boards
• 📝 Explore board
• ➕ Create card
• ⚙️ Settings
• 🚪 Exit

Direct Commands

# View all boards
tcu boards list

# Show detailed board information
tcu boards show <boardId>

# View lists in a board
tcu lists list <boardId>

# View cards in a list
tcu cards list <listId>

# Show detailed card information
tcu cards show <cardId>

# Create a new card
tcu cards create <listId> <name> [--desc "description"]

# Update an existing card
tcu cards update <cardId> --name "new name" [--desc "new description"]

# Move a card to another list
tcu cards move <cardId> --to <listId>

# Delete a card
tcu cards delete <cardId>

# Start interactive mode
tcu interactive

# Configure token
tcu setup

# Show version
tcu --version

# Output format options (available for most commands)
tcu boards list --format json
tcu boards list --format csv
tcu boards list --format table  # default

🏗️ Command Structure

The CLI uses a hierarchical subcommand structure for better organization:

tcu [command] [subcommand] [options] [arguments]

Main Commands

• boards - Manage Trello boards

  • list - List all boards
  • show <boardId> - Show detailed board information
  • create <name> - Create a new board
  • delete <boardId> - Delete a board

• lists - Manage Trello lists

  • list <boardId> - List all lists in a board
  • create <boardId> <name> - Create a new list
  • delete <listId> - Delete a list
  • move <listId> <position> - Move list to new position

• cards - Manage Trello cards

  • list <listId> - List all cards in a list
  • show <cardId> - Show detailed card information
  • create <listId> <name> - Create a new card
  • update <cardId> - Update an existing card
  • move <cardId> - Move card to another list
  • delete <cardId> - Delete a card

• config - Configuration management

  • setup - Configure Trello token
  • show - Display current configuration

Global Options

• --format <format> - Output format: table (default), json, csv
• --help - Show help for any command
• --version - Show CLI version

Interactive Mode

# Start interactive menu
tcu

# Or explicitly
tcu interactive

📚 Usage Examples

View Boards

# List all your boards
tcu boards list

# Show detailed information about a specific board
tcu boards show 60d5ecb74e2b8c3b8c8c8c8c

# Export boards to JSON
tcu boards list --format json

# Export boards to CSV
tcu boards list --format csv

Manage Lists

# List all lists in a board
tcu lists list 60d5ecb74e2b8c3b8c8c8c8c

Manage Cards

# List all cards in a list
tcu cards list 60d5ecb74e2b8c3b8c8c8c8d

# Show detailed information about a card
tcu cards show 60d5ecb74e2b8c3b8c8c8c8e

# Create a new card
tcu cards create 60d5ecb74e2b8c3b8c8c8c8d "Implement new feature" --desc "Add support for card templates"

# Update an existing card
tcu cards update 60d5ecb74e2b8c3b8c8c8c8e --name "Updated feature name" --desc "Updated description"

# Move a card to another list
tcu cards move 60d5ecb74e2b8c3b8c8c8c8e --to 60d5ecb74e2b8c3b8c8c8c8f

# Delete a card
tcu cards delete 60d5ecb74e2b8c3b8c8c8c8e

Create a Card

# Interactive mode
tcu
# Select "➕ Create card"
# Choose board → list → enter name and description

Explore a Board

# Interactive mode
tcu
# Select "📝 Explore board"
# Choose board → list → see cards
# Optionally: edit, delete, or move cards

Show Card Details

# Show detailed information about a card, including checklists, members, labels and attachments
tcu cards show <cardId>

Output Formats

# Table format (default)
tcu boards list

# JSON format
tcu boards list --format json

# CSV format
tcu boards list --format csv

# All formats work with most commands
tcu cards list <listId> --format json
tcu lists list <boardId> --format csv

🔄 Backward Compatibility

Legacy Command Support

During the transition period, the CLI maintains backward compatibility with older command formats. These legacy commands will show deprecation warnings but continue to work:

# Legacy commands (show deprecation warnings)
tcu boards                    # → Use "tcu boards list" instead
tcu lists legacy <boardName>  # → Use "tcu lists list <boardId>" instead
tcu cards legacy <boardName> <listName>  # → Use "tcu cards list <listId>" instead

# Legacy card management commands
tcu create-card <boardName> <listName> <cardName>
tcu move-card <cardId> <listName>
tcu delete-card <cardId>

Migration Guide

| Old Command | New Command | Status | |-------------|-------------|--------| | tcu boards | tcu boards list | ⚠️ Deprecated | | tcu lists <boardName> | tcu lists list <boardId> | ⚠️ Deprecated | | tcu cards <boardName> <listName> | tcu cards list <listId> | ⚠️ Deprecated | | tcu create-card <boardName> <listName> <name> | tcu cards create <listId> <name> | ⚠️ Deprecated | | tcu move-card <cardId> <listName> | tcu cards move <cardId> --to <listId> | ⚠️ Deprecated | | tcu delete-card <cardId> | tcu cards delete <cardId> | ⚠️ Deprecated |

Migration Timeline:

• Current: Legacy commands work with deprecation warnings
• Future: Legacy commands will be removed (TBD)

Why the Changes?

The new command structure provides:

• Better organization with hierarchical subcommands
• Improved discoverability with tcu <command> --help
• Consistency with modern CLI patterns
• Future extensibility for additional subcommands

🤖 CI/CD & Automation

This project uses automated CI/CD with semantic versioning based on commit messages:

Version Bumping

• feat: commits → Minor version bump (0.5.0 → 0.6.0)
• fix: commits → Patch version bump (0.5.0 → 0.5.1)
• BREAKING CHANGE: in commit body → Major version bump (0.5.0 → 1.0.0)
• Other commits (docs, test, chore) → No release

Automated Publishing

Every push to main branch triggers:

1. CI Pipeline: Linting, type checking, tests, coverage, and build
2. Release Pipeline: Automatic version bump based on commit message
3. NPM Publishing: Package published with provenance and signed builds
4. GitHub Release: Automatic release notes and changelog

Conventional Commits

# Feature commit (minor version bump)
git commit -m "feat: add new card templates"

# Bug fix (patch version bump)
git commit -m "fix: handle network timeouts gracefully"

# Breaking change (major version bump) - Method 1
git commit -m "feat!: redesign authentication flow"

# Breaking change (major version bump) - Method 2
git commit -m "feat: redesign authentication flow

BREAKING CHANGE: token format changed from legacy API to Power-Up"

# Non-releasing commits
git commit -m "docs: update installation guide"
git commit -m "test: add integration tests"
git commit -m "chore: update dependencies"

Important: Version bumps are automatic and based on the commit message when merged to main, not PR titles or descriptions.

🛠️ Development

Project Structure

trello-cli-unofficial/
├── src/
│   ├── domain/           # Business logic & entities
│   ├── application/      # Use cases & orchestration
│   ├── infrastructure/   # External implementations
│   └── presentation/     # CLI controllers & UI
├── tests/                # Test suite (57 tests)
├── .github/workflows/    # CI/CD pipelines
├── main.ts              # Entry point
├── package.json         # Dependencies & scripts
└── README.md           # This documentation

Dependencies

• commander: CLI framework
• inquirer: Interactive prompts
• fs-extra: File operations
• dotenv: Environment variables

Available Scripts

# Run locally
bun run main.ts

# Development with watch mode
bun run --watch main.ts

# Build for production
bun run build

# Run tests
bun test

# Run tests with coverage
bun test:coverage

# Validation (lint + typecheck + test)
bun run validate

# Type checking only
bun run typecheck

# Linting only
bun run lint

🔧 Architecture & Extensibility

Domain-Driven Design Structure

The CLI follows Domain-Driven Design principles with clear separation of concerns:

src/
├── domain/           # Business logic & entities
│   ├── entities/     # Board, List, Card entities
│   ├── repositories/ # Repository interfaces
│   └── services/     # Domain services (Authentication)
├── application/      # Use cases & business logic
│   └── use-cases/    # Business operations
├── infrastructure/   # External implementations
│   ├── repositories/ # Trello API, File system implementations
│   └── external/     # External service integrations
├── presentation/     # CLI interface layer
│   └── cli/         # Command controllers & UI
└── shared/          # Cross-cutting concerns
    ├── ErrorHandler.ts
    ├── OutputFormatter.ts
    └── types.ts

Adding New Commands

To extend the CLI with new functionality:

1. Create a Use Case in src/application/use-cases/
2. Implement Repository Interface if needed
3. Add Controller Method in appropriate CLI controller
4. Register Command in CommandController.ts
5. Add Tests following the existing pattern

Output Formatters

The CLI supports multiple output formats through the OutputFormatter class:

• Table: Human-readable tabular output (default)
• JSON: Machine-readable structured data
• CSV: Spreadsheet-compatible format

All formatters handle complex nested data structures automatically.

🧪 Cross-Platform Development Testing

This project includes tools for testing cross-platform compatibility during development:

Quick Cross-Platform Test

# Run comprehensive cross-platform tests
bun run test:cross-platform

# This will test:
# ✅ Build process
# ✅ Installation process
# ✅ CLI functionality (--version, --help)
# ✅ File system operations
# ✅ Environment variable handling
# ✅ Platform-specific features

Individual Test Commands

# Test build process only
bun run test:build

# Test installation process
bun run test:install

# Quick smoke tests
bun run test:smoke

Docker-Based Cross-Platform Testing

For comprehensive testing across platforms, use Docker containers:

# Test on all platforms (Linux + Windows when available)
npm run test:docker

# Test specific platforms
npm run test:docker:ubuntu    # Ubuntu Linux
npm run test:docker:alpine    # Alpine Linux
npm run test:docker:windows   # Windows (requires Windows host or WSL2)

Platform Support:

• ✅ Linux: Ubuntu 22.04, Ubuntu 20.04, Alpine Linux
• ✅ Windows: Windows Server Core 2022 (via Docker Desktop)
• ✅ macOS: Tested via GitHub Actions CI/CD

Requirements:

• Docker Desktop installed
• 4GB+ RAM allocated to Docker
• For Windows containers: Windows 10/11 Pro+ or WSL2

See WINDOWS_TESTING.md for detailed Windows setup instructions.

Manual Windows Testing Checklist

When testing on Windows, verify these scenarios:

1. Installation Methods:

   # Method 1: NPM global install
   npm install -g trello-cli-unofficial
   
   # Method 2: From source
   bun install
   bun link  # or bun run install-global

2. Command Availability:

   # Test both command names
   tcu --version
   trello-cli-unofficial --version
   
   # Test in different terminals
   # - Command Prompt (cmd)
   # - PowerShell
   # - Windows Terminal

3. PATH Configuration:

   # Check if commands are in PATH
   where tcu
   where trello-cli-unofficial
   
   # Refresh environment (PowerShell)
   $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

4. File System Operations:

   • Config directory creation: %USERPROFILE%\.trello-cli-unofficial\
   • File read/write permissions
   • Path separator handling (\ vs /)

5. Environment Variables:

   • TRELLO_TOKEN handling
   • Language detection (LANG, LC_ALL, etc.)
   • Node.js/Bun path resolution

Common Windows Issues & Solutions

| Issue | Symptom | Solution | |-------|---------|----------| | PATH not updated | tcu command not found | Restart terminal or run refreshenv | | Permission denied | Installation fails | Run as Administrator | | Antivirus blocking | Installation interrupted | Temporarily disable or whitelist | | Node version conflicts | Runtime errors | Use Node 18+ or Bun 1.0+ |

🔒 Security

• Token saved locally in protected file (~/.trello-cli-unofficial/config.json)
• No data sent to external servers
• Uses HTTPS for all Trello API communications
• Compatible with Trello's Power-Up authentication
• NPM packages published with provenance attestation

🐛 Troubleshooting

401 Unauthorized Error

• Verify the token is correct and starts with ATTA
• Confirm the Power-Up has necessary permissions
• Try generating a new token from trello.com/power-ups/admin

Network Error

• Check your internet connection
• Confirm api.trello.com is accessible
• Try again in a few minutes

Configuration Not Saving

• Check write permissions in ~/.trello-cli-unofficial/
• Run as user with appropriate permissions
• Try running tcu setup again

Installation Issues

• Runtime Required: Ensure Bun or Node.js 16+ is installed
• Package Manager Fallback: Try npm install -g trello-cli-unofficial if Bun fails
• PATH Issues: Check that tcu command is in your PATH
• Permission Issues: Try running as administrator/sudo

Windows-specific Issues

• PATH not updated: Restart your terminal or run refreshenv in PowerShell
• Permission errors: Run PowerShell/Command Prompt as Administrator
• Node.js version: Ensure you have Node.js 16+ or Bun 1.0+
• Antivirus blocking: Some antivirus software may block global NPM installations

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide before submitting PRs.

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes using conventional commits (git commit -m 'feat: add some amazing feature')
4. Run the tests (bun run validate)
5. Push to the branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

Development Setup

# Clone and setup
git clone https://github.com/JaegerCaiser/trello-cli-unofficial.git
cd trello-cli-unofficial
bun install

# Run tests
bun test

# Start development
bun run --watch main.ts

📜 License

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

🙏 Acknowledgments

• Trello API - Official Trello REST API
• Bun - Ultra-fast JavaScript runtime
• Inquirer - Interactive command-line interface
• Commander - CLI framework for Node.js
• GitHub Actions - CI/CD automation

📊 Project Status

• 🚀 195 tests passing (100% coverage)
• 📦 Clean Domain-Driven Design architecture
• 🎨 ESLint + TypeScript strict mode
• ⚡ Performance optimized with Bun
• 🤖 Automated CI/CD with semantic versioning
• 🔒 Secure publishing with NPM provenance
• 🌍 Internationalization (pt-BR/en)
• 📊 Multiple output formats (table/json/csv)
• 🏗️ Hierarchical command structure

Note: This is an unofficial project and is not affiliated with Atlassian or Trello.

Made with ❤️, Bun, and automated CI/CD