---
name: trelly
description: >-
  Operate the trelly Trello CLI (npm trelly; bin trelly): auth setup/login,
  human vs --json output, boards/lists/cards, search, attachments, GitHub PR/commit
  links on cards, trelly ui, trelly api. Use when the user asks to run trelly
  commands, list or show Trello cards/todos, link a GitHub PR or commit to a card, or
  automate Trello with trelly.
---

# trelly

Fast Trello CLI (`npm install -g trelly`). **Human Trello-styled output by default**;
**`--json` for scripts**. Command: **`trelly`**.

## Routing: prefer MCP in agent hosts

When running inside Cursor, Codex, Claude, or another MCP-capable agent host, first
check whether `trello_*` MCP tools are available. If they are, use those tools for
normal Trello work instead of spawning the `trelly` CLI. This includes search,
boards, lists, cards, comments, attachments, and other REST operations.

Use the CLI only when the user explicitly asks for terminal commands or shell
automation, MCP is unavailable, or the task requires the interactive `trelly ui`.
If MCP is available but a tool call fails, report the failure before falling back
to the CLI.

> **Showing cards to a user?** Read [trelly-card-display.md](trelly-card-display.md).
> Pi has no MCP — use **human CLI** (`trelly lists cards LIST_ID` without `--json`)
> or format per that contract. Never reply with titles-only.

## Prerequisites

```bash
npm install -g trelly
trelly auth setup    # once: API key from https://trello.com/power-ups/admin
trelly auth login    # browser Allow → saves token
```

From source: clone [brandonkramer/trelly](https://github.com/brandonkramer/trelly),
`bun install`, then `./bin/trelly auth setup`.

Auth notes (common confusion):

- Power-Up admin is **developer registration**, not installing a Power-Up on a board.
- Pick any workspace you **admin** (personal is fine) — does not limit which boards you can use.
- After login the CLI is **you** on Trello (member permissions, not board admin).

Credentials: `~/.config/trelly/config.json` (migrates from `~/.config/trello-cli/`; never read/log/commit).

## Output contract

| Goal | Flags |
|------|--------|
| Human (default) | *(none)* |
| JSON envelope | `--json` → `{ ok, profile, data }` or `{ ok: false, error, ... }` |
| Pretty JSON | `--json --pretty` |
| Fresh network read | `--fresh` |

- **Scripts:** always `--json` if parsing stdout.
- **Token cost:** raw `--json` returns full Trello objects (a board list ≈ 10k tokens) — trim with `jq` (e.g. `| jq '.data[] | {id,name}'`) or request fewer fields (`--fields`, `--query "fields=id,name"`).
- **Showing cards to a human?** See [trelly-card-display.md](trelly-card-display.md).
  Prefer human CLI (`trelly lists cards LIST_ID`). With `--json`, slim first, then
  apply **Manual format** in that doc:
  `jq '.data[] | {name, shortUrl, labels: [.labels[] | {name, color}], badges: {comments: .badges.comments, attachments: .badges.attachments, checkItems: .badges.checkItems, checkItemsChecked: .badges.checkItemsChecked}, due, dueComplete}'`.
- **`--pretty` alone** does not emit JSON; it only indents `--json` output.
- Errors: red `✗` in human mode; exit code `1`.

## Common commands

```bash
trelly boards list
trelly --json boards list | jq '.data[].name'
trelly boards lists BOARD_ID
trelly boards cards BOARD_ID          # or: api GET /boards/{id}/cards
trelly lists cards LIST_ID
trelly cards get CARD_ID --fields name,desc
trelly cards comments CARD_ID
trelly cards create --list LIST_ID --name "Task"
trelly cards move CARD_ID --list OTHER_LIST_ID
trelly cards comment CARD_ID --text "Done"
trelly cards edit-comment CARD_ID COMMENT_ID --text "Updated"
trelly cards delete-comment CARD_ID COMMENT_ID # permanent
trelly cards attachments CARD_ID
trelly cards add-attachment CARD_ID --url "https://github.com/org/repo/pull/42"
trelly search "query"
trelly ui BOARD_ID                    # interactive kanban (TTY required)
trelly auth list
trelly install                        # install detected agent plugins
trelly update --check                 # CLI + installed plugin updates
```

Global: `-p, --profile <name>` (or `TRELLO_PROFILE`), `--fresh` to bypass and refresh
the CLI response cache. Successful CLI GETs are cached on disk briefly; set
`TRELLO_CACHE=0` to disable caching.

## Raw API escape hatch

```bash
trelly api -X GET --path /members/me
trelly api -X PUT --path /cards/CARD_ID --query idList=LIST_ID
trelly api -X POST --path /cards --body '{"idList":"LIST_ID","name":"Hi"}'
```

Request body flag is **`--body`** (not `--json` — that flag is global output).

## Card comments

```bash
trelly cards comments CARD_ID
trelly cards comment CARD_ID --text "Done"
trelly cards edit-comment CARD_ID COMMENT_ID --text "Updated"
trelly cards delete-comment CARD_ID COMMENT_ID
```

`COMMENT_ID` is the action `id` returned by `cards comments`. Comment deletion is
**permanent** and subject to Trello permissions.

## Card attachments

```bash
trelly cards attachments CARD_ID
trelly cards add-attachment CARD_ID --url "https://…" [--name "label"]
trelly cards add-attachment CARD_ID --file ./screenshot.png [--name "label"]
trelly cards delete-attachment CARD_ID ATTACHMENT_ID
```

Pass **exactly one** of `--url` or `--file`. In `trelly ui`, open a card's detail (**⏎**), then **a** opens the attach prompt (URL or local path).

## GitHub PR / commit on a card

Boards with the **GitHub Power-Up** enabled can show rich PR metadata in the Trello UI.
trelly attaches the same underlying **URL attachment** — it does **not** drive the
Power-Up picker or OAuth flow.

### Link a PR or commit (preferred)

```bash
# Pull request — set --name so the attachment is scannable in lists/UI
trelly cards add-attachment CARD_ID \
  --url "https://github.com/org/repo/pull/42" \
  --name "#42 fix authentication bug"

# Commit
trelly cards add-attachment CARD_ID \
  --url "https://github.com/org/repo/commit/abc1234" \
  --name "abc1234 Merge PR #42"

# Issue (same mechanism)
trelly cards add-attachment CARD_ID \
  --url "https://github.com/org/repo/issues/42"
```

Accepted URL shapes: `…/pull/N`, `…/commit/SHA`, `…/issues/N`, `…/tree/branch`.
Use the canonical `https://github.com/…` URL (no `/files` or `/commits` tab suffix).

### Power-Up UI vs trelly URL attachment

| Feature | GitHub Power-Up (Trello UI) | `cards add-attachment --url` |
|--------|-----------------------------|------------------------------|
| Link on card | Yes | Yes |
| Readable `--name` / PR title | Yes (auto) | Set `--name` yourself (recommended) |
| CI/check badges on card front | Yes | No |
| Pick PR from repo browser | Yes | No — pass URL |
| Comment back on GitHub PR | Yes (optional setting) | No |

If the user needs badges or GitHub-side back-links, attach via **Power-Ups → GitHub**
in Trello. For agent/CLI workflows (ship PR → link card → move list), URL attachment
is enough.

### Agent workflow patterns

**After opening or merging a PR** — attach and optionally move the card:

```bash
CARD_ID=…
PR_URL="https://github.com/org/repo/pull/42"
trelly cards add-attachment "$CARD_ID" --url "$PR_URL" --name "#42 fix scope"
trelly cards move "$CARD_ID" --list PENDING_REVIEW_LIST_ID
```

**Fallback — comment only** (visible in activity, not Attachments):

```bash
trelly cards comment CARD_ID --text "PR: https://github.com/org/repo/pull/42"
```

**Inspect what's linked:**

```bash
trelly --json cards attachments CARD_ID | jq '.data[] | {name, url}'
```

### Raw API (same as CLI)

```bash
trelly api -X POST --path "/cards/CARD_ID/attachments" \
  --query "url=https://github.com/org/repo/pull/42" \
  --query "name=#42 feature title"
```

## Custom fields (list-type)

```bash
trelly api -X PUT \
  --path "/cards/CARD_ID/customField/FIELD_ID/item" \
  --body '{"idValue":"OPTION_ID"}'
```

## Safety

| Action | CLI | Reversible? |
|--------|-----|-------------|
| Close | `cards archive`, `boards archive` | Yes (Trello UI) |
| Destroy | `cards delete`, `boards delete`, `cards delete-comment` | **No** |

Prefer **archive** unless the user explicitly wants permanent deletion.

## Multi-profile

```bash
trelly auth login --profile work
trelly -p work boards list
```

Env override: `TRELLO_APP_API_KEY`, `TRELLO_API_KEY`, `TRELLO_TOKEN`, `TRELLO_PROFILE`.

## Updating trelly and agent plugins

```bash
trelly install
trelly install --cursor --claude
trelly install --all --yes
trelly update --check
trelly update --yes
trelly --json update --check
```

`trelly install` installs or repairs Cursor, Claude Code, and Codex plugins. Select hosts
with `--cursor`, `--claude`, and `--codex`; use `--check` for a read-only status. `trelly
update` detects npm, Bun, Homebrew, source, and ephemeral installs and refreshes installed
plugins. Never bypass a dirty source-checkout refusal; commit, stash, or discard those
changes explicitly first.

## MCP vs CLI

- **MCP (default in agent hosts):** structured `trello_*` tools — see
  **trelly-mcp** skill.
- **CLI:** terminal use, shell automation, or interactive `trelly ui`; human or
  `--json` on stdout.