Client libraries

Most of the time you call the Dagger API through the CLI or from inside a module. A client is for your own program, whether a script, a service, or a test harness, that needs to talk to the engine directly.

There are two ways to get one.

Generated clients

A generated client is a typed binding to one module's API, including the core API and every module it depends on. It lives in an SDK scope. dagger.toml records the scope and target module, and dagger generate regenerates it with the other generated files.

Install the SDK for the required language. For Go, run the client command from a project with a go.mod file, then add the target module:

dagger module install dagger.io/sdk/go
dagger module client add ./.dagger/modules/api --sdk=go

The module argument must be an explicit local path, such as ./api or ../api, or a module address. Installed module names and unmarked local paths are not supported. A bare api never means ./api. Saved local targets are relative to the directory containing dagger.toml. They keep an explicit path marker. For each SDK, the engine compares the deepest registered scope that contains the current directory with the detected client root. It uses the deeper path. Without --sdk, the engine selects the unique deepest scope across installed SDKs. If several SDKs have that scope, the command fails and asks you to select one with --sdk. The --sdk help text lists installed SDKs. The command accepts no SDK settings flags. Generation uses saved settings. The engine records the target in one scope in dagger.toml, and the SDK writes the bindings.

dagger module client list       # clients in scopes that contain the current directory
dagger module client list --all # clients in every scope
dagger generate                 # regenerate bindings after the bound module changes

The list shows SCOPE, SDK, and the complete TARGET removal key. Scope paths are relative to the workspace root. To remove a specific row, run this from its listed scope:

dagger module client rm <TARGET> --sdk=<SDK>

Removal uses recorded client targets and selects the deepest matching scope. It fails if several SDKs match at that scope. Use --sdk to select one. List also shows invalid old targets. Remove them with their exact listed target. If invalid targets remain, removal succeeds and generation is skipped with a warning. Correct or remove those targets to resume generation.

The current Go SDK supports clients in ordinary Go projects. Python, Dang, and Java currently require a Dagger module in the scope. TypeScript and PHP still need an update to the new SDK interface. The bindings pin the engine version the bound module requires, so a client and the module it came from stay in step.

Standalone client libraries

Each SDK also publishes a plain client library for the core API to its language's package registry. Use it when you don't need module-specific bindings, or in a language that has no generated clients yet.

Language	Package	Source
Go	dagger.io/dagger	sdk/go
TypeScript	@dagger.io/dagger (npm)	sdk/typescript
Python	dagger-io (PyPI)	sdk/python
PHP	dagger/dagger (Packagist)	sdk/php
Java	io.dagger:dagger-java-sdk (Maven)	sdk/java
Elixir	dagger (Hex)	sdk/elixir
Rust	dagger-sdk (crates.io)	sdk/rust
.NET	Dagger.SDK	sdk/dotnet

A client library needs a session with the engine. The simplest way to get one is to run your program under dagger api with-session. It starts a session and sets DAGGER_SESSION_PORT and DAGGER_SESSION_TOKEN in the program's environment:

dagger api with-session go run main.go
dagger api with-session node index.mjs
dagger api with-session python main.py

Every library reads those two variables. Progress renders in the same TUI as any other Dagger command, and the run shows up in Dagger Cloud like a dagger check would.

Raw GraphQL

The API is GraphQL underneath, so any HTTP client works. With a session from dagger api with-session, post queries to http://127.0.0.1:$DAGGER_SESSION_PORT/query with the token as the basic-auth username:

jq -n '{query:"{container{id}}"}' | \
  dagger api with-session sh -c 'curl -s \
    -u $DAGGER_SESSION_TOKEN: \
    -H "content-type:application/json" \
    -d @- \
    http://127.0.0.1:$DAGGER_SESSION_PORT/query'

The API reference documents the schema.