trelly 0.1.0

package/README.md

@@ -0,0 +1,191 @@
+# trelly ~ trello CLI
+
+Fast Trello CLI + MCP server ([npm](https://www.npmjs.com/package/trelly): `npm install -g trelly`).
+**Human, Trello-styled output by default**; add `--json` for scripts and automation.
+Commands: **`trelly`** (CLI) and **`trelly-mcp`** (MCP server).
+
+![trelly interactive UI](cli.gif)
+
+Boards, lists, cards, checklists, labels, custom fields, search, webhooks, multi-profile
+auth, interactive kanban TUI, raw `trelly api` escape hatch.
+
+## Quick start
+
+```bash
+npm install -g trelly
+trelly auth setup    # once: API key from power-ups/admin
+trelly auth login    # browser → Allow
+trelly boards list
+```
+
+From source (repo [brandonkramer/trelly](https://github.com/brandonkramer/trelly)):
+
+```bash
+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`.
+
+## 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`.
+
+```bash
+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.
+
+See the demo above or run `trelly --help` for all subcommands.
+
+## Auth
+
+Two steps: **API key** (app identity, once) → **token** (your account, per profile).
+
+Register a throwaway app at [power-ups/admin](https://trello.com/power-ups/admin) — you are **not** installing a Power-Up on your boards. Pick any workspace you **admin** (personal is fine); that choice does not limit which boards you can use. Iframe URL can be any `https://` placeholder (e.g. `https://example.com`). Add `http://127.0.0.1:14189` to **Allowed Origins** for automatic browser login.
+
+After login the CLI is **you** on Trello — same boards and permissions as the website.
+
+```bash
+trelly auth setup
+trelly auth login
+trelly auth login --profile work
+trelly auth login --manual              # paste token if redirect blocked
+trelly auth login --full-access         # never-expiring token
+trelly auth list
+trelly auth use work
+trelly auth logout --profile work
+trelly auth url
+```
+
+Non-interactive: `trelly auth setup --api-key KEY` then `trelly auth login --api-key KEY --token TOKEN`.
+
+Environment override: `TRELLO_APP_API_KEY`, `TRELLO_API_KEY`, `TRELLO_TOKEN`, `TRELLO_PROFILE`.
+
+Credentials: `~/.config/trelly/config.json` (mode `600`).
+
+## Usage
+
+```bash
+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 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` · `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](skills/trelly/SKILL.md)).
+
+Per-subcommand flags: `trelly <group> --help`. Curated examples and agent guidance: [skills/trelly/SKILL.md](skills/trelly/SKILL.md).
+
+## MCP
+
+Add to `~/.cursor/mcp.json` (see `mcp.example.json`):
+
+```json
+"trelly": {
+  "command": "trelly-mcp",
+  "env": { "TRELLO_PROFILE": "default" }
+}
+```
+
+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](skills/trelly-mcp/SKILL.md).
+
+## Development
+
+```bash
+bun run typecheck && bun test && bun run lint
+```
+
+CI runs the same via `bun install --frozen-lockfile`. See `AGENTS.md` for conventions.
+
+**Agent skills:** [skills/](skills/README.md) — portable `SKILL.md` files for Cursor, Claude, Pi, Codex (`trelly`, `trelly-mcp`).
+
+## License
+
+MIT

package/bin/run-ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+run_ts() {
+  local entry="$1"
+  shift
+
+  if command -v bun >/dev/null 2>&1 && bun --version >/dev/null 2>&1; then
+    exec bun run "$ROOT/$entry" "$@"
+  fi
+
+  if [[ -x "$HOME/.bun/bin/bun" ]]; then
+    exec "$HOME/.bun/bin/bun" run "$ROOT/$entry" "$@"
+  fi
+
+  if [[ -x "$ROOT/node_modules/.bin/tsx" ]]; then
+    exec "$ROOT/node_modules/.bin/tsx" "$ROOT/$entry" "$@"
+  fi
+
+  if command -v tsx >/dev/null 2>&1; then
+    exec tsx "$ROOT/$entry" "$@"
+  fi
+
+  echo "No runtime found. Install deps first:" >&2
+  echo "  bun install" >&2
+  echo "  # fallback (Node 22+): npm install" >&2
+  exit 1
+}
+
+run_ts "$@"

package/bin/trelly

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec "$(dirname "$0")/run-ts" "src/cli/index.ts" "$@"

package/bin/trelly-mcp

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec "$(dirname "$0")/run-ts" "src/mcp/server.ts" "$@"

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "trelly",
+  "version": "0.1.0",
+  "description": "trelly — fast Trello CLI with multi-profile auth, MCP server, and kanban TUI",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/brandonkramer/trelly#readme",
+  "keywords": [
+    "trello",
+    "cli",
+    "trelly",
+    "mcp",
+    "kanban",
+    "automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brandonkramer/trelly.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "bin": {
+    "trelly": "./bin/trelly",
+    "trelly-mcp": "./bin/trelly-mcp"
+  },
+  "scripts": {
+    "trelly": "bun src/cli/index.ts",
+    "mcp": "bun src/mcp/server.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "biome check .",
+    "fmt": "biome format --write .",
+    "fmt:check": "biome check .",
+    "postinstall": "chmod +x bin/trelly bin/trelly-mcp bin/run-ts 2>/dev/null || true",
+    "prepublishOnly": "bun run typecheck && bun test && bun run lint"
+  },
+  "engines": {
+    "bun": ">=1.2.0",
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^15.0.0",
+    "ink": "^7.1.0",
+    "react": "^19.2.7",
+    "tsx": "^4.22.5",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.2",
+    "@types/node": "^26.1.0",
+    "@types/react": "^19.2.17",
+    "typescript": "^6.0.3"
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,332 @@
+import {
+  type JsonValue,
+  parseTrelloResponse,
+  type Query,
+  type RequestOptions,
+  TrelloError,
+  trelloErrorMessage,
+  trelloFetch,
+} from "./http.ts";
+
+export {
+  type JsonValue,
+  type Query,
+  type RequestOptions,
+  TrelloError,
+} from "./http.ts";
+
+export class TrelloClient {
+  private readonly base = "https://api.trello.com/1";
+
+  constructor(
+    private readonly apiKey: string,
+    private readonly token: string,
+    private readonly requestOptions: RequestOptions = {},
+  ) {}
+
+  async request<T = JsonValue>(
+    method: string,
+    path: string,
+    query: Query = {},
+    body?: JsonValue,
+  ): Promise<T> {
+    const url = new URL(`${this.base}${path.startsWith("/") ? path : `/${path}`}`);
+
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+
+    const headers: Record<string, string> = {
+      Authorization: `OAuth oauth_consumer_key="${this.apiKey}", oauth_token="${this.token}"`,
+    };
+
+    const init: RequestInit = { method, headers };
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      init.body = JSON.stringify(body);
+    }
+
+    const res = await trelloFetch(url, init, this.requestOptions);
+    const text = await res.text();
+    const parsed = parseTrelloResponse(text);
+
+    if (!res.ok) {
+      throw new TrelloError(trelloErrorMessage(parsed, res.status), res.status, parsed);
+    }
+
+    return parsed as T;
+  }
+
+  get<T = JsonValue>(path: string, query?: Query): Promise<T> {
+    return this.request("GET", path, query);
+  }
+
+  post<T = JsonValue>(path: string, query?: Query, body?: JsonValue): Promise<T> {
+    return this.request("POST", path, query, body);
+  }
+
+  put<T = JsonValue>(path: string, query?: Query, body?: JsonValue): Promise<T> {
+    return this.request("PUT", path, query, body);
+  }
+
+  delete<T = JsonValue>(path: string, query?: Query): Promise<T> {
+    return this.request("DELETE", path, query);
+  }
+
+  memberMe(fields = "fullName,username,url,email") {
+    return this.get("/members/me", { fields });
+  }
+
+  memberBoards(memberId = "me", query: Query = {}) {
+    return this.get(`/members/${memberId}/boards`, query);
+  }
+
+  boardGet(id: string, query: Query = {}) {
+    return this.get(`/boards/${id}`, query);
+  }
+
+  boardCreate(query: Query) {
+    return this.post("/boards", query);
+  }
+
+  boardUpdate(id: string, query: Query) {
+    return this.put(`/boards/${id}`, query);
+  }
+
+  /** Close (archive) a board — reversible in Trello UI. */
+  boardArchive(id: string) {
+    return this.put(`/boards/${id}/closed`, { value: true });
+  }
+
+  /** Permanently delete a board. Irreversible. */
+  boardDelete(id: string) {
+    return this.delete(`/boards/${id}`);
+  }
+
+  boardLists(id: string, query: Query = {}) {
+    return this.get(`/boards/${id}/lists`, query);
+  }
+
+  boardCards(id: string, query: Query = {}) {
+    return this.get(`/boards/${id}/cards`, query);
+  }
+
+  boardLabels(id: string, query: Query = {}) {
+    return this.get(`/boards/${id}/labels`, query);
+  }
+
+  boardMembers(id: string, query: Query = {}) {
+    return this.get(`/boards/${id}/members`, query);
+  }
+
+  boardActions(id: string, query: Query = {}) {
+    return this.get(`/boards/${id}/actions`, query);
+  }
+
+  boardCustomFields(id: string) {
+    return this.get(`/boards/${id}/customFields`);
+  }
+
+  listGet(id: string, query: Query = {}) {
+    return this.get(`/lists/${id}`, query);
+  }
+
+  listCreate(query: Query) {
+    return this.post("/lists", query);
+  }
+
+  listUpdate(id: string, query: Query) {
+    return this.put(`/lists/${id}`, query);
+  }
+
+  listArchive(id: string) {
+    return this.put(`/lists/${id}/closed`, { value: true });
+  }
+
+  listCards(id: string, query: Query = {}) {
+    return this.get(`/lists/${id}/cards`, query);
+  }
+
+  cardGet(id: string, query: Query = {}) {
+    return this.get(`/cards/${id}`, query);
+  }
+
+  cardCreate(query: Query) {
+    return this.post("/cards", query);
+  }
+
+  cardUpdate(id: string, query: Query) {
+    return this.put(`/cards/${id}`, query);
+  }
+
+  /** Close (archive) a card — reversible in Trello UI. */
+  cardArchive(id: string) {
+    return this.put(`/cards/${id}/closed`, { value: true });
+  }
+
+  /** Permanently delete a card. Irreversible. */
+  cardDelete(id: string) {
+    return this.delete(`/cards/${id}`);
+  }
+
+  cardComment(id: string, text: string) {
+    return this.post(`/cards/${id}/actions/comments`, { text });
+  }
+
+  cardMembers(id: string, query: Query = {}) {
+    return this.get(`/cards/${id}/members`, query);
+  }
+
+  cardAddMember(id: string, memberId: string) {
+    return this.post(`/cards/${id}/idMembers`, { value: memberId });
+  }
+
+  cardRemoveMember(id: string, memberId: string) {
+    return this.delete(`/cards/${id}/idMembers/${memberId}`);
+  }
+
+  cardLabels(id: string) {
+    return this.get(`/cards/${id}/labels`);
+  }
+
+  cardAddLabel(id: string, labelId: string) {
+    return this.post(`/cards/${id}/idLabels`, { value: labelId });
+  }
+
+  cardRemoveLabel(id: string, labelId: string) {
+    return this.delete(`/cards/${id}/idLabels/${labelId}`);
+  }
+
+  cardActions(id: string, query: Query = {}) {
+    return this.get(`/cards/${id}/actions`, query);
+  }
+
+  cardComments(id: string, query: Query = {}) {
+    return this.get(`/cards/${id}/actions`, {
+      filter: "commentCard",
+      ...query,
+    });
+  }
+
+  cardAttachments(id: string) {
+    return this.get(`/cards/${id}/attachments`);
+  }
+
+  cardAddAttachment(id: string, query: Query) {
+    return this.post(`/cards/${id}/attachments`, query);
+  }
+
+  cardCustomFieldItems(id: string) {
+    return this.get(`/cards/${id}/customFieldItems`);
+  }
+
+  checklistGet(id: string, query: Query = {}) {
+    return this.get(`/checklists/${id}`, query);
+  }
+
+  checklistCreate(query: Query) {
+    return this.post("/checklists", query);
+  }
+
+  checklistUpdate(id: string, query: Query) {
+    return this.put(`/checklists/${id}`, query);
+  }
+
+  checklistDelete(id: string) {
+    return this.delete(`/checklists/${id}`);
+  }
+
+  checklistAddItem(id: string, query: Query) {
+    return this.post(`/checklists/${id}/checkItems`, query);
+  }
+
+  checklistUpdateItem(checklistId: string, itemId: string, query: Query) {
+    return this.put(`/checklists/${checklistId}/checkItems/${itemId}`, query);
+  }
+
+  checklistDeleteItem(checklistId: string, itemId: string) {
+    return this.delete(`/checklists/${checklistId}/checkItems/${itemId}`);
+  }
+
+  labelGet(id: string, query: Query = {}) {
+    return this.get(`/labels/${id}`, query);
+  }
+
+  labelCreate(query: Query) {
+    return this.post("/labels", query);
+  }
+
+  labelUpdate(id: string, query: Query) {
+    return this.put(`/labels/${id}`, query);
+  }
+
+  labelDelete(id: string) {
+    return this.delete(`/labels/${id}`);
+  }
+
+  customFieldGet(id: string) {
+    return this.get(`/customFields/${id}`);
+  }
+
+  customFieldCreate(query: Query) {
+    return this.post("/customFields", query);
+  }
+
+  customFieldUpdate(id: string, query: Query) {
+    return this.put(`/customFields/${id}`, query);
+  }
+
+  customFieldDelete(id: string) {
+    return this.delete(`/customFields/${id}`);
+  }
+
+  customFieldUpdateItem(id: string, query: Query, body?: JsonValue) {
+    return this.put(`/customFields/${id}/item`, query, body);
+  }
+
+  actionGet(id: string, query: Query = {}) {
+    return this.get(`/actions/${id}`, query);
+  }
+
+  search(query: string, opts: Query = {}) {
+    return this.get("/search", { query, ...opts });
+  }
+
+  webhooksForToken() {
+    return this.get("/tokens/me/webhooks");
+  }
+
+  webhookCreate(query: Query) {
+    return this.post("/webhooks", query);
+  }
+
+  webhookGet(id: string) {
+    return this.get(`/webhooks/${id}`);
+  }
+
+  webhookDelete(id: string) {
+    return this.delete(`/webhooks/${id}`);
+  }
+
+  orgGet(id: string, query: Query = {}) {
+    return this.get(`/organizations/${id}`, query);
+  }
+
+  orgBoards(id: string, query: Query = {}) {
+    return this.get(`/organizations/${id}/boards`, query);
+  }
+
+  batch(urls: string[]) {
+    return this.get("/batch", { urls: urls.join(",") });
+  }
+}
+
+export function createClient(
+  apiKey: string,
+  token: string,
+  requestOptions?: RequestOptions,
+): TrelloClient {
+  return new TrelloClient(apiKey, token, requestOptions);
+}