你的仓库，尽在终端
taskforge 是一个命令行待办事项应用，用来处理你 Obsidian 仓库里的任务和笔记。查询和完成任务、创建和编辑笔记，或者把同样的命令交给 shell 脚本或智能体。它使用应用本身的解析器，在你的电脑上写入真实的 Markdown 文件。
CLI 还是 MCP 服务器？
在没有 MCP 连接的 shell 环境中使用 CLI：脚本、cron、CI，或是在仓库检出目录里工作的编码智能体。如果你的智能体已经与 TaskForge 建立了 MCP 连接，则优先使用 MCP 工具；它们是类型化的，返回结构化错误，方便智能体据此自我纠正，而且不需要在你的 PATH 里安装任何东西。两者驱动的是同一个引擎，语义完全一致，选择你运行环境里已经接好的那一个就行。手动编辑仓库文件是最后的办法。
安装
使用 Node.js 试用（含 npm 和 npx）：
全局安装 taskforge 命令：
需要安装含 npm/npx 的 Node.js。npm 会为 macOS、Windows（x64）和 Linux（x64 与 arm64）安装原生二进制文件。TaskForge 应用还没有 Linux 版，在 Linux 上你可以使用 CLI 和 MCP 服务器。CLI 需独立于应用安装；不再支持 Homebrew。
快速上手
使用 --vault 让 taskforge 指向某个仓库，或者一次性设置 TASKFORGE_VAULT。每个读取类命令都支持 --json 参数，输出机器可读的结果，方便智能体解析。
打印仓库的任务语法：状态符号、日期格式、自定义字段、新任务的去向。这是智能体首先要读取的信息。
把一条任务追加到仓库的默认新任务位置，格式与你仓库自己的任务书写方式一致。
统计带有自定义字段 priority_label:: urgent 的任务数量，优先级最高的排在最前。去掉 --count 即可列出这些任务。
查找描述中提到 invoice、标题中提到 acme 的任务，以 JSON 形式输出。匹配时忽略重音符号和大小写，因此 cafe 也能匹配 café。
完成一个任务。如果是重复任务，下一次的任务会写回文件，和应用里的处理方式完全一致。
读取一个任务及其内容哈希，这样后续编辑可以传入 --if-hash，拒绝覆盖过期的副本。
查询语法
查询参数是一组以空格分隔的标记，必须全部匹配。常用的标记有：
| text:word | 标题包含该词（忽略重音符号和大小写）。 | text:groceries |
| desc:"phrase" | 任务描述包含该短语。 | desc:"send invoice" |
| tag:name | 任务带有 #name 标签。 | tag:work |
| prop:key=value | 自定义字段 key 的值等于 value。 | prop:area=home |
| prop:key | 自定义字段 key 存在，值不限。 | prop:estimate |
| --sort due|priority|created | 对结果排序。默认按截止日期，最近的排最前。 | --sort priority |
| --count | 返回匹配数量，而不是任务列表本身。 | --count |
自定义字段的 key 可以包含字母、数字和下划线，因此 priority_label 和 area_2 都是合法写法。
唯一的前提条件：仓库契约文件
taskforge 会读取一个由 TaskForge 写入你仓库的小型契约文件 TaskForge/Settings/dialect.json，它精确描述你的任务格式，让 CLI 按你的方式编辑任务，而不是靠猜测。请至少用 TaskForge 3.0 或更高版本打开一次仓库，进入“设置 → AI 与智能体”，并保持“生成智能体文件”开启。这样就会写入这份契约文件。TaskForge/Settings 是默认位置，根文件夹可以在应用中改名。
如果 taskforge 找不到仓库，它会告诉你三种指定仓库的方法：
- 在命令中传入 --vault /path/to/vault。
- 设置 TASKFORGE_VAULT 环境变量。
- 用 TaskForge 3.0 及以上版本打开一次仓库，使 TaskForge/Settings/dialect.json 文件存在，然后在该仓库文件夹内运行命令。
仅在本地运行
taskforge 在你自己的电脑上运行，只会接触你指定仓库中的 markdown 文件。不需要账号，不需要 API 密钥，也不会发起任何网络请求。无论你用什么方式同步仓库，iCloud、Dropbox 还是 Obsidian Sync，改动都会随之送达你的其他设备。
想让智能体来操作它？
CLI 面向终端和脚本。如果你想让 Claude Desktop 或其他 MCP 客户端通过工具接口添加和完成任务，请改用 MCP 服务器。同一个仓库，同一套规则。两种方式用的都是同一个 taskforge 二进制文件，运行 taskforge mcp --stdio 就能把它切换成 MCP 服务器。
设置 MCP 服务器 →CLI 编辑任务，应用让它们持续可用。
taskforge 可以从任意终端写入你的仓库；TaskForge 把同一批文件变成你手机和电脑上的列表、小组件和提醒。可在 iPhone、iPad、Mac、安卓和 Windows 上免费下载。
