内容
<p>
<img src="assets/logo.svg" alt="Trelly" width="128" height="128" />
</p>
# Trelly -- Trello 命令行工具
快速的Trello命令行工具 + MCP服务器（[npm](https://www.npmjs.com/package/trelly): `npm install -g trelly`）。
**默认以人类可读、Trello样式的输出**；添加 `--json` 用于脚本和自动化。
命令： **`trelly`** （命令行工具）和 **`trelly-mcp`** （MCP服务器）。
板块、列表、卡片、检查清单、标签、自定义字段、搜索、网络钩子、多配置文件
身份验证、交互式看板终端界面、原始 `trelly api` 出口。
## 安装
```bash
npm install -g trelly # npm (Node 22+)
brew install brandonkramer/tap/trelly # Homebrew
bunx trelly # 运行但不安装 (Bun)
npx trelly # 运行但不安装 (Node 22+)
```
从源码（仓库 [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
```
没有Bun？ 在克隆中使用 `npm install` — tsx 是备用运行时。
可选： `bun link` / `npm link`，或将 `bin/` 添加到 `PATH`。
### 更新
```bash
npm update -g trelly # 或：npm install -g trelly@latest
brew upgrade trelly # Homebrew
```
身份验证信息保存在 `~/.config/trelly/config.json` 中，并在升级过程中保持不变。
如果您使用代理插件MCP服务器，请在更新后重新加载IDE。
## 快速开始
```bash
trelly auth setup # 一次：从Power-Ups/管理员获取API密钥
trelly auth login # 浏览器 → 允许
trelly boards list
```
## 输出
| 模式 | 命令 | 标准输出 |
|------|---------|--------|
| 默认 | `trelly boards list` | 样式化行（标签、截止日期徽章等） |
| JSON | `trelly --json boards list` | `{ ok, profile, data }` |
| 美化JSON | `trelly --json --pretty boards list` | 缩进信封 |
- **错误：** 红色 `✗ 消息` 在人类模式下，退出代码 `1` （使用 `--json` 获取 `{ ok: false, ... }` ）。
- **管道：** 当标准输出不是TTY时，颜色自动禁用。
- **脚本：** 始终在解析标准输出时传递 `--json` 。MCP服务器保持不变（从不使用CLI输出）。
## 交互式界面
裸 **`trelly`** （无子命令）打开终端中的Ink看板 — 与 `trelly ui` 相同。
```bash
trelly # 板块选择器，当未给定ID时
trelly ui # 相同
trelly ui BOARD_ID # 直接跳转到板块
```
需要TTY。按键： **箭头键** / **hjkl** 移动焦点， **Enter** 进入卡片详情， **r** 刷新， **q** / **Esc** 返回或退出。
在卡片详情中： **↑↓** 移动附件和评论， **Enter** 在浏览器中打开聚焦的附件或展开/折叠聚焦的评论， **c** 新评论， **r** 回复聚焦的评论（预填充 `@author`）， **a** 附加文件路径或URL， **Esc** 返回。
查看演示或运行 `trelly --help` 获取所有子命令。
## 身份验证
两步： **API密钥** （应用程序身份，一次）→ **令牌** （您的帐户，每个配置文件）。登录后，CLI代表您在Trello上 — 与网站上的权限相同的板块。
**1 · 获取API密钥（一次）。** `trelly auth setup` 打开 [power-ups/admin](https://trello.com/power-ups/admin) 并提示输入密钥：
1. 创建一个Power-Up — 注册应用程序；您的板块上没有任何内容被安装。
2. 任意您 **管理员** 的工作区（个人资料即可）；它不会限制板块访问。
3. Iframe URL：任意 `https://` 占位符。
4. API密钥选项卡 → **生成API密钥**；将 `http://127.0.0.1:14189` 添加到 **允许的来源** （用于浏览器登录）。
5. 在提示符下粘贴密钥。
**2 · 登录。** `trelly auth login` — 浏览器打开 → **允许**。
| 变体 | 命令 |
|---------|---------|
| 重定向被阻止 | `auth login --manual` （粘贴令牌） |
| 永不过期令牌 | `auth login --full-access` （否则30天） |
| 更多帐户 | `auth login --profile work` · `auth use work` · `auth logout -p work` · 命令上的 `-p` |
| 检查 | `auth list` （配置文件） · `auth url` （授权URL） |
| 非交互式 | `auth setup --api-key KEY` 然后 `auth login --api-key KEY --token TOKEN` |
环境变量覆盖： `TRELLO_API_KEY` + `TRELLO_TOKEN` （绕过配置文件）， `TRELLO_PROFILE`， `TRELLO_APP_API_KEY`。凭证： `~/.config/trelly/config.json` （模式 `600` ）。
## 用法
```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 cards add-attachment CARD_ID --file screenshot.png # 或 --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"}'
```
标志： `-p, --profile <name>`， `--json`， `--pretty` （仅与 `--json` 一起使用）。
**存档** （可逆）与 **删除** （永久）：优先使用 `cards archive` / `boards archive` 而不是 `cards delete` / `boards delete` 。
### 命令参考
顶级： `auth` · `boards` · `lists` · `cards` · `checklists` · `labels` · `custom-fields` · `search` · `webhooks` · `members` · `orgs` · `actions` · `api` · `ui`
| 组 | 子命令 |
|-------|-------------|
| **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` ，限制） |
| **webhooks** | `list` · `create` · `get` · `delete` |
| **members** | `me` |
| **orgs** | `get` · `boards` |
| **actions** | `get` |
| **api** | 原始REST（ `-X` ， `--path` ， `--query` ， `--body` ） |
| **ui** | `[boardId]` — 或运行裸 `trello` / `trelly` |
列表类型自定义字段值：使用 `trelly api` 和 `PUT /cards/{id}/customField/{fieldId}/item` 以及 `{"idValue":"..."}` （参见 [skills/trelly/SKILL.md](skills/trelly/SKILL.md) ）。
每个子命令的标志： `trelly <group> --help` 。精选示例和代理指南： [skills/trelly/SKILL.md](skills/trelly/SKILL.md)。
## MCP
将 `trelly` 添加到您的IDE或平台MCP服务器配置中（在 `"mcpServers"` 下，参见 [mcp.example.json](mcp.example.json) ）：
```json
"trelly": {
"command": "trelly-mcp",
"env": { "TRELLO_PROFILE": "default" }
}
```
典型配置路径：
- **Cursor**： `~/.cursor/mcp.json`
- **Claude Desktop**： `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `~/.config/Claude/claude_desktop_config.json` （Linux）
- **Antigravity（`agy`）**： `~/.gemini/antigravity/mcp_config.json`
- **Codex**： `~/.codex/config.toml` （TOML格式，位于 `[mcp_servers.trelly]` 下）
在 `npm install -g trelly` 之后， `trelly-mcp` 位于您的PATH中。从克隆仓库中，使用 `bin/trelly-mcp` 的完整路径。
标准输入/输出服务器 — 每个工具的JSON信封（ `{ ok, profile, data }` ），永不使用CLI人类输出。在任何工具上传递 **`profile`** 以使用非默认帐户。优先使用 **`trello_*_archive`** 而不是 **`trello_card_delete`** （永久；无板块删除MCP工具）。
### MCP工具（27）
| 工具 | 用途 |
|------|---------|
| `trello_profiles_list` | 已保存的配置文件 + 默认 |
| `trello_member_me` | 身份验证的成员 |
| `trello_boards_list` | 成员板块 |
| `trello_board_get` | 通过ID获取板块 |
| `trello_board_create` | 创建板块 |
| `trello_board_archive` | 关闭板块（可逆） |
| `trello_board_lists` | 板块上的列表 |
| `trello_board_cards` | 板块上的所有卡片 |
| `trello_list_create` | 创建列表 |
| `trello_list_cards` | 列表中的卡片 |
| `trello_card_get` | 通过ID获取卡片 |
| `trello_card_create` | 创建卡片 |
| `trello_card_update` | 更新卡片字段 |
| `trello_card_move` | 移动到另一个列表 |
| `trello_card_comments` | 列出评论 |
| `trello_card_comment` | 添加评论 |
| `trello_card_archive` | 关闭卡片（可逆） |
| `trello_card_delete` | **永久** 删除 |
| `trello_checklist_create` | 卡片上的检查清单 |
| `trello_checklist_add_item` | 检查清单项 |
| `trello_label_create` | 板块标签 |
| `trello_card_add_label` | 卡片上的标签 |
| `trello_search` | 搜索Trello |
| `trello_webhooks_list` | 令牌网络钩子 |
| `trello_webhook_create` | 创建网络钩子 |
| `trello_webhook_delete` | 删除网络钩子 |
| `trello_api` | 原始REST出口 |
完整的工具说明和MCP与CLI指南： [skills/trelly-mcp/SKILL.md](skills/trelly-mcp/SKILL.md)。
## 开发
```bash
bun run typecheck && bun test && bun run lint
```
CI通过 `bun install --frozen-lockfile` 运行相同的命令。参见 `AGENTS.md` 获取约定。
## 代理技能和插件
技能和IDE插件随npm包一起提供，因此代理可以学习CLI/MCP约定
（卡片 **`display`** 列表，GitHub链接，存档与删除）。
**安装 trelly + 身份验证一次**，然后选择您的平台：
| 平台 | 安装 |
|----------|---------|
| **Pi** | `pi install npm:trelly` （仅限技能和CLI） |
| **Claude Code** | `claude plugin install "$(npm root -g)/trelly"` → 重载 |
| **Cursor** | `cp -R "$(npm root -g)/trelly" ~/.cursor/plugins/local/trelly` → 重载窗口 |
| **Codex** | 本地市场 → `/plugins` → 安装Trelly |
| **Antigravity** | `agy plugin install "$(npm root -g)/trelly/.antigravity-plugin"` |
```bash
npm install -g trelly && trelly auth setup && trelly auth login
```
每个平台的逐步指南，验证/更新和MCP-only备用方案：
**[skills/README.md](skills/README.md)** · **[CHANGELOG.md](CHANGELOG.md)**
另见： [PLUGIN.md](PLUGIN.md) · [PRIVACY.md](PRIVACY.md)
## 许可证
MIT
