scale-flow/trello-cli

using-trello-cli

Operate Trello through the local CLI tool.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/scale-flow/trello-cli --skill using-trello-cli

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

This skill teaches you how to translate natural-language Trello requests into safe, multi-step trello CLI workflows. The CLI outputs deterministic JSON — every response is machine-parseable and follows a stable contract.

Resolve the Binary

Try these in order — use whichever works first:

  1. trello on PATH
  2. ./bin/trello (relative to the repo root)
  3. Build from the repo: go build -o bin/trello ./cmd/trello

Once resolved, use that path for all subsequent commands in the session.

Preflight: Check Auth

Before any resource command, verify credentials are configured:

bash
trello auth status

The response follows the JSON envelope. If ok is false or the auth mode is key_only, stop and explain the issue to the user. Do not attempt resource commands without valid auth.

Auth can come from three sources:

  • Device flow (preferred — via trello auth login with Power-Up pairing)
  • OS keyring (stored credentials via trello auth set or trello auth login)
  • Environment variables TRELLO_API_KEY and TRELLO_TOKEN

Device Flow Authentication (Preferred)

When authenticating a new user, prefer the device flow over manual API key setup:

  1. Run trello auth login — this contacts the pairing service and displays a code
  2. Present the pairing code to the user: "Enter this code in your Trello board's CLI Connector Power-Up: XXXX-XXXX"
  3. The command blocks until the user completes pairing (up to 15 minutes)
  4. On success, credentials are stored automatically — no API key or token handling needed
  5. If the pairing service is unavailable, the CLI falls back to browser-based login automatically

The device flow is ideal for non-technical users and agent-driven workflows because it requires no developer portal access.

Core Workflow: Discover, Mutate, Verify

Every Trello task follows this shape:

  1. Discover — find the IDs you need (boards, lists, cards) using read commands or search
  2. Mutate — run the minimum command to accomplish the task
  3. Verify — re-fetch the resource to confirm the change took effect

This matters because the CLI uses IDs, not names. Never guess an ID — always discover it first.

Example: "Create a card in the Doing list on the Marketing board"

  1. trello boards list → find Marketing board ID
  2. trello lists list --board <board-id> → find Doing list ID
  3. trello cards create --list <list-id> --name "My card"
  4. trello cards get --card <card-id> → confirm creation

JSON Contract

Every command returns one of two envelopes:

json
{"ok": true, "data": ...}
{"ok": false, "error": {"code": "...", "message": "..."}}

Always branch on ok. Read payloads from data, errors from error.code and error.message. The --pretty flag changes formatting only, not the schema.

Use compact JSON (no --pretty) when piping output or extracting values programmatically. Use --pretty when showing results to the user.

Safety Rules

  • Prefer reads first when names are ambiguous — list boards/lists before mutating
  • Use IDs after discovery — never pass names where an ID is expected
  • Never guess IDs — always discover them from a list or search command
  • Re-fetch after mutations when confirmation matters
  • Validate file paths before attachments add-file
  • Use ISO-8601 for --due and --date values
  • `cards list` requires exactly one of --board or --list, never both
  • Update commands need at least one mutation field

Intent Interpretation

When the user describes a Trello task in natural language, translate it into a multi-step workflow — not a single command. Think about what IDs you need and how to get them.

Common patterns:

  • "Move card X to Done" → discover the Done list ID, then cards move, then verify
  • "Add a checklist to card X" → checklists create, add items, list to confirm
  • "Find boards about marketing" → search boards --query marketing or boards list and filter
  • "Set priority to High on card X" → discover custom field ID, then custom-fields items set

Read references/task-recipes.md for complete workflow recipes covering all resource types.

Command Reference

The CLI has 12 top-level command groups: auth, boards, lists, cards, comments, checklists, attachments, custom-fields, labels, members, search, version.

Read references/command-digest.md for the full command surface, flags, and validation rules.

Error Handling

When a command returns ok: false, check the error code:

CodeMeaningWhat to do
AUTH_REQUIREDNo credentials configuredGuide user through auth set or auth login
AUTH_INVALIDCredentials rejected by TrelloCredentials may be expired — re-authenticate
NOT_FOUNDResource ID doesn't existRe-discover the ID
VALIDATION_ERRORBad input (missing flag, wrong format)Fix the command flags
RATE_LIMITEDTrello API rate limit hitWait and retry
CONFLICTResource state conflictRe-fetch and retry