命令总览与通用参数

按操作查命令

cdg dag 下的命令以工作流为操作对象，cdg task 下的命令以某个工作流中的任务为操作对象，其余几个根命令负责初始化项目、查看队列、释放分支名、管理插件和账号。

暂停、中断与恢复各自适合什么情况，见干预与控制；几个审核动作之间怎么选，见按你的判断选择动作。

cdg 与 codedag 是同一个命令行工具的两个名字，文档中一律写作 cdg。在任何命令后加 --help 都能看到它的完整参数，例如 cdg task pause --help。

也可以用 cdg help <命令...>：把命令名逐级写出，就能定位到任意一层子命令，例如 cdg help dag review clear。dag、task、dag review、task review、plugin、branch、auth 这几个命令组下也各有 help，所以 cdg dag help review clear 输出的是同一份帮助。写出的名字在那一级下不存在时，例如 cdg help dag foo，命令把已经定位到的那一级帮助输出到 stderr，退出状态为 1。

指定工作流

命令中的工作流可以写成名字，也可以写成路径，但不论哪种写法，最终都必须指向主仓库 .codedag/dags/ 目录（含其子目录）中的一个 .yaml、.yml 或 .json 文件；指向其他位置或其他扩展名的文件，命令会拒绝执行。日常直接写名字最省事，例如 .codedag/dags/feature.yaml 写作 feature。

名字和以 .codedag/dags/ 开头的路径总是从主仓库解析，所以在主仓库、任一已登记的副本工作区，以及它们的任意子目录中执行，效果都相同。其他含有 / 的相对写法，包括以 ./、../ 开头的，都按当前目录解析。因此在主仓库根目录写 team/feature 会被拒绝，子目录中的工作流要写成 .codedag/dags/team/feature；在副本工作区中，./.codedag/dags/feature.yaml 这样的相对路径指向的是副本自己的目录，同样会被拒绝，这时改用名字或以 .codedag/dags/ 开头的写法即可。

不论用哪种写法，命令本身都要在项目内执行，也就是主仓库或某个已登记的工作区之内；在项目之外，即使写了正确的绝对路径，命令也找不到所属的项目。

同一目录下只有扩展名不同的两个文件，例如 feature.yaml 与 feature.yml，共用同一个日志文件和同一套分支名，不适合用来放两个不同的工作流，见文件位置与格式。

位置参数与 -w

cdg dag 下的命令把工作流写成位置参数，cdg task 下的命令把位置参数留给任务 ID，工作流改用 -w 指定。-w、--workflow-file 与 --dag 是同一个选项的三种写法，取值规则与上表相同。

cdg dag status feature
cdg task status 2 -w feature

有三个命令两种方式都接受：cdg dag status 与 cdg dag logs 既可以用位置参数，也可以用 -w；cdg task ls 的位置参数本身就是工作流，同样接受 -w。它们每次只操作一个工作流，位置参数、-w 与 --dag 只能给出一种，同时给出两种以上时命令报错、不输出状态或日志，即使这些写法指向的是同一个工作流。

cdg dag 下的校验、提交、控制与审核命令可以一次写多个工作流，用空格分隔，例如 cdg dag validate feature docs。一条 cdg task 命令则只操作一个工作流中的任务。

省略工作流时，多数命令作用于队首工作流，也就是排在队列最前面的那一个，同一时刻只有它在执行；cdg dag validate、cdg dag submit 与 cdg dag review clear 则必须写明工作流。每个命令能否省略、省略时指向哪个工作流，以对应的命令页为准。队列中有多个工作流时，队首不一定是你最近提交的那个，所以在脚本中或让 Agent 调用命令时，写明工作流更稳妥。

指定一个或多个任务

任务命令用工作流文件中 tasks[].id 的值指定任务（见 id）。它是一个正整数，与任务标题以及任务在列表中的位置都无关。同一个 ID 在不同工作流中指的是不同任务，所以命令中还要用 -w 指明工作流，省略时为队首工作流。

多个 ID 用空格分隔，例如 cdg task status 2 3 -w feature。只有由数字组成、数值不小于 1 的写法合法；2,3、1.5、+2、2abc、0 这类写法都会让命令报 Invalid task ID，以退出状态 1 结束，不做任何事。一条命令里有多个 ID 时，其中一个写错，整条命令就报错，写对的那几个也不会被处理。

各任务命令接受的任务数量不同。除 cdg task ls 外，它们都没有默认任务：省略任务时命令会报错，而不会作用于全部任务。

任务选择器

任务选择器按依赖关系一次选中一组任务，省去逐个列出 ID。下面用一个有五个任务的工作流 feature 说明各选择器选中哪些任务：任务 2、3 都依赖任务 1，任务 4 依赖任务 2 和 3，任务 5 依赖任务 4。

flowchart LR  t1["1 写接口契约"] --> t2["2 实现接口"]  t1 --> t3["3 编写测试"]  t2 --> t4["4 运行测试并修复"]  t3 --> t4  t4 --> t5["5 更新文档"]

上游与下游沿 dependencies 逐级追溯，间接依赖也算在内：任务 5 经由任务 4 间接依赖任务 2，所以 --below 2 包含任务 5。与指定任务并列、彼此没有依赖关系的任务不算上下游，所以 --through 2 不包含任务 3。

写在命令后面的任务 ID 就是 --only 的简写，因此 cdg task pause 2 3 与 cdg task pause --only 2 3 相同。直接写出的 ID 不能再与任何选择器同时使用，包括 --only 本身。

一个选择器能跟几个 ID，取决于命令。在任务的暂停、继续、中断与恢复命令中，每个选择器都可以跟多个 ID，结果取并集，例如 --upto 2 3 选中 1、2、3；在任务的审核命令中，包括 cdg task review clear，除 --only 外的选择器每个只接受一个 ID。

需要圈出中间的一段任务时，可以组合两个选择器取交集：一个取自 --downfrom 或 --below，另一个取自 --upto 或 --above。其他组合，例如 --only 搭配 --upto，或同时使用三个选择器，命令都会报错而不执行。

# 从任务 2 往下、到任务 4 为止：选中 2、4
cdg task pause --downfrom 2 --upto 4 -w feature
# 任务 1 与任务 5 之间的一段：选中 2、3、4
cdg task pause --below 1 --above 5 -w feature

选择器只根据依赖关系圈定任务，不看它们当前处于什么状态。圈中的任务能否执行这个动作，仍由各命令按自己的前提逐个判断，例如 cdg task pause 会跳过已经审核结束的任务。各命令的具体前提见控制命令语法与适用状态与审核。

常用批量操作

下面的命令沿用 feature 工作流：任务 2、3 依赖任务 1，任务 4 依赖任务 2 和 3，任务 5 依赖任务 4。最后一例另外用到工作流 docs。

批量控制的其余写法见指定范围与批量控制，批量审核时各动作的选项与默认值见审核。