Trelly -- Trello CLI

Fast Trello CLI + MCP server (npm: npm install -g trelly). Human, Trello-styled output by default; add --json for scripts and automation. Commands: trelly (CLI) and trelly-mcp (MCP server).

Boards, lists, cards, checklists, labels, custom fields, search, webhooks, multi-profile auth, interactive kanban TUI, raw trelly api escape hatch.

Install

npm install -g trelly                   # npm (Node 22+)
brew install brandonkramer/tap/trelly   # Homebrew
bunx trelly                             # run without installing (Bun)
npx trelly                              # run without installing (Node 22+)

From source (repo brandonkramer/trelly):

git clone https://github.com/brandonkramer/trelly.git && cd trelly
bun install
./bin/trelly auth setup
./bin/trelly auth login
./bin/trelly boards list

No Bun? npm install in the clone — tsx is the fallback runtime.

Optional: bun link / npm link, or add bin/ to PATH.

Updating

npm update -g trelly          # or: npm install -g trelly@latest
brew upgrade trelly           # Homebrew

Auth in ~/.config/trelly/config.json is kept across upgrades. Reload your IDE after updating if you use the agent plugin MCP server.

Quick start

trelly auth setup    # once: API key from power-ups/admin
trelly auth login    # browser → Allow
trelly boards list

Output

Mode	Command	stdout
Default	trelly boards list	Styled rows (labels, due badges, etc.)
JSON	trelly --json boards list	{ ok, profile, data }
Pretty JSON	trelly --json --pretty boards list	Indented envelope

• Errors: red ✗ message in human mode, exit code 1 (use --json for { ok: false, ... }).
• Pipes: colors auto-disable when stdout is not a TTY.
• Scripts: always pass --json if you parse stdout. The MCP server is unchanged (never uses CLI output).

Interactive UI

Bare trelly (no subcommand) opens the Ink kanban board in your terminal — same as trelly ui.

trelly              # board picker when no id given
trelly ui           # same
trelly ui BOARD_ID  # jump straight to a board

Requires a TTY. Keys: arrows / hjkl move focus, Enter card detail, r refresh, q / Esc back or quit.

In card detail: ↑↓ move over attachments and comments, Enter opens the focused attachment in your browser or expands/collapses the focused comment, c new comment, r reply to the focused comment (prefills @author), a attach a file path or URL, Esc back.

See the demo above or run trelly --help for all subcommands.

Auth

Two steps: API key (app identity, once) → token (your account, per profile). After login the CLI is you on Trello — same boards and permissions as the website.

1 · Get an API key (once). trelly auth setup opens power-ups/admin and prompts for the key:

1. Create a Power-Up — registers the app; nothing is installed on your boards.
2. Any workspace you admin (personal is fine); it doesn't limit board access.
3. Iframe URL: any https:// placeholder.
4. API Key tab → Generate API Key; add http://127.0.0.1:14189 to Allowed Origins (for browser login).
5. Paste the key at the prompt.

2 · Log in. trelly auth login — browser opens → Allow.

Variant	Command
Redirect blocked	auth login --manual (paste token)
Never-expiring token	auth login --full-access (otherwise 30 days)
More accounts	auth login --profile work · auth use work · auth logout -p work · -p on any command
Inspect	auth list (profiles) · auth url (authorize URL)
Non-interactive	auth setup --api-key KEY then auth login --api-key KEY --token TOKEN

Env overrides: TRELLO_API_KEY + TRELLO_TOKEN (bypass profiles), TRELLO_PROFILE, TRELLO_APP_API_KEY. Credentials: ~/.config/trelly/config.json (mode 600).

Usage

trelly boards list
trelly --json --pretty boards list | jq '.data[].name'
trelly --profile work boards lists BOARD_ID
trelly cards create --list LIST_ID --name "Ship feature"
trelly cards comments CARD_ID
trelly cards comment CARD_ID --text "Shipped"
trelly cards add-attachment CARD_ID --file screenshot.png   # or --url https://…
trelly search "customer onboarding"
trelly api -X PUT --path /cards/CARD_ID --query idList=LIST_ID
trelly api -X POST --path /cards --body '{"idList":"LIST_ID","name":"Hi"}'

Flags: -p, --profile <name>, --json, --pretty (with --json only).

Archive (reversible) vs delete (permanent): prefer cards archive / boards archive over cards delete / boards delete.

Command reference

Top-level: auth · boards · lists · cards · checklists · labels · custom-fields · search · webhooks · members · orgs · actions · api · ui

Group	Subcommands
auth	setup · login · list · use · logout · url
boards	list · get · create · update · archive · delete · lists · cards · labels · members · actions · custom-fields
lists	get · create · update · archive · cards
cards	get · list · create · update · move · comments · comment · archive · delete · members · add-member · remove-member · labels · add-label · remove-label · actions · attachments · add-attachment · delete-attachment · custom-fields
checklists	get · create · update · delete · add-item · update-item · delete-item
labels	get · create · update · delete
custom-fields	get · create · update · delete · set-item
search	<query> (--model-types, limits)
webhooks	list · create · get · delete
members	me
orgs	get · boards
actions	get
api	raw REST (-X, --path, --query, --body)
ui	[boardId] — or run bare trello / trelly

List-type custom field values: use trelly api with PUT /cards/{id}/customField/{fieldId}/item and {"idValue":"..."} (see skills/trelly/SKILL.md).

Per-subcommand flags: trelly <group> --help. Curated examples and agent guidance: skills/trelly/SKILL.md.

MCP

Add trelly to your IDE or platform MCP server configuration (under "mcpServers", see mcp.example.json):

"trelly": {
  "command": "trelly-mcp",
  "env": { "TRELLO_PROFILE": "default" }
}

Typical configuration paths:

• Cursor: ~/.cursor/mcp.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux)
• Antigravity (agy): ~/.gemini/antigravity/mcp_config.json
• Codex: ~/.codex/config.toml (TOML format under [mcp_servers.trelly])

After npm install -g trelly, trelly-mcp is on your PATH. From a clone, use the full path to bin/trelly-mcp.

Stdio server — JSON envelope on every tool ({ ok, profile, data }), never CLI human output. Pass profile on any tool for a non-default account. Prefer trello_*_archive over trello_card_delete (permanent; no board-delete MCP tool).

MCP tools (27)

Tool	Purpose
trello_profiles_list	Saved profiles + default
trello_member_me	Authenticated member
trello_boards_list	Member boards
trello_board_get	Board by id
trello_board_create	Create board
trello_board_archive	Close board (reversible)
trello_board_lists	Lists on board
trello_board_cards	All cards on board
trello_list_create	Create list
trello_list_cards	Cards in list
trello_card_get	Card by id
trello_card_create	Create card
trello_card_update	Update card fields
trello_card_move	Move to another list
trello_card_comments	List comments
trello_card_comment	Add comment
trello_card_archive	Close card (reversible)
trello_card_delete	Permanent delete
trello_checklist_create	Checklist on card
trello_checklist_add_item	Checklist item
trello_label_create	Board label
trello_card_add_label	Label on card
trello_search	Search Trello
trello_webhooks_list	Token webhooks
trello_webhook_create	Create webhook
trello_webhook_delete	Delete webhook
trello_api	Raw REST escape hatch

Full tool notes and MCP vs CLI guidance: skills/trelly-mcp/SKILL.md.

Development

bun run typecheck && bun test && bun run lint

CI runs the same via bun install --frozen-lockfile. See AGENTS.md for conventions.

Agent skills & plugins

Skills + IDE plugins ship in the npm package so agents learn CLI/MCP conventions (card display lists, GitHub links, archive vs delete).

Install trelly + auth once, then pick your platform:

Platform	Install
Pi	pi install npm:trelly (skills + CLI only)
Claude Code	claude plugin install "$(npm root -g)/trelly" → reload
Cursor	cp -R "$(npm root -g)/trelly" ~/.cursor/plugins/local/trelly → reload window
Codex	Local marketplace → /plugins → install Trelly
Antigravity	agy plugin install "$(npm root -g)/trelly/.antigravity-plugin"

npm install -g trelly && trelly auth setup && trelly auth login

Step-by-step for each platform, verify/update, and MCP-only fallback: skills/README.md · CHANGELOG.md

Also: PLUGIN.md · PRIVACY.md

License

MIT