用 ud CLI 在终端中管理任务

如果你大部分时间都在终端里工作，那么每次记录任务或查看待办事项都要切换到浏览器标签页，这种上下文切换完全没有必要。ud CLI 正是为了消除这种干扰而生。它将 UnDercontrol 的全部功能——任务增删改查、笔记、查询、看板——带入你的 shell 环境，并采用你已经熟悉的命令结构。

kubectl 风格的命令，因为它好用

CLI 使用与 kubectl 相同的动词-资源模式，这种模式让无数工程师觉得上手自然。你可以 get、describe、apply 和 delete 资源，无需建立新的心智模型。

# 列出所有任务
ud get task

# 查看任务完整详情（支持短 ID 前缀）
ud describe task 3de9f82b

# 从 markdown 文件创建或更新任务
ud apply -f task.md

# 删除任务
ud delete task abc123

apply 命令值得重点介绍。你的任务就是一个带有 YAML frontmatter 的 markdown 文件。如果文件中有 id 字段，则更新已有任务；没有 id，则新建任务。这使得批量更新、脚本化工作流以及版本控制的任务定义变得简单直接。

echo '---
title: Write release notes
status: in-progress
tags:
  - release
deadline: 2026-04-10
---

Draft the changelog and update the docs site.' | ud apply -f -

真正能过滤的查询语法

ud task query 提供了一种类 SQL 的过滤语言，用于查询你的任务。当任务数量多到"翻列表"不再是可行策略时，它就派上用场了。

# 本周截止的任务
ud task query "deadline BETWEEN 'today' AND '+7d'"

# 标记为 urgent 的进行中任务
ud task query "(status = 'todo' OR status = 'in-progress') AND tags = 'urgent'"

# 标题搜索
ud task query "title ILIKE '%api%'"

如果你不想考虑语法，ud task nlquery 支持直接输入自然语言，并通过 AI 将其转译为查询：

ud task nlquery "show me overdue tasks"
ud task nlquery "tasks tagged with work that are not done"

两个命令都支持 --sort、--order 和 --limit 参数，便于分页和排序，可以干净地组合进脚本或 shell 别名中。

用笔记记录进度

每个任务都支持笔记——简短的自由格式条目，充当持续更新的进度日志。这对于记录你实际做了什么很有用，而不只是最终状态。

ud task note add 3de9f82b "Finished the backend changes, opening PR now"
ud task note ls 3de9f82b

笔记也让 CLI 天然适合 AI 智能体工作流。智能体可以从计划文件创建任务，在每个步骤追加进度笔记，最后标记任务完成——全程无需打开浏览器。团队的其他成员可以在 UnDercontrol Web 界面或桌面应用中看到完整的历史记录。这种交接方式轻量、实用，真正跑得通。

需要可视化时，用交互式 TUI

不带任何参数运行 ud，会打开终端 UI——一个支持键盘操作的看板式界面，带有 vim 风格的按键绑定。

按键	操作
j / k	在任务间移动
Enter	打开任务详情
i	新建任务
x	切换状态
/	搜索
f	文件选择器（模糊搜索本地文件以创建任务）

文件选择器是个亮点。按 f，在当前目录中模糊搜索 markdown 文件，它就会变成一个任务——第一行作为标题，其余内容作为描述。如果你习惯在项目仓库中用 markdown 记笔记，并想把它们纳入任务追踪，这个功能非常实用。

多上下文支持多个服务器

如果你在多个环境中自托管 UnDercontrol——个人、工作、测试实例——上下文系统的处理方式与 kubectl 完全相同。

ud config set-context work --api-url https://ud.company.com
ud login --context work

# 单次命令使用不同上下文
UD_CONTEXT=personal ud get task

配置文件位于 ~/.config/ud/config.yaml。你也可以完全通过环境变量（UD_API_URL、UD_API_KEY、UD_TOKEN）驱动 CLI，无需修改配置文件，在 CI 流水线中同样可用。

快速开始

通过 npm、Homebrew 或一行 curl 命令安装：

npm install -g @oatnil/ud
# 或
brew install oatnil-top/ud/ud
# 或
curl -fsSL https://get.oatnil.com/ud | bash

然后指向你的 UnDercontrol 实例：

ud login

完整的命令参考——包括文件附件、多上下文认证和高级查询语法——请查阅 CLI Reference 文档。如果你还没有运行 UnDercontrol，自托管指南 介绍了如何在几分钟内用 Docker 启动一个服务器。