trello-cli-unofficial 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [0.17.0](https://github.com/JaegerCaiser/trello-cli-unofficial/compare/v0.16.0...v0.17.0) (2026-04-10)
+
+
+### Bug Fixes
+
+* handle SIGINT in auth setup prompt with translated cancel message ([f352e4f](https://github.com/JaegerCaiser/trello-cli-unofficial/commit/f352e4f5c4fe62b77573cbdb915cddbd4ae275cb))
+
+
+### Features
+
+* **search:** support advanced card search filters and pagination ([a5ebf31](https://github.com/JaegerCaiser/trello-cli-unofficial/commit/a5ebf31c434b4168d9745be1a99331dd536704a8))
+
 # [0.16.0](https://github.com/JaegerCaiser/trello-cli-unofficial/compare/v0.15.1...v0.16.0) (2026-04-09)
 
 

package/README.md

@@ -1,5 +1,7 @@
 # Trello CLI Unofficial
 
+*Read this in other languages: [English](#-english) | [Português](#-português)*
+
 [![npm version](https://img.shields.io/npm/v/trello-cli-unofficial.svg)](https://www.npmjs.com/package/trello-cli-unofficial)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Bun](https://img.shields.io/badge/Bun-%23000000.svg?style=flat&logo=bun&logoColor=white)](https://bun.sh)
@@ -8,9 +10,93 @@
 [![CI/CD](https://img.shields.io/github/actions/workflow/status/JaegerCaiser/trello-cli-unofficial/ci.yml?branch=main&label=CI)](https://github.com/JaegerCaiser/trello-cli-unofficial/actions)
 [![Release](https://img.shields.io/github/actions/workflow/status/JaegerCaiser/trello-cli-unofficial/release.yml?branch=main&label=Release)](https://github.com/JaegerCaiser/trello-cli-unofficial/actions)
 
+---
+
+## 🇺🇸 English
+
+An unofficial Trello CLI with Power-Up authentication, built with Bun and TypeScript. It allows you to manage boards, lists, and cards with modern outputs and multi-profile support.
+
+### Quick Start
+
+```bash
+npm install -g trello-cli-unofficial
+```
+
+```bash
+tcu setup
+tcu interactive
+```
+
+### 🔑 Configuring the Trello Token
+
+On the first run, the CLI will ask for your Trello token (via Power-Up authentication). Follow these steps:
+
+**Step 1 — Access the Power-Ups admin dashboard:**
+Open in your browser: **https://trello.com/power-ups/admin**
+Log in to Trello if necessary.
+
+**Step 2 — Create a new Power-Up:**
+Click on **"New"** and fill in any name (e.g., `My CLI`). The name doesn't matter — it's just to identify the app in your account.
+> If you have created a Power-Up before, simply select it from the list.
+
+**Step 3 — Generate the token manually:**
+Inside your Power-Up's page, you will see a message on the right panel:
+> *"Most developers will need to ask each user to authorize their app. If you are building an app for yourself or doing local testing, you can manually generate a **token**."*
+
+Click on the highlighted word **token** in that message. A new page will open asking for confirmation — click **"Allow"**.
+
+**Step 4 — Copy the token:**
+The page will display a long sequence of characters starting with `ATTA`. Copy the entire string.
+
+**Step 5 — Paste it into the terminal:**
+When the CLI asks `Please enter your Trello token:`, paste the token and press Enter.
+
+> **Tip:** The token must always start with `ATTA`. If the CLI rejects your input, make sure you copied the full token without any extra spaces.
+
+> **Security:** The token is saved locally in `~/.trello-cli-unofficial/config.json`. To revoke access, go to [trello.com/account](https://trello.com/account) → **Power-Ups & Tokens** and revoke the token for this application.
+
+### Features
+
+- 🚀 Interactive mode with a guided menu
+- 📊 Output in JSON, table, and CSV formats
+- 🌍 i18n support (English / pt-BR)
+- 🔐 Power-Up authentication for Trello
+- 👤 Multi-profile support with persistent configuration
+
+### Commands
+
+```bash
+tcu boards
+
+tcu lists
+
+tcu cards
+
+tcu checklists
+
+tcu config
+```
+
+*To see all available parameters and options, run `tcu <command> --help` in your terminal.*
+
+### 📚 Full Documentation
+
+- [./docs/commands.md](./docs/commands.md)
+- [./docs/architecture.md](./docs/architecture.md)
+- [./docs/migration-guide.md](./docs/migration-guide.md)
+- [./docs/troubleshooting.md](./docs/troubleshooting.md)
+
+### Contributing
+
+Want to help improve the project? See our [Contributing Guide](CONTRIBUTING.md).
+
+---
+
+## 🇧🇷 Português
+
 Um CLI não-oficial para Trello com autenticação Power-Up, feito em Bun e TypeScript. Permite gerenciar boards, lists e cards com saídas modernas e suporte a múltiplos perfis.
 
-## Quick Start
+### Quick Start
 
 ```bash
 npm install -g trello-cli-unofficial
@@ -21,43 +107,35 @@ tcu setup
 tcu interactive
 ```
 
-## 🔑 Configurando o Token do Trello
+### 🔑 Configurando o Token do Trello
 
 Na primeira execução o CLI vai pedir seu token do Trello (autenticação via Power-Up). Siga os passos abaixo:
 
 **Passo 1 — Acesse o painel de administração de Power-Ups:**
-
 Abra no navegador: **https://trello.com/power-ups/admin**
-
 Faça login no Trello se necessário.
 
 **Passo 2 — Crie um novo Power-Up:**
-
 Clique em **"New"** e preencha com qualquer nome (ex: `Meu CLI`). O nome não importa — é só para identificar o app na sua conta.
-
 > Se você já criou um Power-Up antes, basta selecioná-lo na lista.
 
 **Passo 3 — Gere o token manualmente:**
-
 Dentro da página do seu Power-Up, você verá no painel à direita a mensagem:
-
 > *"A maioria dos desenvolvedores precisará solicitar a cada usuário que autorize seu aplicativo. Se você deseja criar um aplicativo para si mesmo ou está fazendo testes locais, é possível gerar um **token** manualmente."*
 
 Clique na palavra **token** destacada nessa mensagem. Uma nova página abrirá pedindo confirmação — clique em **"Permitir"**.
 
 **Passo 4 — Copie o token:**
-
 A página exibirá uma longa sequência de caracteres começando com `ATTA`. Copie tudo.
 
 **Passo 5 — Cole no terminal:**
-
 Quando o CLI perguntar `Por favor, insira seu token do Trello:`, cole o token e pressione Enter.
 
 > **Dica:** O token começa obrigatoriamente com `ATTA`. Se o CLI rejeitar sua entrada, verifique se copiou o token completo sem espaços extras.
 
 > **Segurança:** O token fica salvo localmente em `~/.trello-cli-unofficial/config.json`. Para revogar o acesso, acesse [trello.com/account](https://trello.com/account) → **Power-Ups & Tokens** e revogue o token desta aplicação.
 
-## Features
+### Features
 
 - 🚀 Modo interativo com menu guiado
 - 📊 Saída em JSON, table e CSV
@@ -65,7 +143,7 @@ Quando o CLI perguntar `Por favor, insira seu token do Trello:`, cole o token e
 - 🔐 Autenticação Power-Up para Trello
 - 👤 Suporte a múltiplos perfis e configuração persistente
 
-## Commands
+### Commands
 
 ```bash
 tcu boards
@@ -81,13 +159,13 @@ tcu config
 
 *Para ver todos os parâmetros e opções, execute `tcu <comando> --help` no seu terminal.*
 
-## 📚 Documentação Completa
+### 📚 Documentação Completa
 
 - [./docs/commands.md](./docs/commands.md)
 - [./docs/architecture.md](./docs/architecture.md)
 - [./docs/migration-guide.md](./docs/migration-guide.md)
 - [./docs/troubleshooting.md](./docs/troubleshooting.md)
 
-## Contribuição
+### Contribuição
 
-Quer ajudar a melhorar o projeto? Veja nosso [Guia de Contribuição](CONTRIBUTING.md).
+Quer ajudar a melhorar o projeto? Veja nosso [Guia de Contribuição](CONTRIBUTING.md).

package/dist/main.js

@@ -2850,6 +2850,7 @@ var require_en = __commonJS((exports, module) => {
       enterToken: "Please enter your Trello token:",
       tokenInvalid: "❌ Invalid token! Token must start with 'ATTA' and be at least 11 characters long.",
       tokenSaved: "✅ Token saved successfully!",
+      setupCancelled: "⚠️ Setup cancelled by the user.",
       authenticated: "✅ You are already authenticated!"
     },
     menu: {
@@ -2955,7 +2956,8 @@ var require_en = __commonJS((exports, module) => {
       validation: {
         requiredName: "Name is required",
         requiredCardName: "Card name is required",
-        cardNameCannotBeEmpty: "Card name cannot be empty"
+        cardNameCannotBeEmpty: "Card name cannot be empty",
+        requiredSearchQuery: "Search query cannot be empty"
       },
       actions: {
         view: "👁️  View Details",
@@ -2977,6 +2979,11 @@ var require_en = __commonJS((exports, module) => {
         checklistProgress: " [{{done}}/{{total}}]",
         checklistItemDone: "      ☑  {{name}}",
         checklistItemPending: "      ☐  {{name}}"
+      },
+      search: {
+        results: '🔍 Results for "{{query}}" ({{count}} found):',
+        empty: '🔍 No cards found for "{{query}}".',
+        pagination: "📄 Page {{page}} (limit: {{limit}})"
       }
     },
     checklist: {
@@ -3144,6 +3151,14 @@ var require_en = __commonJS((exports, module) => {
         },
         delete: {
           description: "Delete a card"
+        },
+        search: {
+          description: "Search cards by text",
+          boardIdOption: "Filter by board ID",
+          listIdOption: "Filter by list ID",
+          labelsOption: "Filter by labels (comma-separated)",
+          limitOption: "Maximum number of results",
+          pageOption: "Page number (starts at 0)"
         }
       },
       checklists: {
@@ -3218,6 +3233,7 @@ var require_pt_BR = __commonJS((exports, module) => {
       enterToken: "Por favor, insira seu token do Trello:",
       tokenInvalid: "❌ Token inválido! O token deve começar com 'ATTA' e ter pelo menos 11 caracteres.",
       tokenSaved: "✅ Token salvo com sucesso!",
+      setupCancelled: "⚠️ Configuração cancelada pelo usuário.",
       authenticated: "✅ Você já está autenticado!"
     },
     menu: {
@@ -3323,7 +3339,8 @@ var require_pt_BR = __commonJS((exports, module) => {
       validation: {
         requiredName: "Nome é obrigatório",
         requiredCardName: "Nome do cartão é obrigatório",
-        cardNameCannotBeEmpty: "Nome do cartão não pode estar vazio"
+        cardNameCannotBeEmpty: "Nome do cartão não pode estar vazio",
+        requiredSearchQuery: "A consulta de busca não pode estar vazia"
       },
       actions: {
         view: "👁️  Ver Detalhes",
@@ -3345,6 +3362,11 @@ var require_pt_BR = __commonJS((exports, module) => {
         checklistProgress: " [{{done}}/{{total}}]",
         checklistItemDone: "      ☑  {{name}}",
         checklistItemPending: "      ☐  {{name}}"
+      },
+      search: {
+        results: '🔍 Resultados para "{{query}}" ({{count}} encontrado(s)):',
+        empty: '🔍 Nenhum card encontrado para "{{query}}".',
+        pagination: "📄 Página {{page}} (limite: {{limit}})"
       }
     },
     checklist: {
@@ -3512,6 +3534,14 @@ var require_pt_BR = __commonJS((exports, module) => {
         },
         delete: {
           description: "Deleta um card"
+        },
+        search: {
+          description: "Buscar cards por texto",
+          boardIdOption: "Filtrar por ID de board",
+          listIdOption: "Filtrar por ID de lista",
+          labelsOption: "Filtrar por labels (separadas por vírgula)",
+          limitOption: "Número máximo de resultados",
+          pageOption: "Número da página (começa em 0)"
         }
       },
       checklists: {
@@ -3954,6 +3984,37 @@ var init_RenameChecklistUseCase = __esm(() => {
   init_i18n();
 });
 
+// src/application/use-cases/SearchCardsUseCase.ts
+class SearchCardsUseCase {
+  trelloRepository;
+  constructor(trelloRepository) {
+    this.trelloRepository = trelloRepository;
+  }
+  async execute(query, filters) {
+    if (!query || query.trim().length === 0) {
+      throw new Error(t3("card.validation.requiredSearchQuery"));
+    }
+    let fullQuery = query.trim();
+    if (filters?.labels) {
+      const labelTerms = filters.labels.split(",").map((l) => `label:"${l.trim()}"`).join(" ");
+      fullQuery = `${fullQuery} ${labelTerms}`;
+    }
+    const options = {
+      boardId: filters?.boardId,
+      limit: filters?.limit,
+      page: filters?.page
+    };
+    const results = await this.trelloRepository.searchCards(fullQuery, options);
+    if (filters?.listId) {
+      return results.filter((card) => card.idList === filters.listId);
+    }
+    return results;
+  }
+}
+var init_SearchCardsUseCase = __esm(() => {
+  init_i18n();
+});
+
 // src/application/use-cases/UpdateCardUseCase.ts
 class UpdateCardUseCase {
   trelloRepository;
@@ -3993,6 +4054,7 @@ var init_use_cases = __esm(() => {
   init_GetBoardDetailsUseCase();
   init_RenameChecklistItemUseCase();
   init_RenameChecklistUseCase();
+  init_SearchCardsUseCase();
   init_UpdateCardUseCase();
 });
 
@@ -25646,16 +25708,24 @@ class AuthController {
     console.log(t3("auth.tokenHintUrl"));
     console.log(t3("auth.tokenHintStep2"));
     console.log(t3("auth.tokenHintStep3"));
-    const { token } = await dist_default14.prompt([
-      {
-        type: "input",
-        name: "token",
-        message: t3("auth.enterToken"),
-        validate: (input) => input.startsWith("ATTA") || t3("auth.tokenInvalid")
+    try {
+      const { token } = await dist_default14.prompt([
+        {
+          type: "input",
+          name: "token",
+          message: t3("auth.enterToken"),
+          validate: (input) => input.startsWith("ATTA") || t3("auth.tokenInvalid")
+        }
+      ]);
+      const result = await this.authenticateUseCase.execute(token);
+      console.log(result.success ? t3("auth.tokenSaved") : result.message);
+    } catch (error) {
+      if (error instanceof Error && error.name === "ExitPromptError") {
+        console.log(t3("auth.setupCancelled"));
+        process.exit(0);
       }
-    ]);
-    const result = await this.authenticateUseCase.execute(token);
-    console.log(result.success ? t3("auth.tokenSaved") : result.message);
+      throw error;
+    }
   }
   async getConfig() {
     return await this.authenticateUseCase.getConfig();
@@ -25875,6 +25945,7 @@ class CardController {
   deleteCardUseCase;
   moveCardUseCase;
   getCardUseCase;
+  searchCardsUseCase;
   constructor(trelloRepository, boardController, outputFormatter) {
     this.trelloRepository = trelloRepository;
     this.boardController = boardController;
@@ -25884,6 +25955,7 @@ class CardController {
     this.deleteCardUseCase = new DeleteCardUseCase(trelloRepository);
     this.moveCardUseCase = new MoveCardUseCase(trelloRepository);
     this.getCardUseCase = new GetCardUseCase(trelloRepository);
+    this.searchCardsUseCase = new SearchCardsUseCase(trelloRepository);
   }
   async createCardInteractive() {
     const boards = await this.boardController.getBoards();
@@ -26096,28 +26168,7 @@ class CardController {
     throw new Error(t3("card.notFound", { cardId }));
   }
   async deleteCard(cardId) {
-    const boards = await this.trelloRepository.getBoards();
-    let card;
-    for (const board of boards) {
-      const lists = await this.trelloRepository.getLists(board.id);
-      for (const list of lists) {
-        try {
-          const cards = await this.trelloRepository.getCards(list.id);
-          card = cards.find((c) => c.id === cardId);
-          if (card) {
-            break;
-          }
-        } catch {
-          continue;
-        }
-      }
-      if (card) {
-        break;
-      }
-    }
-    if (!card) {
-      throw new Error(t3("card.notFound", { cardId }));
-    }
+    const card = await this.trelloRepository.getCard(cardId);
     await this.deleteCardUseCase.execute(cardId);
     console.log(t3("card.deleted"));
     console.log(t3("card.cardName", { name: card.name }));
@@ -26230,44 +26281,32 @@ class CardController {
     }
   }
   async moveCardToList(cardId, targetListId) {
-    const boards = await this.trelloRepository.getBoards();
-    let card;
-    for (const board of boards) {
-      const lists = await this.trelloRepository.getLists(board.id);
-      for (const list of lists) {
-        try {
-          const cards = await this.trelloRepository.getCards(list.id);
-          card = cards.find((c) => c.id === cardId);
-          if (card) {
-            break;
-          }
-        } catch {
-          continue;
-        }
-      }
-      if (card) {
-        break;
-      }
-    }
-    if (!card) {
-      throw new Error(t3("card.notFound", { cardId }));
-    }
-    let targetList;
-    for (const board of boards) {
-      const lists = await this.trelloRepository.getLists(board.id);
-      targetList = lists.find((l) => l.id === targetListId);
-      if (targetList) {
-        break;
-      }
-    }
-    if (!targetList) {
-      throw new Error(t3("list.notFoundById", { listId: targetListId }));
-    }
+    const [card, targetList] = await Promise.all([
+      this.trelloRepository.getCard(cardId),
+      this.trelloRepository.getList(targetListId)
+    ]);
     await this.moveCardUseCase.execute(cardId, targetListId);
     console.log(t3("card.moved"));
     console.log(t3("card.cardName", { name: card.name }));
     console.log(t3("card.movedTo", { listName: targetList.name }));
   }
+  async searchCards(query, filters) {
+    const cards = await this.searchCardsUseCase.execute(query, filters);
+    if (cards.length === 0) {
+      console.log(t3("card.search.empty", { query }));
+      return;
+    }
+    console.log(t3("card.search.results", { query, count: cards.length }));
+    if (filters?.page !== undefined || filters?.limit !== undefined) {
+      const page = (filters.page ?? 0) + 1;
+      const limit = filters.limit ?? 50;
+      console.log(t3("card.search.pagination", { page, limit }));
+    }
+    this.outputFormatter.output(cards, {
+      fields: ["name", "id", "url"],
+      headers: ["Name", "ID", "URL"]
+    });
+  }
 }
 var init_CardController = __esm(() => {
   init_use_cases();
@@ -28725,6 +28764,10 @@ ${errorText}`);
     const data = await this.requestLists(`/boards/${boardId}/lists`);
     return data.map((list) => ListEntity.fromApiResponse(list));
   }
+  async getList(listId) {
+    const data = await this.request(`/lists/${listId}`);
+    return ListEntity.fromApiResponse(data);
+  }
   async createList(boardId, name) {
     const body = new URLSearchParams({
       idBoard: boardId,
@@ -28907,6 +28950,16 @@ ${errorText}`);
     });
     return ChecklistItemEntity.fromApiResponse(data);
   }
+  async searchCards(query, options) {
+    const limit = options?.limit ?? 50;
+    const page = options?.page ?? 0;
+    let endpoint = `/search?query=${encodeURIComponent(query)}&modelTypes=cards&cards_limit=${limit}&cards_page=${page}&card_fields=id,name,desc,idList,url,pos`;
+    if (options?.boardId) {
+      endpoint += `&idBoards=${encodeURIComponent(options.boardId)}`;
+    }
+    const data = await this.request(endpoint);
+    return data.cards.map((card) => CardEntity.fromApiResponse(card));
+  }
 }
 var init_TrelloApiRepository = __esm(() => {
   init_entities();
@@ -31546,6 +31599,21 @@ class CommandController {
         await this.cardController.showCard(cardId);
       }, "cards show");
     });
+    cardsCmd.command("search <query>").description(t3("commands.cards.search.description")).option("-f, --format <format>", t3("commands.formatOption"), "table").option("--board-id <boardId>", t3("commands.cards.search.boardIdOption")).option("--list-id <listId>", t3("commands.cards.search.listIdOption")).option("--labels <labels>", t3("commands.cards.search.labelsOption")).option("--limit <limit>", t3("commands.cards.search.limitOption")).option("--page <page>", t3("commands.cards.search.pageOption")).action(async (query, options) => {
+      await ErrorHandler.withErrorHandling(async () => {
+        await this.initializeTrelloControllers();
+        if (options.format) {
+          this.outputFormatter.setFormat(options.format);
+        }
+        await this.cardController.searchCards(query, {
+          boardId: options.boardId,
+          listId: options.listId,
+          labels: options.labels,
+          limit: options.limit !== undefined ? Number.parseInt(options.limit, 10) : undefined,
+          page: options.page !== undefined ? Number.parseInt(options.page, 10) : undefined
+        });
+      }, "cards search");
+    });
     cardsCmd.command("legacy <boardName> <listName>").description(t3("commands.deprecated.cardsAliasDescription")).action(async (boardName, listName) => {
       console.warn(t3("commands.deprecated.cardsAliasWarning"));
       await ErrorHandler.withErrorHandling(async () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "trello-cli-unofficial",
   "type": "module",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": false,
   "packageManager": "bun@1.3.11",
   "description": "Unofficial Trello CLI using Power-Up authentication, built with Bun for maximum performance",

package/src/application/use-cases/SearchCardsUseCase.ts

@@ -0,0 +1,41 @@
+import type { CardEntity } from '@domain/entities';
+import type { SearchCardsOptions, TrelloRepository } from '@domain/repositories';
+import { t } from '@/i18n';
+
+export interface SearchCardsFilters {
+  boardId?: string;
+  listId?: string;
+  labels?: string;
+  limit?: number;
+  page?: number;
+}
+
+export class SearchCardsUseCase {
+  constructor(private trelloRepository: TrelloRepository) {}
+
+  async execute(query: string, filters?: SearchCardsFilters): Promise<CardEntity[]> {
+    if (!query || query.trim().length === 0) {
+      throw new Error(t('card.validation.requiredSearchQuery'));
+    }
+
+    let fullQuery = query.trim();
+    if (filters?.labels) {
+      const labelTerms = filters.labels.split(',').map(l => `label:"${l.trim()}"`).join(' ');
+      fullQuery = `${fullQuery} ${labelTerms}`;
+    }
+
+    const options: SearchCardsOptions = {
+      boardId: filters?.boardId,
+      limit: filters?.limit,
+      page: filters?.page,
+    };
+
+    const results = await this.trelloRepository.searchCards(fullQuery, options);
+
+    if (filters?.listId) {
+      return results.filter(card => card.idList === filters.listId);
+    }
+
+    return results;
+  }
+}

package/src/application/use-cases/index.ts

@@ -15,5 +15,6 @@ export * from './GetListsUseCase';
 export * from './MoveCardUseCase';
 export * from './RenameChecklistItemUseCase';
 export * from './RenameChecklistUseCase';
+export * from './SearchCardsUseCase';
 export * from './UpdateCardUseCase';
 export * from './UpdateChecklistItemStateUseCase';

package/src/domain/repositories/TrelloRepository.ts

@@ -21,12 +21,19 @@ export interface BoardLabel {
   color: string;
 }
 
+export interface SearchCardsOptions {
+  boardId?: string;
+  limit?: number;
+  page?: number;
+}
+
 export interface TrelloRepository {
   getBoards: () => Promise<BoardEntity[]>;
   createBoard: (name: string, description?: string) => Promise<BoardEntity>;
   getBoardMembers: (boardId: string) => Promise<BoardMember[]>;
   getBoardLabels: (boardId: string) => Promise<BoardLabel[]>;
   getLists: (boardId: string) => Promise<ListEntity[]>;
+  getList: (listId: string) => Promise<ListEntity>;
   createList: (boardId: string, name: string) => Promise<ListEntity>;
   deleteList: (listId: string) => Promise<void>;
   moveList: (listId: string, position: number) => Promise<ListEntity>;
@@ -43,4 +50,5 @@ export interface TrelloRepository {
   deleteChecklistItem: (checklistId: string, itemId: string) => Promise<void>;
   renameChecklistItem: (cardId: string, itemId: string, name: string) => Promise<ChecklistItemEntity>;
   updateChecklistItemState: (cardId: string, itemId: string, state: 'complete' | 'incomplete') => Promise<ChecklistItemEntity>;
+  searchCards: (query: string, options?: SearchCardsOptions) => Promise<CardEntity[]>;
 }

package/src/i18n/locales/en.json

@@ -20,6 +20,7 @@
     "enterToken": "Please enter your Trello token:",
     "tokenInvalid": "❌ Invalid token! Token must start with 'ATTA' and be at least 11 characters long.",
     "tokenSaved": "✅ Token saved successfully!",
+    "setupCancelled": "⚠️ Setup cancelled by the user.",
     "authenticated": "✅ You are already authenticated!"
   },
   "menu": {
@@ -125,7 +126,8 @@
     "validation": {
       "requiredName": "Name is required",
       "requiredCardName": "Card name is required",
-      "cardNameCannotBeEmpty": "Card name cannot be empty"
+      "cardNameCannotBeEmpty": "Card name cannot be empty",
+      "requiredSearchQuery": "Search query cannot be empty"
     },
     "actions": {
       "view": "👁️  View Details",
@@ -147,6 +149,11 @@
       "checklistProgress": " [{{done}}/{{total}}]",
       "checklistItemDone": "      ☑  {{name}}",
       "checklistItemPending": "      ☐  {{name}}"
+    },
+    "search": {
+      "results": "🔍 Results for \"{{query}}\" ({{count}} found):",
+      "empty": "🔍 No cards found for \"{{query}}\".",
+      "pagination": "📄 Page {{page}} (limit: {{limit}})"
     }
   },
   "checklist": {
@@ -314,6 +321,14 @@
       },
       "delete": {
         "description": "Delete a card"
+      },
+      "search": {
+        "description": "Search cards by text",
+        "boardIdOption": "Filter by board ID",
+        "listIdOption": "Filter by list ID",
+        "labelsOption": "Filter by labels (comma-separated)",
+        "limitOption": "Maximum number of results",
+        "pageOption": "Page number (starts at 0)"
       }
     },
     "checklists": {

package/src/i18n/locales/pt-BR.json

@@ -20,6 +20,7 @@
     "enterToken": "Por favor, insira seu token do Trello:",
     "tokenInvalid": "❌ Token inválido! O token deve começar com 'ATTA' e ter pelo menos 11 caracteres.",
     "tokenSaved": "✅ Token salvo com sucesso!",
+    "setupCancelled": "⚠️ Configuração cancelada pelo usuário.",
     "authenticated": "✅ Você já está autenticado!"
   },
   "menu": {
@@ -125,7 +126,8 @@
     "validation": {
       "requiredName": "Nome é obrigatório",
       "requiredCardName": "Nome do cartão é obrigatório",
-      "cardNameCannotBeEmpty": "Nome do cartão não pode estar vazio"
+      "cardNameCannotBeEmpty": "Nome do cartão não pode estar vazio",
+      "requiredSearchQuery": "A consulta de busca não pode estar vazia"
     },
     "actions": {
       "view": "👁️  Ver Detalhes",
@@ -147,6 +149,11 @@
       "checklistProgress": " [{{done}}/{{total}}]",
       "checklistItemDone": "      ☑  {{name}}",
       "checklistItemPending": "      ☐  {{name}}"
+    },
+    "search": {
+      "results": "🔍 Resultados para \"{{query}}\" ({{count}} encontrado(s)):",
+      "empty": "🔍 Nenhum card encontrado para \"{{query}}\".",
+      "pagination": "📄 Página {{page}} (limite: {{limit}})"
     }
   },
   "checklist": {
@@ -314,6 +321,14 @@
       },
       "delete": {
         "description": "Deleta um card"
+      },
+      "search": {
+        "description": "Buscar cards por texto",
+        "boardIdOption": "Filtrar por ID de board",
+        "listIdOption": "Filtrar por ID de lista",
+        "labelsOption": "Filtrar por labels (separadas por vírgula)",
+        "limitOption": "Número máximo de resultados",
+        "pageOption": "Número da página (começa em 0)"
       }
     },
     "checklists": {

package/src/infrastructure/repositories/TrelloApiRepository.ts

@@ -1,5 +1,5 @@
 import type { CreateCardData, UpdateCardData } from '@domain/entities';
-import type { TrelloRepository } from '@domain/repositories';
+import type { SearchCardsOptions, TrelloRepository } from '@domain/repositories';
 import { BoardEntity, CardEntity, ChecklistEntity, ChecklistItemEntity, ListEntity } from '@domain/entities';
 import { t } from '@/i18n';
 
@@ -171,6 +171,11 @@ export class TrelloApiRepository implements TrelloRepository {
     );
   }
 
+  async getList(listId: string): Promise<ListEntity> {
+    const data = await this.request(`/lists/${listId}`);
+    return ListEntity.fromApiResponse(data as TrelloListResponse);
+  }
+
   async createList(boardId: string, name: string): Promise<ListEntity> {
     const body = new URLSearchParams({
       idBoard: boardId,
@@ -400,4 +405,15 @@ export class TrelloApiRepository implements TrelloRepository {
 
     return ChecklistItemEntity.fromApiResponse(data as TrelloChecklistItemResponse);
   }
+
+  async searchCards(query: string, options?: SearchCardsOptions): Promise<CardEntity[]> {
+    const limit = options?.limit ?? 50;
+    const page = options?.page ?? 0;
+    let endpoint = `/search?query=${encodeURIComponent(query)}&modelTypes=cards&cards_limit=${limit}&cards_page=${page}&card_fields=id,name,desc,idList,url,pos`;
+    if (options?.boardId) {
+      endpoint += `&idBoards=${encodeURIComponent(options.boardId)}`;
+    }
+    const data = await this.request(endpoint) as { cards: TrelloCardResponse[] };
+    return data.cards.map(card => CardEntity.fromApiResponse(card));
+  }
 }

package/src/presentation/cli/AuthController.ts

@@ -26,17 +26,26 @@ export class AuthController {
     console.log(t('auth.tokenHintStep2'));
     console.log(t('auth.tokenHintStep3'));
 
-    const { token } = await inquirer.prompt([
-      {
-        type: 'input',
-        name: 'token',
-        message: t('auth.enterToken'),
-        validate: input => input.startsWith('ATTA') || t('auth.tokenInvalid'),
-      },
-    ]);
-
-    const result = await this.authenticateUseCase.execute(token);
-    console.log(result.success ? t('auth.tokenSaved') : result.message);
+    try {
+      const { token } = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'token',
+          message: t('auth.enterToken'),
+          validate: input => input.startsWith('ATTA') || t('auth.tokenInvalid'),
+        },
+      ]);
+
+      const result = await this.authenticateUseCase.execute(token);
+      console.log(result.success ? t('auth.tokenSaved') : result.message);
+    } catch (error: unknown) {
+      if (error instanceof Error && error.name === 'ExitPromptError') {
+        console.log(t('auth.setupCancelled'));
+        process.exit(0);
+      }
+
+      throw error;
+    }
   }
 
   async getConfig(): Promise<ConfigEntity> {

package/src/presentation/cli/CardController.ts

@@ -1,3 +1,4 @@
+import type { SearchCardsFilters } from '@application/use-cases';
 import type { BoardEntity, CardEntity, ListEntity } from '@domain/entities';
 import type { TrelloRepository } from '@domain/repositories';
 import type { BoardController } from './BoardController';
@@ -8,6 +9,7 @@ import {
   DeleteCardUseCase,
   GetCardUseCase,
   MoveCardUseCase,
+  SearchCardsUseCase,
   UpdateCardUseCase,
 } from '@application/use-cases';
 
@@ -21,6 +23,7 @@ export class CardController {
   private deleteCardUseCase: DeleteCardUseCase;
   private moveCardUseCase: MoveCardUseCase;
   private getCardUseCase: GetCardUseCase;
+  private searchCardsUseCase: SearchCardsUseCase;
 
   constructor(
     private trelloRepository: TrelloRepository,
@@ -32,6 +35,7 @@ export class CardController {
     this.deleteCardUseCase = new DeleteCardUseCase(trelloRepository);
     this.moveCardUseCase = new MoveCardUseCase(trelloRepository);
     this.getCardUseCase = new GetCardUseCase(trelloRepository);
+    this.searchCardsUseCase = new SearchCardsUseCase(trelloRepository);
   }
 
   async createCardInteractive(): Promise<void> {
@@ -309,34 +313,7 @@ export class CardController {
   }
 
   async deleteCard(cardId: string): Promise<void> {
-    // Primeiro precisamos encontrar o cartão para mostrar informações
-    const boards = await this.trelloRepository.getBoards();
-    let card: CardEntity | undefined;
-
-    for (const board of boards) {
-      const lists = await this.trelloRepository.getLists(board.id);
-
-      for (const list of lists) {
-        try {
-          const cards = await this.trelloRepository.getCards(list.id);
-          card = cards.find((c: CardEntity) => c.id === cardId);
-
-          if (card) {
-            break;
-          }
-        } catch {
-          continue;
-        }
-      }
-      if (card) {
-        break;
-      }
-    }
-
-    if (!card) {
-      throw new Error(t('card.notFound', { cardId }));
-    }
-
+    const card = await this.trelloRepository.getCard(cardId);
     await this.deleteCardUseCase.execute(cardId);
     console.log(t('card.deleted'));
     console.log(t('card.cardName', { name: card.name }));
@@ -494,51 +471,32 @@ export class CardController {
   }
 
   async moveCardToList(cardId: string, targetListId: string): Promise<void> {
-    // Primeiro precisamos encontrar o cartão para mostrar informações
-    const boards = await this.trelloRepository.getBoards();
-    let card: CardEntity | undefined;
-
-    for (const board of boards) {
-      const lists = await this.trelloRepository.getLists(board.id);
-
-      for (const list of lists) {
-        try {
-          const cards = await this.trelloRepository.getCards(list.id);
-          card = cards.find((c: CardEntity) => c.id === cardId);
-
-          if (card) {
-            break;
-          }
-        } catch {
-          continue;
-        }
-      }
-      if (card) {
-        break;
-      }
-    }
-
-    if (!card) {
-      throw new Error(t('card.notFound', { cardId }));
-    }
-
-    // Verificar se a lista de destino existe procurando em todos os boards
-    let targetList: ListEntity | undefined;
-    for (const board of boards) {
-      const lists = await this.trelloRepository.getLists(board.id);
-      targetList = lists.find((l: ListEntity) => l.id === targetListId);
-      if (targetList) {
-        break;
-      }
-    }
-
-    if (!targetList) {
-      throw new Error(t('list.notFoundById', { listId: targetListId }));
-    }
+    const [card, targetList] = await Promise.all([
+      this.trelloRepository.getCard(cardId),
+      this.trelloRepository.getList(targetListId),
+    ]);
 
     await this.moveCardUseCase.execute(cardId, targetListId);
     console.log(t('card.moved'));
     console.log(t('card.cardName', { name: card.name }));
     console.log(t('card.movedTo', { listName: targetList.name }));
   }
+
+  async searchCards(query: string, filters?: SearchCardsFilters): Promise<void> {
+    const cards = await this.searchCardsUseCase.execute(query, filters);
+    if (cards.length === 0) {
+      console.log(t('card.search.empty', { query }));
+      return;
+    }
+    console.log(t('card.search.results', { query, count: cards.length }));
+    if (filters?.page !== undefined || filters?.limit !== undefined) {
+      const page = (filters.page ?? 0) + 1;
+      const limit = filters.limit ?? 50;
+      console.log(t('card.search.pagination', { page, limit }));
+    }
+    this.outputFormatter.output(cards, {
+      fields: ['name', 'id', 'url'],
+      headers: ['Name', 'ID', 'URL'],
+    });
+  }
 }

package/src/presentation/cli/CommandController.ts

@@ -387,6 +387,31 @@ export class CommandController {
         }, 'cards show');
       });
 
+    cardsCmd
+      .command('search <query>')
+      .description(t('commands.cards.search.description'))
+      .option('-f, --format <format>', t('commands.formatOption'), 'table')
+      .option('--board-id <boardId>', t('commands.cards.search.boardIdOption'))
+      .option('--list-id <listId>', t('commands.cards.search.listIdOption'))
+      .option('--labels <labels>', t('commands.cards.search.labelsOption'))
+      .option('--limit <limit>', t('commands.cards.search.limitOption'))
+      .option('--page <page>', t('commands.cards.search.pageOption'))
+      .action(async (query: string, options: { format?: string; boardId?: string; listId?: string; labels?: string; limit?: string; page?: string }) => {
+        await ErrorHandler.withErrorHandling(async () => {
+          await this.initializeTrelloControllers();
+          if (options.format) {
+            this.outputFormatter.setFormat(options.format as OutputFormat);
+          }
+          await this.cardController.searchCards(query, {
+            boardId: options.boardId,
+            listId: options.listId,
+            labels: options.labels,
+            limit: options.limit !== undefined ? Number.parseInt(options.limit, 10) : undefined,
+            page: options.page !== undefined ? Number.parseInt(options.page, 10) : undefined,
+          });
+        }, 'cards search');
+      });
+
     // Backward compatibility subcommand for legacy behavior
     cardsCmd
       .command('legacy <boardName> <listName>')