Trello Control

trello-control - Claude Skill Reference

A command-line tool for reading and writing Trello cards. Invoke it as a subprocess; all output is a single JSON object on stdout.

Prerequisites

Two environment variables must be set before any command runs:

Output Contract

Every invocation returns exactly one JSON object. Always check success before using data.

{ "success": true,  "data": <result> }
{ "success": false, "error": "<message>" }

Exit code is 0 on success, 1 on error.

Card Object Shape

All card-returning commands produce this shape:

{
  "id":          "abc123",
  "name":        "Card title",
  "description": "Markdown body or null",
  "idList":      "list-id",
  "idBoard":     "board-id",
  "shortUrl":    "https://trello.com/c/...",
  "due":         "2025-06-01T00:00:00+00:00",
  "closed":      false,
  "labels": [
    { "id": "label-id", "name": "Bug", "color": "red" }
  ],
  "comments": null
}

description, shortUrl, due, and color may be null.

comments is null for all commands except cards get, which populates it with the full comment history:

"comments": [
  {
    "id":         "action-id",
    "text":       "Comment body",
    "authorName": "Alice Smith",
    "date":       "2025-05-01T10:30:00+00:00"
  }
]

authorName may be null. Comments are ordered oldest-first as returned by Trello.

Commands

Discovery (start here when you don't have IDs)

Get all lists on a board

trello-control boards lists --id <boardId>

data: [{ "id": "...", "name": "..." }, ...]

Get all labels on a board

trello-control boards labels --id <boardId>

data: [{ "id": "...", "name": "...", "color": "..." }, ...]

Cards

Search cards

trello-control cards search --query <text> [--board-id <boardId>]

• Partial-match search across all boards the token can access.
• --board-id narrows results client-side (does not restrict the API call).

data: array of card objects (max 50).

Get a card

trello-control cards get --id <cardId>

data: single card object with comments populated (full history, oldest-first).

Create a card

trello-control cards create --list-id <listId> --name <text> [--description <text>] [--label-ids <id,id,...>]

• --label-ids is a comma-separated list of label IDs from boards labels.

data: the created card object.

Update a card's name or description

trello-control cards update --id <cardId> [--name <text>] [--description <text>]

• At least one of --name or --description is required.
• Pass an empty string "" to clear the description.

data: the updated card object.

Add a comment

trello-control cards comment --id <cardId> --text <text>

Comments cannot be edited after creation. Supports Markdown.

data: the card object (after comment is added).

Add or remove labels

trello-control cards label --id <cardId> [--add <id,id,...>] [--remove <id,id,...>]

• At least one of --add or --remove is required.
• Use label IDs from boards labels, not label names.
• Both flags can be used in a single call.

data: the updated card object.

Move a card to a different list

trello-control cards move --id <cardId> --list-id <listId>

Use boards lists to find valid list IDs. Moving to a list on a different board is not supported by this command.

data: the updated card object.

Common Workflows

Create a card with a label

# 1. Find the target list and label IDs
trello-control boards lists  --id <boardId>
trello-control boards labels --id <boardId>

# 2. Create the card
trello-control cards create --list-id <listId> --name "Fix login bug" --label-ids <bugLabelId>

Move a card from Backlog → In Progress

# 1. Find the "In Progress" list ID
trello-control boards lists --id <boardId>

# 2. Move the card
trello-control cards move --id <cardId> --list-id <inProgressListId>

Update a card's description and leave a comment

trello-control cards update  --id <cardId> --description "Updated spec: ..."
trello-control cards comment --id <cardId> --text "Description updated with latest requirements."

Search and inspect a card

# Search (returns array)
trello-control cards search --query "login bug"

# Fetch full detail by ID from the search results
trello-control cards get --id <idFromSearchResults>

Error Examples

{ "success": false, "error": "Missing TRELLO_API_KEY environment variable" }
{ "success": false, "error": "Specify at least one field to update (--name or --description)." }
{ "success": false, "error": "Specify at least --add or --remove." }
{ "success": false, "error": "Invalid value. The card was not found." }

ID Reference

Board IDs — two accepted formats

List IDs

Always 24-character hex strings. Returned by boards lists.

Card IDs - two accepted formats

Both formats are accepted by every command that takes --id:

Prefer the short link when working from a URL a user has pasted. Prefer the full hex ID when chaining commands (e.g. use the id field from a cards search result as input to cards get).

Use boards lists and boards labels at the start of a session to build a local map of name → ID for the board(s) you are working with.