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。

daggerCICDDocker容器GoPython2026/10/19

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.

命令分组速读:

分组命令用途
Cloudlogin / 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 常用全局选项速查(实测默认值)

选项默认值作用
--progressauto进度渲染格式(auto/plain/tty/dots/logs),CI 中常用 plain
-s, --silent关完全隐藏进度,只留结果
-q, --quiet0(可叠加)降噪:显示进度但结束后清理
-m, --mod当前目录加载指定模块(本地路径或远程 Git 引用)
-M, --no-mod关不自动加载模块(与 -m 互斥)
-d, --debug关调试日志与全量输出
-i, --interactive关失败时进入交互终端(默认命令 /bin/sh)
-w, --web关在浏览器打开本次执行的 trace
--lockdisabled工作区锁模式(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 重建带代理的引擎实例。

十二、参考链接