trelly

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. 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

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, 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. 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

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

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

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

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)

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

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):

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

Inspect what's linked:

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

Raw API (same as CLI)

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)

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

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

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.