duvo-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Duvo CLI

duvo

is the official command-line interface for the Duvo public API. It is published to npm as

@duvoai/cli

: a single binary with resource-grouped subcommands (

duvo agents …

duvo runs …

duvo cases …

, …) and a low-level

duvo api <method> <path>

escape hatch for endpoints that don't yet have a dedicated command.

Use the CLI when the user wants to automate or script Duvo. The web UI at https://app.duvo.ai is the right answer when they want to click around interactively;

duvo

is the right answer the moment they ask for a shell snippet, a cron job, a CI step, or "how do I do X without opening the browser?". Both surfaces talk to the same public API — there is no functional gap to bridge by reaching for

curl

duvo

是Duvo公共API的官方命令行界面，以

@duvoai/cli

的名义发布在npm上：它是一个单一二进制文件，包含按资源分组的子命令（

duvo agents …

、

duvo runs …

、

duvo cases …

等），还提供了底层的

duvo api <method> <path>

兜底方案，用于调用尚未有专属命令的端点。

当用户希望自动化或脚本化操作Duvo时，可使用该CLI。如果用户想要交互式点击操作，https://app.duvo.ai网页UI是合适的选择；而当用户需要Shell代码片段、定时任务、CI步骤，或者询问“如何不用打开浏览器完成X操作？”时，

duvo

就是正确的选择。两种方式调用的是同一个公共API——无需使用

curl

来弥补功能缺口。

Install

安装

bash

npm install -g @duvoai/cli
duvo --version

Requires Node.js ≥ 22.22.0.

npx @duvoai/cli <cmd>

also works without a global install.

bash

npm install -g @duvoai/cli
duvo --version

需要Node.js ≥ 22.22.0。无需全局安装时，也可使用

npx @duvoai/cli <cmd>

。

Authentication

认证

duvo

keeps credentials as named profiles on disk. One profile per (team, environment). The first profile added becomes the default; from then on, every command uses the default unless overridden.

bash

duvo login                       # OAuth flow — opens your browser
duvo login --name acme           # name the profile up front
duvo login --api-key <key>       # skip OAuth and store an API key directly
duvo whoami                      # confirm who's signed in

duvo login

defaults to browser-based OAuth against the Duvo production tenant. Pass

--api-key <key>

to store a long-lived API key instead (grab one from https://app.duvo.ai/settings/api-keys).

Switching between profiles:

bash

duvo profiles list               # show all profiles; `▶` marks the default
duvo profiles use                # interactively pick the default profile
duvo profiles use acme           # set a named profile as the default
duvo --profile acme whoami       # one-off override for a single command

Resolution precedence (the first match wins):

Profile:

--profile <name>

flag →

DUVO_PROFILE

env →

defaultProfile

in config.

Credential:
```
DUVO_API_KEY
```
env (bypasses the profile's stored credential lookup) → the profile's stored credential.

Base URL:

DUVO_API_BASE_URL

env → the profile's

apiBaseUrl

→

https://api.duvo.ai

duvo

会在磁盘上保存命名配置文件作为凭证。每个（团队、环境）对应一个配置文件。添加的第一个配置文件会成为默认配置；此后，所有命令都会使用默认配置，除非被覆盖。

bash

duvo login                       # OAuth流程——打开浏览器
duvo login --name acme           # 提前指定配置文件名称
duvo login --api-key <key>       # 跳过OAuth，直接存储API密钥
duvo whoami                      # 确认当前登录身份

duvo login

默认针对Duvo生产租户使用基于浏览器的OAuth。若要存储长期API密钥，可传递

--api-key <key>

参数（可从https://app.duvo.ai/settings/api-keys获取）。

切换配置文件：

bash

duvo profiles list               # 显示所有配置文件；`▶`标记默认配置
duvo profiles use                # 交互式选择默认配置文件
duvo profiles use acme           # 将指定名称的配置文件设为默认
duvo --profile acme whoami       # 单次命令临时覆盖默认配置文件

优先级顺序（匹配到的第一个生效）：

配置文件：
```
--profile <name>
```
标志 →
```
DUVO_PROFILE
```
环境变量 → 配置中的
```
defaultProfile
```
。
凭证：
```
DUVO_API_KEY
```
环境变量（绕过配置文件存储的凭证查找）→ 配置文件存储的凭证。
基础URL：
```
DUVO_API_BASE_URL
```
环境变量 → 配置文件的
```
apiBaseUrl
```
→
```
https://api.duvo.ai
```
。

Reading the help

查看帮助

Every command supports

--help

. Reach for it first instead of guessing:

bash

duvo --help                      # global help, lists every top-level group
duvo agents --help               # subcommand group
duvo agents create --help        # exact flags for one command

The CLI's help text is the source of truth — if a flag doesn't appear there, it doesn't exist in your installed version. Always show the user

duvo <command> --help

rather than copy-pasting flags from memory if you're unsure.

每个命令都支持

--help

参数。遇到疑问时请先使用该参数，而非猜测：

bash

duvo --help                      # 全局帮助，列出所有顶级命令组
duvo agents --help               # 子命令组帮助
duvo agents create --help        # 单个命令的具体标志说明

CLI的帮助文本是权威来源——如果某个标志未出现在帮助中，则说明你安装的版本不支持该标志。如果不确定，务必让用户查看

duvo <command> --help

，而非凭记忆复制粘贴标志。

Output modes

输出模式

Each command picks a default output shape based on what it returns:

Single resource (
```
duvo agents get <id>
```
,
```
duvo runs get <id>
```
) → human-readable key/value text.
Collection (
```
duvo agents list
```
,
```
duvo runs list
```
) → table with a fixed column set per resource.
--json
on either of the above → raw JSON to stdout. This is the stable contract for scripts — table and text formats can change between versions, JSON is safe to pipe into
```
jq
```
or
```
yq
```
.

bash

duvo agents list --json | jq '.agents[].id'

For scripting, always pass

--json

and parse the response. Don't parse the table output — column widths and truncation thresholds are not part of the public contract. Envelope keys differ across endpoints —

agents list

returns

.agents[]

queues list

returns

.queues[]

runs list

returns

.data[]

agents create

returns

.agent.id

. Inspect the shape with a one-off

--json

call before hard-coding a jq path.

每个命令会根据返回内容选择默认输出格式：

单一资源（
```
duvo agents get <id>
```
、
```
duvo runs get <id>
```
）→ 人类可读的键值文本。
资源集合（
```
duvo agents list
```
、
```
duvo runs list
```
）→ 按资源类型固定列的表格。
在上述两种命令后添加
```
--json
```
→ 向标准输出返回原始JSON。这是脚本使用的稳定约定——表格和文本格式可能在版本间变化，而JSON可安全地通过管道传递给
```
jq
```
或
```
yq
```
处理。

bash

duvo agents list --json | jq '.agents[].id'

编写脚本时，请始终传递

--json

参数并解析响应。不要解析表格输出——列宽和截断阈值不属于公开约定。不同端点的响应结构不同——

agents list

.agents[]

，

queues list

.queues[]

，

runs list

.data[]

，

agents create

.agent.id

。在硬编码jq路径前，请先通过单次

--json

调用检查响应结构。

The

duvo api

escape hatch

duvo api

兜底方案

Any endpoint in the public API is reachable via

duvo api <METHOD> <path>

, modelled directly on

gh api

. Reach for it when:

A new public endpoint shipped but doesn't have a dedicated
```
duvo
```
command yet.
You need a very narrow query-string or body shape that the high-level command doesn't expose.
You're debugging —
```
duvo api
```
shows exactly what the API returned, with no formatting in the way.

bash

duvo api GET /v1/agents -F limit=20 -F offset=0
duvo api POST /v1/agents -f name="Ops bot" -F build[name]="v1"
duvo api POST /v1/agents --input body.json
cat body.json | duvo api POST /v1/agents --input -

-f

sends the value as a string;

-F

parses it as a typed value (boolean, number, JSON

null

, or

@file

to load JSON from disk). See

references/api-escape-hatch.md

for the full flag table.

High-level commands like

duvo agents create

are sugar over

duvo api

— they share the same HTTP client, output pipeline, and exit codes, so a script can mix the two freely.

公共API中的任意端点都可通过

duvo api <METHOD> <path>

调用，该命令模仿

gh api

实现。在以下场景中可使用该命令：

新的公共端点已发布，但尚未有对应的
```
duvo
```
专属命令。
需要使用高级命令未暴露的特定查询字符串或请求体结构。
调试时——
```
duvo api
```
会显示API返回的原始内容，无任何格式干扰。

bash

duvo api GET /v1/agents -F limit=20 -F offset=0
duvo api POST /v1/agents -f name="Ops bot" -F build[name]="v1"
duvo api POST /v1/agents --input body.json
cat body.json | duvo api POST /v1/agents --input -

-f

将值作为字符串发送；

-F

将其解析为类型化值（布尔值、数字、JSON

null

，或

@file

从磁盘加载JSON）。完整标志表请参考

references/api-escape-hatch.md

。

duvo agents create

等高级命令是

duvo api

的语法糖——它们共享相同的HTTP客户端、输出管道和退出码，因此脚本可以自由混合使用两种命令。

Resource groups

资源组

See

references/commands.md

for the full command tree with flags. The top-level groups are:

Auth & profiles —
```
login
```
,
```
logout
```
,
```
whoami
```
,
```
profiles …
```

Agents —

agents …

agents case-triggers …

agents schedules

Agent folders —
```
agent-folders …
```
(organize agents in a tree)
Revisions —
```
revisions …
```
,
```
revision-integrations …
```
(versioned configs)
Runs —
```
runs …
```
(start, get, message, stop, respond to HITL)
Queues & cases —
```
queues …
```
,
```
queue-labels …
```
,
```
cases …
```
Files & sandboxes —
```
files …
```
,
```
sandboxes …
```

Connections & integrations —

integrations …

connections …

oauth …

Clarity —
```
clarity …
```
(read-only process search, versions, captures, gaps, evidence, facets, export, doctor)
Skills & plugins —
```
skills …
```
,
```
plugins …
```
Team —
```
team get
```
,
```
team members
```
Low-level —
```
api <method> <path>
```

For end-to-end recipes (create an agent → start a run → respond to HITL; manage a queue and its cases; upload files for a sandboxed run; authorize a custom MCP server) see

references/workflows.md

完整命令树及标志请参考

references/commands.md

。顶级命令组包括：

认证与配置文件 ——
```
login
```
、
```
logout
```
、
```
whoami
```
、
```
profiles …
```

Agent ——

agents …

、

agents case-triggers …

、

agents schedules

Agent文件夹 ——
```
agent-folders …
```
（以树形结构组织Agent）
版本修订 ——
```
revisions …
```
、
```
revision-integrations …
```
（版本化配置）
运行任务 ——
```
runs …
```
（启动、获取、发送消息、停止、响应HITL）
队列与案例 ——
```
queues …
```
、
```
queue-labels …
```
、
```
cases …
```
文件与沙箱 ——
```
files …
```
、
```
sandboxes …
```

连接与集成 ——

integrations …

、

connections …

、

oauth …

Clarity ——
```
clarity …
```
（只读流程搜索、版本、捕获、缺口、证据、维度、导出、诊断）
Skill与插件 ——
```
skills …
```
、
```
plugins …
```
团队 ——
```
team get
```
、
```
team members
```
底层命令 ——
```
api <method> <path>
```

端到端使用示例（创建Agent → 启动运行任务 → 响应HITL；管理队列及案例；为沙箱运行任务上传文件；授权自定义MCP服务器）请参考

references/workflows.md

。

Conventions you can rely on across commands

全命令通用约定

These hold for every command group, so call them out when explaining the CLI rather than restating per-command:

```
--profile <name>
```
is a global flag that overrides the default profile for that single invocation.
```
--json
```
is available on every command that hits the API and is the shape to use in scripts.
Destructive operations (
```
duvo logout
```
,
```
duvo profiles remove
```
,
```
duvo runs stop
```
,
```
duvo agent-folders delete
```
,
```
duvo cases delete
```
,
```
duvo cases clear
```
,
```
duvo cases bulk-delete
```
,
```
duvo skills delete
```
,
```
duvo queues delete
```
, …) prompt for confirmation in a TTY and refuse on a non-TTY stdin. Pass
```
-y
```
/
```
--yes
```
to skip the prompt — never pipe
```
yes
```
into the CLI to bypass the prompt; it explicitly refuses inferred consent from piped input.
Exit codes:
```
0
```
success,
```
1
```
generic error,
```
2
```
auth error (missing or invalid key, unknown profile),
```
3
```
not found. Useful for CI scripts that want to branch on the failure mode.

IDs are printed bare (no quotes) so they copy cleanly into shell pipelines and

$()

substitutions:

bash

agent=$(duvo agents create --name "Ops bot" --input "What to do" --json | jq -r .agent.id)
duvo runs start --agent "$agent"

Deprecation warnings print to stderr (so they don't corrupt
```
--json
```
stdout) and can't be silenced. If a user reports an unexpected warning, check whether their
```
@duvoai/cli
```
version is behind.

以下约定适用于所有命令组，解释CLI时可统一说明，无需逐个命令重复：

```
--profile <name>
```
是全局标志，可临时覆盖单次调用的默认配置文件。
所有调用API的命令都支持
```
--json
```
参数，这是脚本应使用的格式。
破坏性操作（
```
duvo logout
```
、
```
duvo profiles remove
```
、
```
duvo runs stop
```
、
```
duvo agent-folders delete
```
、
```
duvo cases delete
```
、
```
duvo cases clear
```
、
```
duvo cases bulk-delete
```
、
```
duvo skills delete
```
、
```
duvo queues delete
```
等）在TTY环境中会提示确认，在非TTY标准输入环境中会拒绝执行。传递
```
-y
```
/
```
--yes
```
参数可跳过提示——请勿通过管道传递
```
yes
```
命令绕过提示；CLI明确拒绝通过管道输入推断的同意。
退出码：
```
0
```
表示成功，
```
1
```
表示通用错误，
```
2
```
表示认证错误（缺失或无效密钥、未知配置文件），
```
3
```
表示资源未找到。这对需要根据失败模式分支处理的CI脚本很有用。

ID会以无引号的形式打印，以便干净地复制到Shell管道和

$()

替换中：

bash

agent=$(duvo agents create --name "Ops bot" --input "What to do" --json | jq -r .agent.id)
duvo runs start --agent "$agent"

弃用警告会打印到标准错误输出（避免破坏
```
--json
```
的标准输出），且无法关闭。如果用户报告意外警告，请检查其
```
@duvoai/cli
```
版本是否过时。

Pitfalls and gotchas

陷阱与注意事项

Profile vs credential.
```
--profile foo
```
changes which profile is read;
```
DUVO_API_KEY=…
```
overrides the credential but still uses the selected profile's
```
apiBaseUrl
```
. To target a totally different environment, set both
```
DUVO_API_KEY
```
and
```
DUVO_API_BASE_URL
```
.
profiles use
with no argument opens an interactive picker that only works in a TTY. In CI, always pass a name explicitly.
agents create
is interactive by default. When
```
--name
```
and
```
--input
```
are omitted and stdin is a TTY, the CLI prompts. In CI, pass both flags (and
```
--no-build
```
if you don't want an initial build) so it never blocks waiting for input.
cases create --from-file -
reads JSON from stdin. The file (or stdin) is a single case object or an array of up to 100 cases. Each case is
```
{ "title": "…", "data": "…", "labels": [{ "key": "…", "value": "…" }] }
```
. Labels with no
```
key
```
are tag-only labels.
Sandbox files vs team files.
```
duvo files …
```
manages persistent team files (visible in the Files surface in the UI);
```
duvo sandboxes …
```
stages files for a single run (
```
duvo runs start --sandbox-id <id>
```
). Don't mix them.
Connections vs integrations.
```
duvo integrations list
```
shows the team's catalog of integration types;
```
duvo connections list
```
shows the user's actual connected accounts (one per OAuth/credential flow). OAuth-based connections (Gmail, Slack, …) are started by
```
duvo oauth native start <provider>
```
or
```
duvo oauth composio start …
```
, not by
```
duvo connections create
```
— the latter is only for user-provided MCP servers.
Clarity is read-only in this CLI surface. Start with
```
duvo clarity overview <process-id>
```
, then use
```
versions
```
,
```
current
```
,
```
proposal
```
,
```
compare
```
,
```
gaps
```
,
```
evidence
```
,
```
readiness
```
, or
```
facets
```
as needed. Those v2-only commands require a Clarity v2 process; legacy v1 processes support only
```
overview
```
,
```
status
```
,
```
captures
```
,
```
capture
```
, and
```
export
```
. Default output is compact; transcripts and media URLs are included only when a JSON command explicitly passes
```
--include-transcripts
```
.

配置文件 vs 凭证。
```
--profile foo
```
会更改读取的配置文件；
```
DUVO_API_KEY=…
```
会覆盖凭证，但仍会使用所选配置文件的
```
apiBaseUrl
```
。若要完全切换到不同环境，请同时设置
```
DUVO_API_KEY
```
和
```
DUVO_API_BASE_URL
```
。
**不带参数的
```
profiles use
```
**会打开交互式选择器，仅在TTY环境中可用。在CI环境中，请始终显式传递配置文件名称。
agents create
默认是交互式的。当省略
```
--name
```
和
```
--input
```
且标准输入为TTY时，CLI会提示输入。在CI环境中，请同时传递这两个标志（如果不需要初始构建，可添加
```
--no-build
```
），避免命令因等待输入而阻塞。
**
```
cases create --from-file -
```
**从标准输入读取JSON。文件（或标准输入）内容可以是单个案例对象，或最多100个案例的数组。每个案例的结构为
```
{ "title": "…", "data": "…", "labels": [{ "key": "…", "value": "…" }] }
```
。没有
```
key
```
的标签是仅标签类型。
沙箱文件 vs 团队文件。
```
duvo files …
```
管理持久化的团队文件（在UI的文件界面可见）；
```
duvo sandboxes …
```
为单次运行任务暂存文件（
```
duvo runs start --sandbox-id <id>
```
）。请勿混淆两者。
连接 vs 集成。
```
duvo integrations list
```
显示团队的集成类型目录；
```
duvo connections list
```
显示用户实际连接的账户（每个OAuth/凭证流程对应一个）。基于OAuth的连接（Gmail、Slack等）需通过
```
duvo oauth native start <provider>
```
或
```
duvo oauth composio start …
```
启动，而非
```
duvo connections create
```
——后者仅适用于用户提供的MCP服务器。
Clarity在该CLI界面中是只读的。从
```
duvo clarity overview <process-id>
```
开始，根据需要使用
```
versions
```
、
```
current
```
、
```
proposal
```
、
```
compare
```
、
```
gaps
```
、
```
evidence
```
、
```
readiness
```
或
```
facets
```
命令。这些仅支持v2版本的命令需要Clarity v2流程；旧版v1流程仅支持
```
overview
```
、
```
status
```
、
```
captures
```
、
```
capture
```
和
```
export
```
。默认输出为精简格式；仅当JSON命令显式传递
```
--include-transcripts
```
时，才会包含转录内容和媒体URL。

When the CLI is the wrong tool

不适合使用CLI的场景

Steer users to a different surface in these cases:

They want to read a stream of run events as they happen. The CLI's
```
runs get
```
/
```
runs messages
```
are point-in-time reads. Use
```
--webhook-url
```
on
```
runs start
```
to receive events asynchronously, or open the run in the web UI.
They want to edit an SOP or agent configuration interactively.
```
revisions create
```
and
```
revisions update
```
accept a config file, but composing the config by hand is painful. Direct them to the Assignment editor in the web UI for anything beyond a small targeted patch.
They want to run an agent in their own process rather than on Duvo. That's not what the public API exposes; the CLI is a client to the hosted Duvo platform.

在以下场景中，请引导用户使用其他方式：

用户希望实时查看运行任务的事件流。CLI的
```
runs get
```
/
```
runs messages
```
是时点读取。可在
```
runs start
```
时使用
```
--webhook-url
```
参数异步接收事件，或在网页UI中打开运行任务查看。
用户希望交互式编辑SOP或Agent配置。
```
revisions create
```
和
```
revisions update
```
接受配置文件，但手动编写配置非常繁琐。对于除小范围针对性修改外的操作，请引导用户使用网页UI中的任务编辑器。
用户希望在自己的进程中运行Agent，而非在Duvo平台上。这不是公共API提供的功能；CLI是托管Duvo平台的客户端。

In-skill references

技能内参考

```
references/commands.md
```
— full command tree with flags, grouped by resource. Use this when you need the exact flag a command expects.
```
references/workflows.md
```
— end-to-end recipes (create an agent and start a run; queue + cases lifecycle; sandboxed runs with uploaded files; authorize a custom MCP server).
```
references/api-escape-hatch.md
```
—
```
duvo api
```
flag reference, with worked examples of
```
-f
```
vs
```
-F
```
,
```
@file
```
typed fields, and
```
--input
```
for raw JSON bodies.

When in doubt, run

duvo <command> --help

— the installed binary is the final source of truth.

```
references/commands.md
```
—— 按资源分组的完整命令树及标志。当需要命令所需的具体标志时，请参考该文档。
```
references/workflows.md
```
—— 端到端使用示例（创建Agent并启动运行任务；队列+案例生命周期；带上传文件的沙箱运行任务；授权自定义MCP服务器）。
```
references/api-escape-hatch.md
```
——
```
duvo api
```
标志参考，包含
```
-f
```
与
```
-F
```
、
```
@file
```
类型字段、
```
--input
```
用于原始JSON请求体的示例。

如有疑问，请运行

duvo <command> --help

——已安装的二进制文件是最终权威来源。

Resources

资源

Duvo — product website
Duvo documentation — concepts, building Assignments, Connections
Duvo API reference — every endpoint the CLI wraps
```
@duvoai/cli
```
on npm
— versions, install instructions, changelog
Web app — interactive surface for everything the CLI scripts
API keys — issue and revoke API keys for
```
duvo login --api-key
```
Public skill repository — the MIT-licensed community release of this skill, packaged for installation in third-party Claude Code setups

Duvo —— 产品官网
Duvo文档 —— 概念、任务分配构建、连接方式
Duvo API参考 —— CLI封装的所有端点
```
@duvoai/cli
```
on npm
—— 版本、安装说明、变更日志
Web应用 —— CLI可脚本化操作的所有功能的交互式界面
API密钥 —— 为
```
duvo login --api-key
```
生成和撤销API密钥
公共Skill仓库 —— 该技能的MIT许可社区版本，打包用于第三方Claude Code环境安装

duvo-cli

Original

Translation

Duvo CLI

Duvo CLI

Install

安装

Authentication

认证

Reading the help

查看帮助

Output modes

输出模式

The
`duvo api`
escape hatch

`duvo api`
兜底方案

Resource groups

资源组

Conventions you can rely on across commands

全命令通用约定

Pitfalls and gotchas

陷阱与注意事项

When the CLI is the wrong tool

不适合使用CLI的场景

In-skill references

技能内参考

See also

相关工具

Resources

资源

duvo-cli

Original

Translation

Duvo CLI

Duvo CLI

Install

安装

Authentication

认证

Reading the help

查看帮助

Output modes

输出模式

The duvo api escape hatch

duvo api兜底方案

Resource groups

资源组

Conventions you can rely on across commands

全命令通用约定

Pitfalls and gotchas

陷阱与注意事项

When the CLI is the wrong tool

不适合使用CLI的场景

In-skill references

技能内参考

See also

相关工具

Resources

资源

The
`duvo api`
escape hatch

`duvo api`
兜底方案