dagger 0.21.10 常用 CLI 命令与工具详解
dagger CLI v0.21.10 全量子命令实测详解(2026-10-19 Ubuntu 22.04 实测):version/init/develop/config/functions/install/call/query/core/run 逐命令真实回显,全局参数默认值速查、引擎容器生命周期管理与排障 FAQ。
dagger 0.21.10 常用 CLI 命令与工具详解
目标:逐个实测 dagger CLI(v0.21.10)的全部核心子命令与常用全局参数,命令即实测命令、回显即实测回显(2026-10-19 于 Ubuntu 22.04.4 实测采集),供日常操作与排障速查。引擎相关容器表述属 dagger 组件本职用法。
一、环境信息
- 操作系统:Ubuntu 22.04.4 LTS(x86_64),内核 6.8.0-138-generic
- CLI 版本(实测回显):
dagger version
dagger v0.21.10 (image://registry.dagger.io/engine:v0.21.10) linux/amd64
- CLI 安装位置:
/root/.local/bin/dagger(安装过程见《Ubuntu 22.04 安装 dagger 0.21.10 指南》) - 引擎实例:
dagger-engine-v0.21.10(CLI 首次执行任务时自动创建,与 CLI 版本一一对应) - 实测模块目录:
/opt/workspace/dagger-demo(demo 模块,Python SDK,含 hello/build/report 三个函数)
二、工具概览
dagger CLI 是引擎的统一入口:所有子命令最终都被翻译为对引擎 GraphQL API 的调用。全局帮助(实测回显,dagger --help):
A tool to run composable workflows in containers
USAGE
dagger [options] [subcommand | file...]
DAGGER CLOUD COMMANDS
login Log in to Dagger Cloud
logout Log out from Dagger Cloud
DAGGER MODULE COMMANDS
call Call one or more functions, interconnected into a pipeline
config Get or set module configuration
core Call a core function
develop Prepare a local module for development
functions List available functions
init Initialize a new module
install Install a dependency
uninstall Uninstall a dependency
update Update a module's dependencies
EXECUTION COMMANDS
query Send API queries to a dagger engine
run Run a command in a Dagger session
ADDITIONAL COMMANDS
completion Generate the autocompletion script for the specified shell
help Help about any command
lock Manage workspace lockfiles
toolchain Manage toolchains
version Print dagger version
OPTIONS
--allow-llm strings List of URLs of remote modules
allowed to access LLM APIs, or 'all'
to bypass restrictions for the
entire session
-y, --auto-apply Automatically apply changes when a
changeset is returned
-c, --command string Execute a dagger shell command
-d, --debug Show debug logs and full verbosity
--eager-runtime load module runtime eagerly
-i, --interactive Spawn a terminal on container exec
failure
--interactive-command string Change the default command for
interactive mode (default "/bin/sh")
--lock string Lock lookup mode (disabled, live,
pinned, frozen). Defaults to disabled.
-m, --mod string Module reference to load, either a
local path or a remote git repo
(defaults to current directory)
--model string LLM model to use (e.g.,
'claude-sonnet-4-5', 'gpt-4.1')
-E, --no-exit Leave the TUI running after completion
-M, --no-mod Don't automatically load a module
(mutually exclusive with --mod)
--progress string Progress output format (auto, plain,
tty, dots, logs) (default "auto")
-q, --quiet count Reduce verbosity (show progress, but
clean up at the end)
-s, --silent Do not show progress at all
-v, --verbose count Increase verbosity (use -vv or -vvv
for more)
-w, --web Open trace URL in a web browser
--x-release string Run an experimental release from a
Dagger git ref
Use "dagger [command] --help" for more information about a command.
命令分组速读:
| 分组 | 命令 | 用途 |
|---|---|---|
| Cloud | login / logout | 登录/退出 Dagger Cloud(可选云服务,本地功能不依赖) |
| 模块 | init / develop / config / functions / install / uninstall / update / call / core | 模块初始化、SDK 接入、依赖管理与函数调用 |
| 执行 | query / run | 直接发 GraphQL 查询;包裹任意进程注入会话 |
| 附加 | completion / help / lock / toolchain / version | 补全、帮助、实验性工作区锁与工具链、版本 |
⚠️ 注意:全局选项(如
-s、-m、--progress)必须写在子命令之前(dagger -s query ...);写在子命令后会被当作该子命令的未知参数(实测报错样本见 6.4)。
三、前置条件
- 已按《Ubuntu 22.04 安装 dagger 0.21.10 指南》完成 CLI 安装并验证
dagger version; - 容器运行时可用(引擎按需拉起,实例名
dagger-engine-v0.21.10); - 受限网络下引擎实例已配置代理(引擎拉镜像走自身网络栈,配置方法见 B1 篇 FAQ);
- 有一个模块目录用于实验(本文用 demo 模块:
dagger init --name demo+dagger develop --sdk=python)。
四、版本与 Cloud 类命令
4.1 dagger version(版本查询与更新检查)
dagger version
dagger v0.21.10 (image://registry.dagger.io/engine:v0.21.10) linux/amd64
回显三段信息:CLI 版本、内嵌引擎镜像地址(image://registry.dagger.io/engine:v0.21.10)、平台架构。带 --check 可同时检查新版本(需访问版本服务,受限网络单独设代理,实测命令):
https_proxy=http://192.168.1.62:7897 dagger version --check
dagger v0.21.10 (image://registry.dagger.io/engine:v0.21.10) linux/amd64
已是最新版时回显与不带 --check 相同。
4.2 dagger login / logout(Dagger Cloud,可选)
dagger login --help
Log in to Dagger Cloud
USAGE
dagger login [options] [org]
Cloud 仅提供托管 trace 查看等增值能力(执行进度提示中的 Setup tracing at https://dagger.cloud/traces/setup 即其入口),不登录不影响本地全部功能;设置环境变量 DAGGER_NO_NAG=1 可隐藏该提示(提示原文实测保留在每次带进度输出的结尾)。
五、模块管理类命令
5.1 dagger init(初始化模块)
在空目录创建 dagger.json,--name 指定模块名(默认取父目录名):
mkdir -p /opt/workspace/dagger-demo && cd /opt/workspace/dagger-demo
dagger init --name demo
cat dagger.json
{
"name": "demo",
"engineVersion": "v0.21.10"
}
初始化即固定引擎版本基线。重复 init 会报错(实测):
Error: module already exists
init 还支持 --sdk(初始化同时装 SDK)、--blueprint(以现有模块为模板)、--license(默认 Apache-2.0,见 dagger init --help 原文)。
5.2 dagger develop(接入/重生成 SDK)
给已存在的模块补装 SDK 用 develop 而非 init(develop --help 原文:In a module without SDK: install an SDK and start an implementation):
dagger develop --sdk=python --progress plain
10 : develop
11 : ┆ develop . DONE [2.3s]
10 : develop DONE [2.3s]
执行后生成(实测文件清单):pyproject.toml(注意 requires-python = ">=3.14",由 SDK 运行时镜像保证,与宿主机 Python 无关)、sdk/(本地 SDK 源码)、src/demo/__init__.py 与 src/demo/main.py(函数模板),并把 dagger.json 更新为:
{
"name": "demo",
"engineVersion": "v0.21.10",
"sdk": {
"source": "python"
}
}
develop 是幂等命令(官方帮助原文:you can run it at any time, any number of times),引擎升级后重跑可重新对齐代码生成。
5.3 dagger functions(列出模块函数)
无 SDK 的空模块(实测):
dagger functions --progress plain
No functions found.
写入三个函数(Python SDK 实现,代码见《dagger 0.21.10 SDK 与 API 使用详解》5.2 节)后再执行(实测):
dagger functions -s
Name Description
build 把源码目录挂进 alpine 容器,把 msg.txt 复制为 output.txt 并追加构建标记
hello 返回一句问候语
report 构建并把输出文件内容作为字符串返回
函数列表即模块的"API 目录",名称/描述直接来自代码中的函数名与 docstring。
5.4 dagger config(查看模块配置)
dagger config --json -s
{
"name": "demo",
"engineVersion": "v0.21.10",
"sdk": {
"source": "python"
}
}
与文件内容一致,--json 输出规范化结构,适合脚本读取。
5.5 dagger install / uninstall(依赖管理)
把另一个模块安装为依赖(实测用本地路径引用):
cd /opt/workspace/dagger-demo2
dagger install ../demo
Installed module dependency "demo"
dagger.json 随之新增 dependencies(实测):
{
"name": "demo2",
"engineVersion": "v0.21.10",
"dependencies": [
{
"name": "demo",
"source": "../demo"
}
]
}
卸载依赖(实测):
dagger uninstall demo
{
"name": "demo2",
"engineVersion": "v0.21.10"
}
说明:
dagger install亦支持远程 Git 引用(帮助示例dagger install github.com/shykes/daggerverse/hello@v0.3.0);被依赖模块的函数通过宿主模块 SDK 的依赖对象调用,或用-m直接加载目标模块(见 6.3)。
六、函数调用与查询类命令
6.1 dagger call(调用函数,最常用)
调用 demo 模块的问候函数(实测,-s 关闭进度输出):
dagger call hello --name dagger -s
Hello, dagger!
链式调用:构建后取文件内容输出(实测):
dagger call report --src . -s
hello from dagger module
built-by-dagger
用 --output 把结果导出为本地文件(实测):
dagger call build --src . file --path /src/output.txt --output ./exported-output.txt -s
Saved to "/opt/workspace/dagger-demo/exported-output.txt".
cat exported-output.txt
hello from dagger module
built-by-dagger
call 的链式语法:函数返回对象类型(Container/Directory/File)时可继续接子函数,直到返回标量或导出;--json 可把标量结果转为 JSON 输出。当前模块可调函数清单即 dagger call --help 的解析结果(实测解析行):query_functions="[build hello report]"。
6.2 dagger core(直接调用核心 API 函数,实验性)
dagger core --help
Call a core function
USAGE
dagger core [options] <function>
EXPERIMENTAL
dagger core is currently under development and may change in the future.
FUNCTIONS
address initialize an address to load
directories, containers, secrets or
other object types.
changeset Creates an empty changeset
cloud Dagger Cloud configuration and state
container Creates a scratch container, with no
image or metadata.
current-env Returns the current environment
...
directory Creates an empty directory.
engine The Dagger engine container
configuration and state
error Create a new error.
file Creates a file with the specified
contents.
git Queries a Git repository.
host Queries the host environment.
http Returns a file containing an http
remote url content.
...
输出节选(实测首尾):core 把 GraphQL API 的 Query 根对象直接暴露成子命令(container/directory/file/git/host/http/engine 等 70 余项),标注 EXPERIMENTAL,可在不写模块的情况下验证 API 链路。
6.3 dagger query(直发 GraphQL 查询)
官方示例(hello-world,实测回显为带代理引擎环境首次执行结果):
dagger query --progress plain -M <<'EOF'
{
container {
from(address:"hello-world") {
withExec(args:["/hello"]) {
stdout
}
}
}
}
EOF
{
"container": {
"from": {
"withExec": {
"stdout": "\nHello from Docker!\nThis message shows that your installation appears to be working correctly.\n\nTo generate this message, Docker took the following steps:\n 1. The Docker client contacted the Docker daemon.\n 2. The Docker daemon pulled the \"hello-world\" image from the Docker Hub.\n (amd64)\n 3. The Docker daemon created a new container from that image which runs the\n executable that produces the output you are currently reading.\n 4. The Docker daemon streamed that output to the Docker client, which sent it\n to your terminal.\n\nTo try something more ambitious, you can run an Ubuntu container with:\n $ docker run -it ubuntu bash\n\nShare images, automate workflows, and more with a free Docker ID:\n https://hub.docker.com/\n\nFor more examples and ideas, visit:\n https://docs.docker.com/get-started/\n\n"
}
}
}
}
查询引擎版本(实测,-M 表示不自动加载当前目录模块):
dagger query -s -M <<'EOF'
{ version }
EOF
{
"version": "v0.21.10"
}
query 是所有命令的底层形态:call 与各 SDK 都编译为 query;调试 API 结构时它最直接。
6.4 dagger call 的错误样本(实测)
调用不存在的函数(dagger call nope -s):
17:13:35 INF dagger call parse schema summary reason=remaining_args error="unknown command \"nope\" for \"dagger call\"" requested_args="[nope -s]" remaining_args="[nope -s]" command_path="dagger call" main_object=Query object_count=71 interface_count=3 enum_count=16 input_count=3 query_function_count=3 query_functions="[build hello report]"
Error: unknown command "nope" for "dagger call" [traceparent:bdd7e1bad9fef396be046cb3b5ab4c38-2ee3d63a3adf7713]
Run 'dagger call --help' for usage.
该日志同时给出了模块 schema 概要(object_count、query_functions 等),排障时可直接确认"引擎眼里的函数清单"。GraphQL 字段写错的 422 样本见 6.5 后注。
七、执行与调试类命令
7.1 dagger run(包裹任意进程注入会话)
run 在 Dagger 会话中执行外部命令,自动注入 DAGGER_SESSION_PORT 与 DAGGER_SESSION_TOKEN 两个环境变量,进程内即可用 HTTP 直调本地 GraphQL API(帮助原文给出的正是 curl 示例)。实测复现:
echo '{"query":"{ container { from(address: \"alpine:3.22\") { withExec(args: [\"echo\", \"api-works\"]) { stdout } } } }"}' | dagger run -s sh -c 'curl -s -u $DAGGER_SESSION_TOKEN: -H "content-type:application/json" -d @- http://127.0.0.1:$DAGGER_SESSION_PORT/query'
{"data":{"container":{"from":{"withExec":{"stdout":"api-works\n"}}}}}
这条链路证明:任何能发 HTTP 的语言/工具(无需官方 SDK)都能直接驱动引擎——会话端点即引擎本地 API 的入口。
7.2 常用全局选项速查(实测默认值)
| 选项 | 默认值 | 作用 |
|---|---|---|
--progress | auto | 进度渲染格式(auto/plain/tty/dots/logs),CI 中常用 plain |
-s, --silent | 关 | 完全隐藏进度,只留结果 |
-q, --quiet | 0(可叠加) | 降噪:显示进度但结束后清理 |
-m, --mod | 当前目录 | 加载指定模块(本地路径或远程 Git 引用) |
-M, --no-mod | 关 | 不自动加载模块(与 -m 互斥) |
-d, --debug | 关 | 调试日志与全量输出 |
-i, --interactive | 关 | 失败时进入交互终端(默认命令 /bin/sh) |
-w, --web | 关 | 在浏览器打开本次执行的 trace |
--lock | disabled | 工作区锁模式(disabled/live/pinned/frozen) |
八、实验性命令:lock 与 toolchain
两者帮助均标注 EXPERIMENTAL(实测回显):
Manage workspace lockfiles
EXPERIMENTAL
dagger lock is currently under development and may change in the future.
AVAILABLE COMMANDS
update Refresh workspace lock entries
Manage toolchains
EXPERIMENTAL
dagger toolchain is currently under development and may change in the future.
AVAILABLE COMMANDS
install Install a toolchain to the current module
list List all toolchains
uninstall Uninstall a toolchain
update Update toolchains
生产脚本暂不建议依赖(1.0-beta 文档轨中 Toolchains/Checks 已提升为核心概念,稳定后再跟进)。
九、引擎生命周期管理(组件本职)
dagger 的运行时即容器化引擎,CLI 全程自动管理,无需(也提供不了)独立的 dagger engine 子命令——实测 dagger engine --help 会回落到全局帮助(v0.21.10 中 engine 不是顶层子命令,引擎操作经由上表 core 的 engine 对象与容器运行时命令完成)。生命周期实测结论:
- 自动创建:本机无实例时,CLI 执行任务自动创建
dagger-engine-v0.21.10; - 自动启动:实例存在但已停止时,CLI 自动
docker start后连接(实测日志exec docker start dagger-engine-v0.21.10 DONE),连接成功日志(实测):INF connected name=55f142d61e1e client-version=v0.21.10 server-version=v0.21.10; - 删除后自动重建:
docker rm -f实例后执行任意任务,CLI 按内嵌镜像地址重建(实测重建后查询正常返回{ "version": "v0.21.10" }); - 重建实例不带自定义配置:自动重建的实例只有 CLI 默认环境变量(实测
docker inspect可见DAGGER_GO_SDK_MANIFEST_DIGEST、_EXPERIMENTAL_DAGGER_RUNNER_HOST=unix:///run/dagger/engine.sock等),手工注入的代理等变量会丢失,受限网络需按 B1 篇 FAQ 重建。
查看实例状态的标准姿势:
docker ps -a --filter name=dagger-engine --format '{{.Names}} {{.Status}}'
dagger-engine-v0.21.10 Up 2 seconds
十、注意事项
- 全局选项写在子命令前;
-m与-M互斥; call链式参数中--src .这类目录参数传相对路径时以模块根为基准;- 每次 CLI 执行都会生成 trace(进度尾部提示),接 OpenTelemetry 后可在自有后端查看;
DAGGER_NO_NAG=1屏蔽 Cloud 提示; - 实验性命令(core/lock/toolchain)与
--x-release不要进生产脚本; - 引擎实例名含版本号,升级 CLI 后旧实例仍在(可复用旧缓存),磁盘紧张时按版本清理。
十一、常见问题(FAQ)
Q1:dagger call 报 unknown command,但函数明明写对了?
对照报错日志中的 query_functions="[...]" 清单确认函数名;多为模块未通过 dagger develop 生成 SDK、或函数未挂 @object_type/导出(Python 中类未标注即不入 schema)。修复后重跑 dagger functions 验证。
Q2:dagger query 报 422 GRAPHQL_VALIDATION_FAILED?
字段拼写错误即触发(实测样本):
Error: make request: returned error 422: {"data":null,"errors":[{"message":"Cannot query field \"containr\" on type \"Query\". Did you mean \"container\"?","locations":[{"line":1,"column":3}],"extensions":{"code":"GRAPHQL_VALIDATION_FAILED"}}]}
按提示的 "Did you mean" 修正字段名即可;API 全量字段以引擎内省为准。
Q3:进度输出太吵,CI 里怎么静默?
dagger -s <子命令> 全静默,或 --progress plain 用纯文本进度(可被 CI 日志采集);两者实测均正常收敛输出。
Q4:本机首次执行卡在拉取镜像后报 connection refused?
引擎拉镜像走自身网络栈,不走容器运行时守护进程代理;按《Ubuntu 22.04 安装 dagger 0.21.10 指南》第八章 Q3 重建带代理的引擎实例。
十二、参考链接
- 官方 CLI 文档:https://docs.dagger.io/0.21(Reference 章节)
- v0.21.10 Release Notes:https://github.com/dagger/dagger/releases/tag/v0.21.10
- 本系列姊妹篇:《dagger 0.21.10 介绍与选型指南》《Ubuntu 22.04 安装 dagger 0.21.10 指南》《dagger 0.21.10 SDK 与 API 使用详解》