TinyTalkingTodos CLI

使用 ttt 命令行工具管理待办事项列表及其中的条目。该 CLI 与 TinyTalkingTodos 实时同步。

安装

npm install -g @ojschwa/ttt-cli

或在本地安装以供开发使用：

cd /path/to/talking-todo/ttt-cli
npm install
npm run build
npm link

运行 ttt --help 验证安装是否成功。

身份验证

使用 CLI 前，用户必须完成身份验证：

# 检查认证状态
ttt auth status

# 通过浏览器登录（启动 OAuth 流程）
ttt auth login

# 注销
ttt auth logout

# 导出凭据为环境变量（适用于脚本）
ttt auth export

列表管理

列出所有列表

ttt list ls

输出（紧凑格式，Token 占用少）：

Today [2/5]
Groceries [0/3]
Work Tasks [1/4]

如需结构化数据，请使用：

ttt list ls --json

获取列表详情

ttt list get "Groceries"
# 或按 ID 获取
ttt list get list-abc123

创建新列表

ttt list create "Weekend Plans"
ttt list create "Shopping" --icon "🛒" --color "#FF6B6B"

可选参数：

• --color — 背景颜色
• --icon — 列表图标
• --type — 列表类型

更新列表

ttt list update "Groceries" --name "Shopping List"
ttt list update "Shopping List" --icon "🛒" --color "#00FF00"

可选参数：

• --name — 新列表名称
• --color — 背景颜色
• --icon — 列表图标
• --type — 列表类型

删除列表

ttt list delete "Old List"
ttt list rm "Old List"  # 别名

# 强制删除（即使列表中存在待办事项）
ttt list delete "Old List" --force

待办事项操作

列出某列表中的待办事项

ttt todo ls --list "Groceries"

输出（紧凑格式）：

Groceries [1/4]
✓ Milk id:todo-abc123
○ Bread id:todo-def456
○ Eggs id:todo-ghi789
○ Butter id:todo-jkl012

如需 JSON 格式输出：

ttt todo ls --list "Groceries" --json

添加待办事项

基础用法：

ttt todo add "Buy avocados" --list "Groceries"

带参数的用法：

ttt todo add "Doctor appointment" --list "Health" 
  --date 2026-02-15 
  --time 14:30 
  --notes "Bring insurance card"

ttt todo add "Try new pasta place" --list "Restaurants" 
  --url "https://example.com/restaurant" 
  --street-address "123 Main St" 
  --rating 4

ttt todo add "Tomatoes" --list "Groceries" 
  --amount 2.50 
  --category "Produce" 
  --emoji "🍅"

所有支持的 --list 参数如下：

标记待办事项为已完成

ttt todo done todo-abc123

待办事项 ID 在紧凑格式输出中位于 id: 后面。

标记待办事项为未完成

ttt todo undone todo-abc123

更新待办事项

ttt todo update todo-abc123 --text "New text"
ttt todo update todo-abc123 --category "Urgent" --date 2026-02-15
ttt todo update todo-abc123 --done   # 标记为已完成
ttt todo update todo-abc123 --not-done  # 标记为未完成

可选参数：

• --text — 新的待办事项文本
• --notes、--date、--time、--url、--emoji、--email、--street-address
• --number、--amount、--rating、--type、--category
• --done / --not-done — 切换完成状态

删除待办事项

ttt todo delete todo-abc123
# 或使用别名
ttt todo rm todo-abc123

批量添加待办事项

使用 JSON 一次性添加多个待办事项：

ttt todo batch-add --list "Groceries" --items '[
  {"text": "Milk"},
  {"text": "Eggs", "fields": {"category": "Dairy"}},
  {"text": "Bread", "fields": {"amount": 3.50}}
]'

每个条目必须包含 text 字段，fields 字段为可选，可指定任意待办事项字段。

批量更新待办事项

一次性更新多个待办事项：

ttt todo batch-update --items '[
  {"id": "todo-abc123", "fields": {"done": true}},
  {"id": "todo-def456", "fields": {"text": "Updated text", "category": "Urgent"}}
]'

每个条目必须提供 id 和 fields（含要应用的更新内容）。

撤销操作

所有变更类操作均被记录，支持撤销：

# 撤销上一次操作
ttt undo

# 撤销最近三次操作
ttt undo 3

# 查看撤销历史
ttt history
ttt history --limit 20
ttt history --json

支持撤销的操作包括：待办事项增删改、批量增删改、标记完成/未完成、列表的创建/更新/删除。

守护进程（性能优化）

守护进程维持一个持久化的 WebSocket 连接，以提升命令执行速度：

# 启动守护进程（若未运行，首次命令将自动启动）
ttt daemon start

# 查看状态
ttt daemon status

# 停止守护进程
ttt daemon stop

守护进程将在闲置 30 分钟后自动关闭。

最佳实践

1. 面向用户展示列表时，请使用紧凑格式输出（默认）——更节省 Token
2. 需要解析数据或提取特定字段时，请使用 --json
3. 引用列表时优先使用名称（提高可读性），必要时再使用 ID（确保精确性）
4. 不确定登录状态时，请先检查认证状态（ttt auth status）
5. 从紧凑格式输出中提取待办事项 ID（格式：id:），用于后续更新操作
6. 批量添加或更新多个条目时，请使用批量操作——比单次调用更高效
7. 误操作后请使用撤销功能——ttt undo 可回退上一次操作

典型工作流示例

向购物清单添加条目

ttt todo add "Milk" --list "Groceries" --category "Dairy"
ttt todo add "Bread" --list "Groceries" --category "Bakery"
ttt todo add "Apples" --list "Groceries" --amount 3.50 --category "Produce"

查看并完成任务

# 查看待办事项
ttt todo ls --list "Today"

# 标记其中一项为完成（ID 来自上一步输出）
ttt todo done todo-xyz789

新建列表并添加待办事项

ttt list create "Weekend Trip" --icon "🏕️"
ttt todo add "Pack tent" --list "Weekend Trip"
ttt todo add "Check weather" --list "Weekend Trip" --url "https://weather.com"
ttt todo add "Gas up car" --list "Weekend Trip"

高效批量添加条目

ttt todo batch-add --list "Party Supplies" --items '[
  {"text": "Balloons", "fields": {"category": "Decorations"}},
  {"text": "Cake", "fields": {"category": "Food", "amount": 45.00}},
  {"text": "Plates", "fields": {"category": "Supplies", "number": 20}},
  {"text": "Candles", "fields": {"category": "Decorations"}}
]'

批量标记多个条目为完成

ttt todo batch-update --items '[
  {"id": "todo-abc", "fields": {"done": true}},
  {"id": "todo-def", "fields": {"done": true}},
  {"id": "todo-ghi", "fields": {"done": true}}
]'

撤销误操作

# 不小心删错了？立即撤销
ttt undo

# 连续犯了多个错误？可批量撤销
ttt undo 3