# Trello Control

> Command Line Tool for retrieving and updating trello cards using the Trello API.

- Skill: `waf/trello-control` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add waf/trello-control`
- Raw SKILL.md: https://api.skillmd.com/api/skills/waf/trello-control/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: waf (https://skillmd.com/u/waf)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/waf/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:

| Variable | Value |
|---|---|
| `TRELLO_API_KEY` | Trello Power-Up API key |
| `TRELLO_TOKEN` | Trello user token |

## Output Contract

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

```json
{ "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:

```json
{
  "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:

```json
"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

```json
{ "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

| Format | Example | Where to find it |
|---|---|---|
| Full hex ID | `6062dfe3cf949c84a4e791ae` | Returned as `idBoard` in card responses |
| Short link | `8KmgOdPu` | Segment after `/b/` in the board URL: `trello.com/b/8KmgOdPu/board-title` |

### 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`:

| Format | Example | Where to find it |
|---|---|---|
| Full hex ID | `60631de10025813c5ff41640` | Returned as `id` in all card responses |
| Short link | `yc8fqQZK` | Segment after `/c/` in the card URL: `trello.com/c/yc8fqQZK/card-title` |

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.