Taskwarrior 3.5.0 常用 CLI 命令与工具详解
逐条实测 Taskwarrior 3.5.0 命令全集：add 属性修饰与依赖/周期/wait、annotate/append/prepend/modify、start/stop/done/delete/undo、list/next/long 与过滤 DSL、stats/summary/timesheet、export/import/sync 与内省命令，附 GC 重编号等实测注意事项。
Taskwarrior 3.5.0 常用 CLI 命令与工具详解
目标：在 Debian 12 服务器上对 Taskwarrior 3.5.0 的日常命令做逐条实测——任务录入（add 及属性修饰、注记、依赖、周期）、状态流转（start/stop/done/delete/undo）、报表与过滤查询、导入导出与 sync，全部命令与回显逐行照抄真实环境。安装见《Taskwarrior 3.5.0 安装指南（发行版包与源码构建双线实测）》，配置项见《Taskwarrior 3.5.0 配置参数详解（.taskrc 逐项实测）》，选型背景见《Taskwarrior 3.5.0 介绍与选型指南》。
一、环境信息
| 项目 | 值（实测） |
|---|---|
| 操作系统 | Debian GNU/Linux 12 (bookworm)，x86_64 |
| Taskwarrior | 3.5.0（/usr/local/bin/task，源码构建） |
| 配置 | /root/.taskrc（含 color=on、dateformat.report=Y/m/d 等实测项） |
| 数据 | /root/.task/taskchampion.sqlite3 |
| 实测任务集 | 含普通任务、周期任务（recur:weekly）、依赖任务（depends）、等待任务（wait:）、已完成与已删除任务 |
💡 说明：Taskwarrior 全部能力集中在单一
task命令上——没有守护进程、没有客户端/服务端拆分；sync也只是同一个二进制的子命令。本文所有交互确认（yes/no）均在真实终端完成；脚本化复现可用echo yes | script -qec "…" /dev/null的 pty 方式（回显中可见）。
二、工具概览
task 命令的子命令全景用 task commands 查看，实测回显（节选，完整表含每个命令的类别/读写属性/说明列）：
Command Category R/W ID GC Recur Context Filter Mods Misc Description
_aliases internal RO Generates a list
of all aliases,
for
autocompletion
purposes
_columns internal RO Displays only a
list of
supported
columns
_commands internal RO Generates a list
of all commands,
for
命令按形态可归为五类（本文按此组织）：录入编辑（add/annotate/append/prepend/modify/duplicate）、状态流转（start/stop/done/delete/undo）、报表查询（list/next/long/completed/stats/filter…）、数据出入（export/import/sync）、内省辅助（commands/_show/diagnostics/calc/count）。裸敲 task 等价于执行 default.command 配置的报表（默认 next，本文环境实测配置为 list）。
三、前置条件
- 已按安装篇完成 3.5.0 安装且首跑初始化过
~/.taskrc； - 本文示例沿用安装篇 7.3 节迁移进来的任务（pay electricity bill、read taskwarrior docs），并新录入了演示任务；读者在自己环境执行时，ID 与回显数值会不同，输出结构应当一致。
四、任务录入与编辑命令详解
4.1 task add：属性修饰全形态
add 的描述后可直接跟属性修饰词（project:、+标签、priority:、due:、recur:、depends:、wait:），一次成单。实测四连：
task add review pull request project:devops +code priority:M due:2026-10-27
task add "weekly report" recur:weekly due:2026-10-26
task add blocked demo task depends:1 project:demo
实测回显：
Created task 5.
The project 'devops' has changed. Project 'devops' is 0% complete (1 task remaining).
Created task 6 (recurrence template).
Created task 7.
The project 'demo' has changed. Project 'demo' is 33% complete (2 of 3 tasks remaining).
逐项解读：普通任务回显 Created task <ID>.；带 recur: 的 add 会创建周期模板（回显明确标注 recurrence template），到期自动派生实例；depends:1 建立对任务 1 的依赖，被阻塞任务在报表中带 D 标记且紧急度倒扣（实测 Urg -4）。
4.2 task annotate / append / prepend：不改描述的三种补充
task annotate 1 called vendor about invoice
task append 1 and confirm meter reading
task prepend 7 prepare slides for
实测回显：
Annotating task 1 'pay electricity bill'.
Annotated 1 task.
Appending to task 1 'pay electricity bill and confirm meter reading'.
Appended 1 task.
Prepending to task 7 'prepare slides for weekly report'.
This is a recurring task. Do you want to prepend to all pending recurrences of this same task? (yes/no) Prepended 1 task.
逐项解读：annotate 追加带时间戳的注记（不修改描述本身，任务详情视图缩进展示）；append/prepend 分别在描述尾部/头部拼接；对周期任务操作时会询问「是否应用到全部未完成实例」。
4.3 task modify / duplicate：批量改属性与复制
task 5 modify priority:H project:devops
task 2 duplicate
实测回显：
Modifying task 5 'review pull request'.
Modified 1 task.
Project 'devops' is 0% complete (1 task remaining).
Duplicated task 2 'read taskwarrior docs'.
Created task 9.
Duplicated 1 task.
The project 'docs' has changed. Project 'docs' is 0% complete (2 of 2 tasks remaining).
解读：modify 可同时改多个属性（可批量 task 1-3 modify +work）；duplicate 复制任务生成新 ID，是模板化录入的常用手法。
4.4 单任务详情视图：task <ID>
task 1
实测回显（节选）：
Name Value
--------------------- ----------------------------------------------------------
ID 1
Description pay electricity bill and confirm meter reading
2026-10-24 10:18:24 called vendor about invoice
Status Pending
This task is blocking 6 blocked demo task
Entered 2026-10-24 10:04:21 (15min)
Due 2026-10-30 00:00:00
Last modified 2026-10-24 10:18:35 (1min)
Virtual tags ANNOTATED BLOCKING DUE MONTH PENDING QUARTER READY
UNBLOCKED YEAR
UUID 4b477eaf-8066-4745-8444-8bcf525e2a97
解读：详情视图展示全量属性与虚拟标签（ANNOTATED/BLOCKING/DUE 等系统自动判定标签，可直接用于过滤，如 task +BLOCKING list）；注记缩进挂在描述下方；长期引用任务建议用 UUID（ID 会被 GC 重编号，见第九章）。
五、任务状态流转命令详解
5.1 start / stop
task 1 start
task stop 1
实测回显：
Starting task 1 'pay electricity bill and confirm meter reading'.
Started 1 task.
You have more urgent tasks.
Stopping task 1 'pay electricity bill and confirm meter reading'.
Stopped 1 task.
解读：start 标记「进行中」（报表加 active 标记、虚拟标签 ACTIVE），stop 退回；You have more urgent tasks. 是 nag 配置的提醒（见配置篇 5.2 节），非错误。
5.2 done / delete（rm 别名）
task 4 done
task rm 5
实测回显：
Completed task 4 'silent task test'.
Completed 1 task.
You have more urgent tasks.
Delete task 5 'review pull request'? (yes/no) Task not deleted.
Deleted 0 tasks.
⚠️ 实测要点：done 直接触发完成；delete（别名 rm，见配置篇 5.9 节）必须交互确认，非交互环境下确认读不到输入时会回
Task not deleted.——脚本中批量删除要用rc.bulk=0 rc.confirmation=no类覆盖或rc.confirmation:off，并清楚自己在删什么。
5.3 undo：事务级回滚
echo yes | script -qec "task undo" /dev/null
实测回显（节选）：
The following 4 operations would be reverted:
Uuid Modification
6ef8ecc1-97c2-46f6-b1fd-0e5bd19b8c81 Update property
'modified' from
'1792836850' to
'1792837115'
Add property 'end'
with value
'1792837115'
Update property
'status' from
'pending' to
'completed'
The undo command is not reversible. Are you sure you want to revert to the previous state? (yes/no)
解读：undo 展示最近一次事务（本例为一次 done 产生的 end/modified/status 变更）并要求确认；确认即回滚该事务。⚠️ 提示语明确「undo 不可逆」——撤销后无法再撤销这次撤销。
六、报表与过滤查询命令详解
6.1 内建报表：list / next / long
task list
task next
task long
实测回显（list 全文）：
ID Age D P Project Tags R Due Description Urg
-- ----- - - ------- ----- - ---------- ----------------------------------- ----
8 - R 2026/10/26 weekly report 8.08
5 - M devops code 2026/10/27 review pull request 13.3
1 14min 2026/10/30 pay electricity bill and confirm 15.1
meter reading [1]
4 4min silent task test 0
3 5min H demo urgent top task 7
7 - D demo blocked demo task -4
2 14min docs learn read taskwarrior docs 1.8
7 tasks
Creating recurring task instance 'weekly report'
逐项解读：列含义 D=依赖被阻塞、P=优先级、R=周期；默认按 Urg（紧急度）降序；[1] 表示带 1 条注记；周期模板到期时自动派生实例（尾部 Creating recurring task instance 行）。next 聚焦「下一步可做」（实测表头含 Deps/Recur 列，隐藏已阻塞项排在合理位置）；long 展开更多列（Created/Mod/Deps 等）。
6.2 过滤表达式（查询 DSL）
过滤词可直接跟在任何报表后。逐类实测：
项目过滤 task project:demo list：
ID Age D P Project Description Urg
-- ----- - - ------- --------------------- ----
3 5min H demo urgent top task 7
6 12s D demo blocked demo task -4
2 tasks
标签过滤 task +code list：
ID Age P Project Tags Due Description Urg
-- ----- - ------- ---- ---------- ----------------------- ----
4 12s H devops code 2026/10/27 review pull request 15.4
1 task
优先级过滤 task priority:H list（实测命中 2 条：15.4 与 7 两行，表头同上）。
日期区间过滤 task due.before:2026-10-28 list：
ID Age P Project Tags R Due Description Urg
-- ----- - ------- ---- - ---------- ----------------------- ----
7 12s R 2026/10/26 weekly report 8.08
4 12s H devops code 2026/10/27 review pull request 15.4
2 tasks
全文检索 task /electricity/ list：
ID Age Due Description Urg
-- ----- ---------- -------------------------------------------------- ----
1 14min 2026/10/30 pay electricity bill and confirm meter reading [1] 15.1
1 task
语法要点（均为实测可用形态）：+tag 有标签 / -tag 无标签；project:X 支持 project.not:X；日期支持 due.before:/due.after: 及 today、eom、later 等代词；/词/ 为描述模糊检索；多个过滤词之间是 AND 语义，可用 or 连接组合。
6.3 专项报表：completed / waiting / recurring
task completed
task add future task wait:2026-10-25
task waiting
task recurring
实测回显（completed）：
ID UUID Created Completed Age Project Description
-- -------- ---------- ---------- ---- ------- -----------------
- 5e0d4426 2026/10/24 2026/10/24 5min demo low priority task
- 6ef8ecc1 2026/10/24 2026/10/24 4min silent task test
2 tasks
（waiting）：
ID Age Wait Remaining Description
-- --- ---------- --------- -----------
9 - 2026-10-25 13h future task
1 task
（recurring）：
ID Age Recur Due Description Urg
-- ---- ----- ---------- ------------- ----
5 1min P7D 2026/10/26 weekly report 8.08
1 task
解读：completed 报表中已完成任务 ID 列为 -（GC 后不占用编号，靠 UUID 标识）；wait: 任务在等待期不进主报表，专看 waiting；recurring 列出周期模板（Recur 列 P7D 即每 7 天）。⚠️ 实测教训：task status:completed list 返回 No matches.——list 报表内置 status:pending 过滤，与显式条件 AND 后为空；查看完成历史必须用 completed 报表（或自定义无内置过滤的报表，见配置篇 5.4 节）。
6.4 统计类：stats / count / summary / timesheet / projects / tags
task stats 实测回显（全文）：
Category Data
------------------------- -------------
Pending 7
Waiting 0
Recurring 1
Completed 2
Deleted 0
Total 10
Annotations 1
Unique tags 2
Projects 3
Blocked tasks 1
Blocking tasks 1
Undo transactions 16
Sync backlog transactions 107
Tasks tagged 30%
Oldest task 2026-10-24
Newest task 2026-10-24
Task used for 14min
task summary 实测回显（项目维度汇总）：
Project Remaining Avg age Complete 0% 100%
------- --------- ------- -------- ------------------------------
(none) 3 5min 0%
demo 2 2min 33% ==========
devops 1 54s 0%
docs 1 14min 0%
task projects 实测回显：
Project Tasks
------- -----
(none) 4
demo 2
devops 1
docs 1
3 projects (8 tasks)
task tags 实测回显：
Tag Count
code 1
learn 1
2 tags
(8 tasks)
task timesheet 实测回显（当日活动）：
Wk Date Day ID Action Project Due Task
W42 2026-10-24 Sat 5e0d4426 Completed demo low priority task
1 completed, 0 started.
另有 task count（只输出条数，实测 9）适合脚本取数；task calc 可做表达式求值（实测 task calc 2+2 → 4），过滤表达式中的算术也由同一求值器支持。
6.5 组合过滤实例
task project:demo priority:H list
实测命中 urgent top task 一行（结构同 6.2 各表，列头一致）。组合原则：过滤词依次 AND，or 显式改写，括号可用——复杂查询建议先 task <过滤词> count 验证数量再上报表。
七、数据导入导出与同步命令详解
7.1 task export / import
task export rc.verbose:nothing
实测回显（节选）：
[
{"id":0,"description":"low priority task","end":"20261024T101303Z","entry":"20261024T101302Z","modified":"20261024T101303Z","project":"demo","status":"completed","uuid":"5e0d4426-f910-4aab-8f0e-724252465cf9","urgency":1},
{"id":0,"description":"silent task test","end":"20261024T101835Z","entry":"20261024T101410Z","modified":"20261024T101835Z","status":"completed","uuid":"6ef8ecc1-97c2-46f6-b1fd-0e5bd19b8c81","urgency":0},
解读：export 输出全量 JSON 数组（已完成任务 id 为 0，主键是 uuid 字段）；可加过滤只导出子集（task project:demo export）。import 接受同格式 JSON（实测跨版本迁移场景见安装篇 7.3 节：2.6.2 导出 → 3.5.0 导入回显逐条 add <uuid> <描述> → Imported 2 tasks.）。
7.2 task sync：未配置服务端的实测基线
task sync
实测回显：
No sync.* settings are configured. See task-sync(5).
解读：3.5.0 的同步需要先在 .taskrc 配置 sync.server.url / sync.server.client_id / sync.encryption_secret 三要素（见配置篇 5.8 节）并部署 taskchampion-sync-server；未配置时 sync 直接给出上述提示，不会误发数据。task stats 中的 Sync backlog transactions 行实时反映本地待同步事务量（本文实测 107 条为未配置时的本地积压计数）。
八、辅助与内省命令详解
- task commands：全部子命令总表（含 internal 类
_前缀命令，见 2.1 节节选）； - task aliases：别名清单（internal 命令，脚本补全用）；
- task _show：
KEY=VALUE形式的全量配置输出（实测 245 行，脚本解析友好，详见配置篇 3.1 节）； - task diagnostics：安装体检（版本/编译特性/配置文件/数据目录/hooks，全文回显见安装篇 5.7 节）；
- task version：版本号（实测
3.5.0）； - task news：版本新特性导读（首跑样例配置中的
news.version=3.5.0即其游标，见配置篇 3.5 节）。
九、注意事项
- ID 会被 GC 重编号（实测）：本文实验过程中，
review pull request从 ID 5 变为 4、weekly report模板从 8 变为 5——gc=1（默认开启）会在完成任务后重排 ID。跨时刻引用任务一律用 UUID（task <uuid> done同样可用）； - rm/undo 均有交互确认，非交互环境不会生效或需显式覆盖（5.2/5.3 节实测）；
- 报表内置过滤：list/next 默认只含 status:pending，显式
status:completed与之 AND 会得到空结果（6.3 节实测）； - 周期任务操作会触发连带询问（4.2 节 prepend 实测），脚本化处理周期任务时注意确认开关；
- sync 未配置是安全空操作（7.2 节实测），不会静默外发数据；首次配置同步前先备份
~/.task/taskchampion.sqlite3。
十、常见问题（FAQ）
Q1：task list 里的 ID 和昨天对不上了？
GC 重编号所致（第九章第 1 条）。用 UUID 定位：task <uuid> <操作>；或临时 rc.gc=0 关闭回收再观察。
Q2：脚本里 task rm 5 没有删除？
确认提示读不到输入（5.2 节实测回显 Task not deleted.）。交互终端运行，或加 rc.confirmation:off（并自行承担误删风险）。
Q3：task status:completed list 为什么 No matches？
报表内置过滤叠加所致（6.3 节），改用 task completed 报表。
Q4：完成的周期任务没有立刻出现下一期？
实例按模板的 Recur 节奏（如 P7D）与 due 派生，且带 wait 语义的实例会先落在 waiting；用 task recurring 与 task waiting 核对（6.3 节实测形态）。
Q5：how to 只看某个项目下未完成且高优先级的任务？
组合过滤即可（6.5 节实测）：task project:demo priority:H list；再加 due.before:eom 等日期词可继续收窄。
十一、参考链接
- 官方文档（命令参考）：https://docs.taskwarrior.org/
- man 手册：
man task（/usr/local/share/man/man1/task.1，随 3.5.0 安装分发）、man task-sync（同步配置） - 内建命令总表：
task commands（2.1 节） - 安装指南：《Taskwarrior 3.5.0 安装指南（发行版包与源码构建双线实测）》
- 配置参数详解：《Taskwarrior 3.5.0 配置参数详解（.taskrc 逐项实测）》
- 介绍与选型指南：《Taskwarrior 3.5.0 介绍与选型指南》