fix: ship the CLI as earth in the published docker image

[kmannislands]

Fixes #796. Stacked on #800 — base is gh-751-earth-env-migration-internal-vars, so review/merge that first.

The v0.8.18 release notes document the CLI rename earthly → earth and the release assets follow it, but the published image shipped only earthly. +earthly-docker hardcoded DEFAULT_INSTALLATION_NAME="earthly" while the release path passes "earth".

Confirming the starting state first

The issue had a comment retracting part of the original report; that retraction was itself wrong and I withdrew it. It grepped the shipped binaries for earth-buildkitd / .earth literals and found only the earthly forms in both, concluding there was no divergence. That test cannot detect this: the names are built at runtime by concatenation ("."+installName, installName+"-buildkitd", installName+"-cache"), so the derived form never exists as a literal. The earthly literals such a grep finds are the fallback defaults (cmp.Or(installName, "earthly")), compiled into both binaries regardless of the ldflag.

Running them settles it. Built both paths locally at v0.8.18:

# release path (--DEFAULT_INSTALLATION_NAME=earth)
$ ... alpine sh -c 'earth bootstrap --no-buildkit >/dev/null 2>&1; ls -d /root/.earth*'
/root/.earth

# the binary extracted from the published image
$ ... alpine sh -c 'earthly bootstrap --no-buildkit >/dev/null 2>&1; ls -d /root/.earth*'
/root/.earthly

# same image binary renamed to `earth` -- still .earthly, so it is the ldflag, not argv[0]
/root/.earthly

A locally built +earthly-docker at main is indistinguishable from published earthbuild/earthbuild:v0.8.18 on every point checked, so this reproduces the shipped artifact rather than a dev approximation.

Changes

DEFAULT_INSTALLATION_NAME is threaded, not hardcoded (Earthfile), and declared once as ARG --global in release/Earthfile so +signed-release and +perform-release-earthly-dockerhub read the same value and cannot drift apart again. Same shape as #728's DEFAULT_BUILDKITD_IMAGE fix.

The CLI installs as /usr/bin/earth, with /usr/bin/earthly kept as a symlink for one deprecation cycle, matching how EARTHLY_* env vars are being retired rather than removed. earthly-entrypoint.sh calls earth so containerised builds don't print the rename notice on every invocation.

PortOffset no longer offsets earth. It special-cased only "earthly" as "the official release", so switching the image to earth would have moved buildkit 8372→8846 and the local registry 8371→8845 while earthly-entrypoint.sh and buildkitd/buildkitd.tcp.template hardcode the unoffset values. Both official spellings now return 0; earthly stays exempt for the deprecation cycle so an installation predating the rename keeps reaching its existing daemon. Note the old comment was inverted — official releases are earth, so they were the ones carrying a non-zero offset.

The certs path is derived, not hardcoded. earthly-entrypoint.sh hardcoded /root/.earthly/certs/ for files the CLI writes to ~/.<installation name>/certs, so the rename alone would have left three dangling symlinks and a TLS handshake failure with no diagnostic. It now derives from a baked EARTH_INSTALLATION_NAME and fails loudly if the directory is missing.

Two defects in the rename notice (warnIfEarth → warnRenamedFromEarthly): it asserted earthly "is currently symlinked" whether or not it was — in the pre-fix image nothing was symlinked and no earth existed — and its rm hint was gated on path.Join(dir, cmdName) with cmdName == "earthly", i.e. it tested for the invoked binary itself rather than its replacement, so it could never fire correctly. It also used filepath.Abs(argv[0]), which resolves against the working directory when the CLI came off PATH; it now uses os.Executable() for the location and argv[0] only for the invoked name.

CI pins the installation name to earth (ci.yml, build-earthly.yml). Without this the PR is red on its own: renaming the in-image CLI also renames the daemon it manages, so the image test's docker.sock case looked for earth-buildkitd, found nothing, and tried to pull ghcr.io/earthbuild/earthbuild:buildkitd-image-test — a tag +earthly-docker never builds. The pin cascades to the six places CI addresses the daemon directly (reusable-test.yml, reusable-misc-tests-{1,2}.yml, tests/registry-certs/test.sh, the bug-report template). tests/bootstrap/test-bootstrap.sh now derives the name from $default_install_name instead of hardcoding it, so it tracks whatever CI passes. earth-retry.sh and the failure-diagnostics defaults keep the deprecated names alongside the new ones — both are best-effort cleanup and a job may still have either container.

Verification

Against a locally built image, before → after on identical build args:

Check	before	after
command -v earth	nothing	/usr/bin/earth
earthly	real binary	symlink → earth
earth --version	earth: not found	earth version v0.8.18 …
config dir	/root/.earthly	/root/.earth (matches release binaries)
earthly ls	claims a symlink that doesn't exist	renamed to earth + rm /usr/bin/earthly
self-inflicted EARTHLY_ warnings	6	0 (via #800)

Suite	Result
scripts/tests/earth-image.sh (incl. privileged embedded-buildkit hello-world)	pass
+lint	0 issues
+lint-scripts-misc	pass
go test ./config/... ./internal/env/...	pass

The image suite passing the privileged hello-world build is the check that matters for the certs and port changes — it stands up buildkitd inside the container over TLS on 8372.

New tests: config/config_test.go pins both official names to a zero offset and asserts dev names stay in range; scripts/tests/earth-image.sh gains assertions that earth is on PATH, that earth --version works, and that the deprecated name still resolves and says so.

Notes for review

• The tests/ call sites are swept in test: drive the earth binary throughout the integration suite #803, not here. They keep working through the symlink either way; test: drive the earth binary throughout the integration suite #803 moves them onto earth so the suite exercises the binary users actually get.
• /etc/.earthly/config.yml is deliberately unchanged — it is a documented mount point for callers supplying their own config, not a path the CLI derives, and it is passed explicitly via --config.
• +earthly-docker's DEFAULT_INSTALLATION_NAME defaults to earth, not earthly-dev like the binary targets. That default exists to keep a dev binary off a developer's real config dir and containers, which is moot inside a container; the pre-fix value here was the undecorated earthly for the same reason.
• AGENTS.md listed /usr/bin/earthly as a literal to leave alone "until the rename itself" — this is that change, so the guidance is updated rather than violated.
• The earth-vs-earthly banner in --version follows argv[0] via common.GetBinaryName(), so it correctly reports whichever name was used.

🤖 Generated with Claude Code

[github-actions]

🎉 Are we earthbuild yet?

Great progress! You've reduced "earthly" occurrences by 29 (0.76%)

📈 Overall Progress

Branch	Total Count
main	3817
This PR	3788
Difference	-29 (0.76%)

📁 Changes by file type:

File Type	Change
Go files (.go)	❌ +6
Documentation (.md)	❌ +3
Earthfiles	✅ -10

---

Keep up the great work migrating from Earthly to Earthbuild! 🚀

💡 Tips for finding more occurrences

Run locally to see detailed breakdown:

./.github/scripts/count-earthly.sh

Note that the goal is not to reach 0.
There is anticipated to be at least some occurrences of earthly in the source code due to backwards compatibility with config files and language constructs.

[janishorsts]

LGTM except https://github.com/EarthBuild/earthbuild/pull/801/changes#r3860762190.

Ship when you are ready.