dimctl

Minimal HTTP client for the dim daemon, focused on one job: submit a container build, follow its logs, confirm whether it succeeded. dim = Docker Image Manager.

Designed for AI agents and CI: deterministic exit codes, stable error codes, no interactive prompts.

Install

npm install -g dimctl

Node ≥ 18 required. Single tarball (~30 KB), no native binary, no platform packages.

Auth

dimctl does not log in. It picks up a bearer token from the environment:

export DIM_TOKEN=dim_xxxxxxxx
export DIM_ADDR=http://127.0.0.1:8080   # default

The token is typically a long-lived access token created once by an operator using the daemon's admin CLI (dim-cli tokens create --name ci-bot). It's attached as Authorization: Bearer on every request.

As a fallback, dimctl will read a login token written by the in-tree Go CLI (dim-cli login) from $XDG_CONFIG_HOME/dim-cli/token / %APPDATA%\dim-cli\token — convenient on a developer's box, but agents and CI should use DIM_TOKEN.

If no token is reachable, the first request returns error: auth.required: ... with exit code 2.

Commands

dimctl submit --repo URL --ref REF --image IMG --tag T \
              [--dockerfile PATH] [--context DIR] \
              [--build-arg KEY=VAL ...] [--no-cache]
# → prints the build id (ULID) on stdout

dimctl get <id>    [-o table|json]
# → status, digest, error_class, error_summary, timing

dimctl logs <id>   [--follow] [--from-seq N]
# → streams `[stream seq=N] line`; on terminal status prints
#   `[final-status] success|failure|canceled` to stderr

dimctl cancel <id>
# → cancels a queued or running build

dimctl creds list  [-o table|json]
# → which git / registry hosts have credentials configured
#   (no secrets are ever returned). Useful as a pre-flight check
#   before `submit` to avoid `credentials.*.missing` 400s.

Worked example

"Build https://gitea.example.com/u/svc.git main and push to registry.example.com/u/svc:v3. Tell me the digest."

# 1. Pre-flight: both hosts must have credentials in the daemon.
dimctl creds list -o json | jq -e '
  (.git[]?.host       | select(. == "gitea.example.com"))      and
  (.registry[]?.host  | select(. == "registry.example.com"))
' >/dev/null

# 2. Submit, capture the id.
id=$(dimctl submit \
  --repo https://gitea.example.com/u/svc.git --ref main \
  --image registry.example.com/u/svc --tag v3)

# 3. Follow logs to completion (blocks; final status on stderr).
dimctl logs "$id" --follow

# 4. Read the digest.
dimctl get "$id" -o json | jq -r .digest

Exit codes (stable contract)

• 0 — success
• 1 — client-side error (bad flags, no token, network failure)
• 2 — API error (4xx/5xx from daemon); stderr starts error: <code>: <message>

Stable error codes branched on by automation include auth.required, auth.invalid, request.invalid, credentials.git.missing, credentials.registry.missing, path.escape, image.host.missing, queue.full, build.not_found. Treat 4xx as deterministic — don't retry with the same args.

What dimctl deliberately does NOT do

| Not in scope | Where it lives instead | |---|---| | login / logout / whoami / passwd | The Go CLI dim-cli or the daemon's web UI. dimctl assumes a token is already provisioned. | | Listing build history (list) | The web UI's dashboard, or dim-cli list. dimctl is "do this build, watch this build", not a browser. | | Creating / deleting credentials | Operator-side concern handled by dim-cli creds set/delete or the UI. creds list is exposed only for pre-flight checks. | | Managing access tokens | dim-cli tokens create/list/revoke. dimctl uses tokens, doesn't manage them. |

License

MIT