Earthfile reference

Earthfiles are comprised of a series of target declarations and recipe definitions. Earthfiles are named Earthfile, regardless of their location in the codebase.
Earthfiles have the following rough structure:
1
<base-recipe>
2
...
3
​
4
<target-name>:
5
    <recipe>
6
    ...
7
​
8
<target-name>:
9
    <recipe>
10
    ...
11
​
12
<command-name>:
13
    <recipe>
14
    ...
Copied!
Each recipe contains a series of commands, which are defined below. For an introduction into Earthfiles, see the Basics page.
FROM
Synopsis
FROM <image-name>
FROM [--platform <platform>] [--allow-privileged] <target-ref> [--<build-arg-key>=<build-arg-value>...]
Description
The FROM command initializes a new build environment and sets the base image for subsequent instructions. It works similarly to the classical Dockerfile FROM instruction, but it has the added ability to use another target's image as the base image.
Examples:
Classical reference: FROM alpine:latest
Local reference: FROM +another-target
Relative reference: FROM ./subdirectory+some-target
Remote reference from a public or private git repository: FROM github.com/example/project+remote-target
The FROM command does not mark any saved images or artifacts of the referenced target for output, nor does it mark any push commands of the referenced target for pushing. For that, please use BUILD.
Note
The FROM ... AS ... form available in the classical Dockerfile syntax is not supported in Earthfiles. Instead, define a new Earthly target. For example, the following Dockerfile
1
# Dockerfile
2
​
3
FROM alpine:3.15 AS build
4
# ... instructions for build
5
​
6
FROM build as another
7
# ... further instructions inheriting build
8
​
9
FROM busybox as yet-another
10
COPY --from=build ./a-file ./
Copied!
can become
1
# Earthfile
2
​
3
build:
4
    FROM alpine:3.15
5
    # ... instructions for build
6
    SAVE ARTIFACT ./a-file
7
​
8
another:
9
    FROM +build
10
    # ... further instructions inheriting build
11
​
12
yet-another:
13
    FROM busybox
14
    COPY +build/a-file ./
Copied!
Options
--<build-arg-key>=<build-arg-value>
Sets a value override of <build-arg-value> for the build arg identified by <build-arg-key>. See also BUILD for more details about build args.
--platform <platform>
Specifies the platform to build on.
For more information see the multi-platform guide.
--allow-privileged
Allows remotely-referenced targets to request privileged capabilities; this flag has no effect when referencing local targets.
Additionally, for privileged capabilities, earthly must be invoked on the command line with the --allow-privileged (or -P) flag.
For example, consider two Earthfiles, one hosted on a remote GitHub repo:
1
# github.com/earthly/example
2
FROM alpine:latest
3
elevated-target:
4
    RUN --privileged echo do something requiring privileged access.
Copied!
and a local Earthfile:
1
FROM alpine:latest
2
my-target:
3
    FROM --allow-privileged github.com/earthly/example+elevated-target
4
    # ... further instructions inheriting remotely referenced Earthfile
Copied!
then one can build my-target by invoking earthly with the --allow-privileged (or -P) flag:
1
earthly --allow-privileged +my-target
Copied!
--build-arg <key>=<value> (deprecated)
This option is deprecated. Use --<build-arg-key>=<build-arg-value> instead.
RUN
Synopsis
RUN [--push] [--entrypoint] [--privileged] [--secret <env-var>=<secret-ref>] [--ssh] [--mount <mount-spec>] [--] <command> (shell form)
RUN [[<flags>...], "<executable>", "<arg1>", "<arg2>", ...] (exec form)
Description
The RUN command executes commands in the build environment of the current target, in a new layer. It works similarly to the Dockerfile RUN command, with some added options.
The command allows for two possible forms. The exec form runs the command executable without the use of a shell. The shell form uses the default shell (/bin/sh -c) to interpret the command and execute it. In either form, you can use a \ to continue a single RUN instruction onto the next line.
When the --entrypoint flag is used, the current image entrypoint is used to prepend the current command.
To avoid any ambiguity regarding whether an argument is a RUN flag option or part of the command, the delimiter -- may be used to signal the parser that no more RUN flag options will follow.
Options
--push
Marks the command as a "push command". Push commands are only executed if all other non-push instructions succeed. In addition, push commands are never cached, thus they are executed on every applicable invocation of the build.
Push commands are not run by default. Add the --push flag to the earthly invocation to enable pushing. For example
1
earthly --push +deploy
Copied!
Push commands were introduced to allow the user to define commands that have an effect external to the build. This kind of effects are only allowed to take place if the entire build succeeds. Good candidates for push commands are uploads of artifacts to artifactories, commands that make a change to an external environment, like a production or staging environment.
Note that non-push commands are not allowed to follow a push command within a recipe.
--no-cache
Force the command to run every time; ignoring any cache. Any commands following the invocation of RUN --no-cache, will also ignore the cache. If --no-cache is used as an option on the RUN statement within a WITH DOCKER statement, all commands after the WITH DOCKER will also ignore the cache.
--entrypoint
Prepends the currently defined entrypoint to the command.
This option is useful for replacing docker run in a traditional build environment. For example, a command like
1
docker run --rm -v "$(pwd):/data" cytopia/golint .
Copied!
Might become the following in an Earthfile
1
FROM cytopia/goling
2
COPY . /data
3
RUN --entrypoint .
Copied!
--privileged
Allows the command to use privileged capabilities.
Note that privileged mode is not enabled by default. In order to use this option, you need to additionally pass the flag --allow-privileged (or -P) to the earthly command. Example:
1
earthly --allow-privileged +some-target
Copied!
--secret <env-var>=<secret-ref> | <secret-id>
Makes available a secret, in the form of an env var (its name is defined by <env-var>), to the command being executed. If you only specify <secret-id>, the name of the env var will be <secret-id> and its value the value of <secret-id>.
The <secret-ref> needs to be of the form +secrets/<secret-id>, where <secret-id> is the identifier passed to the earthly command when passing the secret: earthly --secret <secret-id>=<value>.
Here is an example that showcases both syntaxes:
1
release:
2
    RUN --push --secret GITHUB_TOKEN=+secrets/GH_TOKEN github-release upload
3
release-short:
4
    RUN --push --secret GITHUB_TOKEN github-release upload
Copied!
1
earthly --secret GH_TOKEN="the-actual-secret-token-value" +release
2
earthly --secret GITHUB_TOKEN="the-actual-secret-token-value" +release-short
Copied!
An empty string is also allowed for <secret-ref>, allowing for optional secrets, should it need to be disabled.
1
release:
2
    ARG SECRET_ID=+secrets/GH_TOKEN
3
    RUN --push --secret GITHUB_TOKEN=$SECRET_ID github-release upload
4
release-short:
5
    ARG SECRET_ID=GITHUB_TOKEN
6
    RUN --push --secret $SECRET_ID github-release upload
Copied!
1
earthly +release --SECRET_ID=""
2
earthly +release-short --SECRET_ID=""
Copied!
It is also possible to mount a secret as a file with RUN --mount type=secret,id=+secret/secret-id,target=/path/of/secret. See --mount below.
For more information on how to use secrets see the build arguments and secrets guide. See also the Cloud secrets guide.
--ssh
Allows a command to access the ssh authentication client running on the host via the socket which is referenced by the environment variable SSH_AUTH_SOCK.
Here is an example:
1
RUN mkdir -p ~/.ssh && \
2
    echo 'github.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==' >> ~/.ssh/known_hosts && \
3
    echo 'gitlab.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9' >> ~/.ssh/known_hosts
4
RUN --ssh git config --global url."[email protected]:".insteadOf "https://github.com/" && \
5
    go mod download
Copied!
--mount <mount-spec>
Mounts a file or directory in the context of the build environment.
The <mount-spec> is defined as a series of comma-separated list of key-values. The following keys are allowed
Key
Description
Example
type
The type of the mount. Currently only cache, tmpfs, and secret are allowed.
type=cache
target
The target path for the mount.
target=/var/lib/data
id
The secret ID for the contents of the target file, only applicable for type=secret.
id=+secrets/password
Examples:
Persisting cache for a single RUN command, even when its dependencies change:
1
ENV GOCACHE=/go-cache
2
RUN --mount=type=cache,target=/go-cache go build main.go
Copied!
Note that mounts cannot be shared between targets, nor can they be shared within the same target, if the build-args differ between invocations.
Mounting a secret as a file:
1
RUN --mount=type=secret,id=+secrets/netrc,target=/root/.netrc curl https://example.earthly.dev/restricted/example-file-that-requires-auth > data
Copied!
The contents of the secret /root/.netrc file can then be specified from the command line as:
1
earthly --secret netrc="machine example.earthly.dev login myusername password mypassword" +base
Copied!
or by passing the contents of an existing file from the host filesystem:
1
earthly --secret-file netrc="$HOME/.netrc" +base
Copied!
--interactive / --interactive-keep
Opens an interactive prompt during the target build. An interactive prompt must:
1.Be the last issued command in the target, with the exception of SAVE IMAGE commands. This also means that you cannot FROM a target containing a RUN --interactive.
2.Be the only --interactive target within the run.
3.Not be within a LOCALLY-designated target.
Examples:
Start an interactive python REPL:
1
python:
2
    FROM alpine:3.15
3
    RUN apk add python
4
    RUN --interactive python
Copied!
Start bash to tweak an image by hand. Changes made will be included:
1
build:
2
    FROM alpine:3.15
3
    RUN apk add bash
4
    RUN --interactive-keep bash
Copied!
COPY
Synopsis
COPY [options...] <src>... <dest> (classical form)
COPY [options...] <src-artifact>... <dest> (artifact form)
COPY [options...] (<src-artifact> --<build-arg-key>=<build-arg-value>...) <dest> (artifact form with build args)
Description
The command COPY allows copying of files and directories between different contexts.
The command may take a couple of possible forms. In the classical form, COPY copies files and directories from the build context into the build environment - in this form, it works similarly to the Dockerfile COPY command. In the artifact form, COPY copies files or directories (also known as "artifacts" in this context) from the artifact environment of other build targets into the build environment of the current target. Either form allows the use of wildcards for the sources.
The parameter <src-artifact> is an artifact reference and is generally of the form <target-ref>/<artifact-path>, where <target-ref> is the reference to the target which needs to be built in order to yield the artifact and <artifact-path> is the path within the artifact environment of the target, where the file or directory is located. The <artifact-path> may also be a wildcard.
The COPY command does not mark any saved images or artifacts of the referenced target for output, nor does it mark any push commands of the referenced target for pushing. For that, please use BUILD.
The classical form of the COPY command differs from Dockerfiles in two cases:
URL sources are not yet supported.
Absolute paths are not supported - sources in the current directory cannot be referenced with a leading /
Note
To prevent Earthly from copying unwanted files, you may specify file patterns to be excluded from the build context using an .earthlyignore file. This file has the same syntax as a .dockerignore file.
Options
--dir
The option --dir changes the behavior of the COPY command to copy the directories themselves, rather than the contents of the directories. It allows the command to behave similarly to a cp -r operation on a unix system. This allows the enumeration of several directories to be copied over on a single line (and thus, within a single layer). For example, the following two are equivalent with respect to what is being copied in the end (but not equivalent with respect to the number of layers used).
1
COPY dir1 dir1
2
COPY dir2 dir2
3
COPY dir3 dir3
Copied!
1
COPY --dir dir1 dir2 dir3 ./
Copied!
--<build-arg-key>=<build-arg-value>
Sets a value override of <build-arg-value> for the build arg identified by <build-arg-key>, when building the target containing the mentioned artifact. See also BUILD for more details about the build arg options.
Note that build args and the artifact references they apply to need to be surrounded by paranthesis:
1
COPY (+target1/artifact --arg1=foo --arg2=bar) ./dest/path
Copied!
--keep-ts
Instructs Earthly to not overwrite the file creation timestamps with a constant.
--keep-own
Instructs Earthly to keep file ownership information. This applies only to the artifact form and has no effect otherwise.
--if-exists
Only copy source if it exists; if it does not exist, earthly will simply ignore the COPY command and won't treat any missing sources as failures.
--from
Although this option is present in classical Dockerfile syntax, it is not supported by Earthfiles. You may instead use a combination of SAVE ARTIFACT and COPY artifact form commands to achieve similar effects. For example, the following Dockerfile
1
# Dockerfile
2
COPY --from=some-image /path/to/some-file.txt ./
Copied!
... would be equivalent to final-target in the following Earthfile
1
# Earthfile
2
intermediate:
3
    FROM some-image
4
    SAVE ARTIFACT /path/to/some-file.txt
5
​
6
final-target:
7
    COPY +intermediate/some-file.txt ./
Copied!
--platform <platform>
In artifact form, it specifies the platform to build the artifact on.
For more information see the multi-platform guide.
--allow-privileged
Same as FROM --allow-privileged.
--build-arg <key>=<value> (deprecated)
The option --build-arg is deprecated. Use --<build-arg-key>=<build-arg-value> instead.
Examples
Assuming the following directory tree, of a folder named test:
1
test
2
  └── file
Copied!
Here is how the following copy commands will behave:
1
# Copies the contents of the test directory.
2
# To access the file, it would be found at ./file
3
COPY test .
4
​
5
# Also copies the contents of the test directory.
6
# To access the file, it would be found at ./file
7
COPY test/* .
8
​
9
# Copies the whole test folder.
10
# To access the file, it would be found at ./test/file
11
COPY --dir test .
Copied!
One can also copy from other Earthfile targets:
1
FROM alpine:3.15
2
dummy-target:
3
    RUN echo aGVsbG8= > encoded-data
4
    SAVE ARTIFACT encoded-data
5
example:
6
    COPY +dummy-target/encoded-data .
7
    RUN cat encoded-data | base64 -d
Copied!
Parentheses are required when passing build-args:
1
FROM alpine:3.15
2
RUN apk add coreutils # required for base32 binary
3
dummy-target:
4
    ARG encoder="base64"
5
    RUN echo hello | $encoder > encoded-data
6
    SAVE ARTIFACT encoded-data
7
example:
8
    COPY ( +dummy-target/encoded-data --encoder=base32 ) .
9
    RUN cat encoded-data | base32 -d
Copied!
For detailed examples demonstrating how other scenarios may function, please see our test suite.
ARG
Synopsis
ARG [--required] <name>[=<default-value>] (constant form)
ARG [--required] <name>=$(<default-value-expr>) (dynamic form)
Description
The command ARG declares a variable (or arg) with the name <name> and with an optional default value <default-value>. If no default value is provided, then empty string is used as the default value.
This command works similarly to the Dockerfile ARG command, with a few differences regarding the scope and the predefined args (called builtin args in Earthly). The variable's scope is always limited to the recipe of the current target or command and only from the point it is declared onward. For more information regarding builtin args, see the builtin args page.
In its constant form, the arg takes a default value defined as a constant string. If the <default-value> is not provided, then the default value is an empty string. In its dynamic form, the arg takes a default value defined as an expression. The expression is evaluated at run time and its result is used as the default value. The expression is interpreted via the default shell (/bin/sh -c) within the build environment.
If an ARG is defined in the base target of the Earthfile, then it becomes a global ARG and it is made available to every other target or command in that file, regardless of their base images used.
The value of an arg can be overridden either from the earthly command
1
earthly <target-ref> --<name>=<override-value>
Copied!
or from a command from another target, when implicitly or explicitly invoking the target containing the ARG
1
BUILD <target-ref> --<name>=<override-value>
2
COPY (<target-ref>/<artifact-path> --<name>=<override-value>) <dest-path>
3
FROM <target-ref> --<name>=<override-value>
Copied!
for example
1
BUILD +binary --NAME=john
2
COPY (+binary/bin --NAME=john) ./
3
FROM +docker-image --NAME=john
Copied!
For more information on how to use build args see the build arguments and secrets guide. A number of builtin args are available and are pre-filled by Earthly. For more information see builtin args.
Options
--required
A required ARG must be provided at build time and can never have a default value. Required args can help eliminate cases where the user has unexpectedly set an ARG to "".
1
target-required:
2
    # user must supply build arg for target
3
    ARG --required NAME
4
​
5
build-linux:
6
    # or explicitly supply in build command
7
    BUILD +target-required --NAME=john
Copied!
Earthly, by default, only supports dynamic values which start with the $(...) shell-out syntax -- passing a value such as --name="the honourable $(whoami)" will fail to execute the whoami program.
This behaviour can be changed with the experimental VERSION --shell-out-anywhere feature flag. This feature additionally allows shelling-out in any earthly command.
SAVE ARTIFACT
Synopsis
SAVE ARTIFACT [--keep-ts] [--keep-own] [--if-exists] [--force] <src> [<artifact-dest-path>] [AS LOCAL <local-path>]
Description
The command SAVE ARTIFACT copies a file, a directory, or a series of files and directories represented by a wildcard, from the build environment into the target's artifact environment.
If AS LOCAL ... is also specified, it additionally marks the artifact to be copied to the host at the location specified by <local-path>, once the build is deemed as successful.
If <artifact-dest-path> is not specified, it is inferred as /.
Files within the artifact environment are also known as "artifacts". Once a file has been copied into the artifact environment, it can be referenced in other places of the build (for example in a COPY command), using an artifact reference.
Hint
In order to inspect the contents of an artifacts environment, you can run
1
earthly --artifact +<target>/* ./output/
Copied!
This command dumps the contents of the artifact environment of the target +<target> into a local directory called output, which can be inspected directly.
Important
Note that there is a distinction between a directory artifact and file artifact when it comes to local output. When saving an artifact locally, a directory artifact will replace the destination entirely, while a file (or set of files) artifact will be copied into the destination directory.
1
# This will wipe ./destination and replace it with the contents of the ./my-directory artifact.
2
SAVE ARTIFACT ./my-directory AS LOCAL ./destination
3
# This will merge the contents of ./my-directory into ./destination.
4
SAVE ARTIFACT ./my-directory/* AS LOCAL ./destination
Copied!
Options
--keep-ts
Instructs Earthly to not overwrite the file creation timestamps with a constant.
--keep-own
Instructs Earthly to keep file ownership information.
--if-exists
Only save artifacts if they exists; if not, earthly will simply ignore the SAVE ARTIFACT command and won't treat any missing sources as failures.
--force
Force save operations which may be unsafe, such as writing to (or overwriting) a file or directory on the host filesystem located outside of the context of the directory containing the Earthfile.
Examples
Assuming the following directory tree, of a folder named test:
1
test
2
  └── file
Copied!
Here is how the following SAVE ARTIFACT ... AS LOCAL commands will behave:
1
WORKDIR base
2
COPY test .
3
​
4
# This will copy the base folder into the output directory.
5
# You would find file at out-dot/base/file.
6
SAVE ARTIFACT . AS LOCAL out-dot/
7
​
8
# This will copy the contents of the base folder into the output directory.
9
# You would find sub-file at out-glob/file. Note the base directory is not in the output.
10
SAVE ARTIFACT ./* AS LOCAL out-glob/
Copied!
For detailed examples demonstrating how other scenarios may function, please see our test suite.
SAVE IMAGE
Synopsis
SAVE IMAGE [--cache-from=<cache-image>] [--push] <image-name>... (output form)
SAVE IMAGE --cache-hint (cache hint form)
Description
In the output form, the command SAVE IMAGE marks the current build environment as the image of the target and assigns an output image name.
In the cache hint form, it instructs Earthly that the current target should be included as part of the explicit cache. For more information see the shared caching guide.
Options
--push
The --push options marks the image to be pushed to an external registry after it has been loaded within the docker daemon available on the host.
If inline caching is enabled, the --push option also instructs Earthly to use the specified image names as cache sources.
The actual push is not executed by default. Add the --push flag to the earthly invocation to enable pushing. For example
1
earthly --push +docker-image
Copied!
--cache-from=<cache-image>
Adds additional cache sources to be used when --use-inline-cache is enabled. For more information see the shared caching guide.
--cache-hint
Instructs Earthly that the current target should be included as part of the explicit cache. For more information see the shared caching guide.
BUILD
Synopsis
BUILD [--platform <platform>] [--allow-privileged] <target-ref> [--<build-arg-name>=<build-arg-value>...]
Description
The command BUILD instructs Earthly to additionally invoke the build of the target referenced by <target-ref>, where <target-ref> follows the rules defined by target referencing. The invocation will mark any images, or artifacts saved by the referenced target for local output (assuming local output is enabled), and any push commands issued by the referenced target for pushing (assuming pushing is enabled).
What is being output and pushed
In Earthly v0.6+, what is being output and pushed is determined either by the main target being invoked on the command-line directly, or by targets directly connected to it via a chain of BUILD calls. Other ways to reference a target, such as FROM, COPY, WITH DOCKER --load etc, do not contribute to the final set of outputs or pushes.
If you are referencing a target via some other command, such as COPY and you would like for the outputs or pushes to be included, you can issue an equivalent BUILD command in addition to the COPY. For example
1
my-target:
2
    COPY --platform=linux/amd64 (+some-target/some-file.txt --FOO=bar) ./
Copied!
Should be amended with the following additional BUILD call:
1
my-target:
2
    BUILD --platform=linux/amd64 +some-target --FOO=bar
3
    COPY --platform=linux/amd64 (+some-target/some-file.txt --FOO=bar) ./
Copied!
This, however, assumes that the target +my-target is itself connected via a BUILD chain to the main target being built. If that is not the case, additional BUILD commands should be issued higher up the hierarchy.
Options
--<build-arg-key>=<build-arg-value>
Sets a value override of <build-arg-value> for the build arg identified by <build-arg-key>.
The override value of a build arg may be a constant string
1
--SOME_ARG="a constant value"
Copied!
or an expression involving other build args
1
--SOME_ARG="a value based on other args, like $ANOTHER_ARG and $YET_ANOTHER_ARG"
Copied!
or a dynamic expression, based on the output of a command executed in the context of the build environment.
1
--SOME_ARG=$(find /app -type f -name '*.php')
Copied!
Dynamic expressions are delimited by $(...).
--platform <platform>
Specifies the platform to build on.
This flag may be repeated in order to instruct the system to perform the build for multiple platforms. For example
1
build-all-platforms:
2
    BUILD --platform=linux/amd64 --platform=linux/arm/v7 +build
Copied!
For more information see the multi-platform guide.
--allow-privileged
Same as FROM --allow-privileged.
--build-arg <build-arg-key>=<build-arg-value> (deprecated)
This option is deprecated. Please use --<build-arg-key>=<build-arg-value> instead.
VERSION
Synopsis
VERSION [options...] <version-number>
Description
The command VERSION identifies which set of features to enable in Earthly while handling the corresponding Earthfile. The VERSION command is currently optional; however will become mandatory in a future version of Earthly. When specified, VERSION must be the first command in the Earthfile.
Version number
enabled features
0.5
initial functionality will be preserved
0.6
--use-copy-include-patterns --referenced-save-only --for-in --require-force-for-unsafe-saves --no-implicit-ignore
Options
Individual features may be enabled by setting the corresponding feature flag. New features start off as experimental, which is why they are disabled by default. Once a feature reaches maturity, it will be enabled by default under a new version number.
All features are described in the version-specific features reference.
GIT CLONE
Synopsis
GIT CLONE [--branch <git-ref>] [--keep-ts] <git-url> <dest-path>
Description
The command GIT CLONE clones a git repository from <git-url>, optionally referenced by <git-ref>, into the build environment, within the <dest-path>.
In contrast to an operation like RUN git clone <git-url> <dest-path>, the command GIT CLONE is cache-aware and correctly distinguishes between different git commit IDs when deciding to reuse a previous cache or not. In addition, GIT CLONE can also use Git authentication configuration passed on to earthly, whereas RUN git clone would require additional secrets passing, if the repository is not publicly accessible.
Options
--branch <git-ref>
Points the HEAD to the git reference specified by <git-ref>. If this option is not specified, then the remote HEAD is used instead.
--keep-ts
Instructs Earthly to not overwrite the file creation timestamps with a constant.
FROM DOCKERFILE
Synopsis
FROM DOCKERFILE [options...] <context-path>
Description
The FROM DOCKERFILE command initializes a new build environment, inheriting from an existing Dockerfile. This allows the use of Dockerfiles in Earthly builds.
The <context-path> is the path where the Dockerfile build context exists. By default, it is assumed that a file named Dockerfile exists in that directory. The context path can be either a path on the host system, or an artifact reference, pointing to a directory containing a Dockerfile.
Options
-f <dockerfile-path>
Specify an alternative Dockerfile to use. The <dockerfile-path> can be either a path on the host system, relative to the current Earthfile, or an artifact reference pointing to a Dockerfile.
It is possible to split the Dockerfile and the build context across two seperate artifact references:
1
FROM alpine
2
​
3
mybuildcontext:
4
    WORKDIR /mydata
5
    RUN echo mydata > myfile
6
    SAVE ARTIFACT /mydata
7
​
8
mydockerfile:
9
    RUN echo "
10
FROM busybox
11
COPY myfile .
12
RUN cat myfile" > Dockerfile
13
    SAVE ARTIFACT Dockerfile
14
​
15
docker:
16
    FROM DOCKERFILE -f +mydockerfile/Dockerfile +mybuildcontext/mydata/*
17
    SAVE IMAGE testimg:latest
Copied!
Note that +mybuildcontext/mydata on its own would copy the directory and its contents; where as +mybuildcontext/mydata/* is required to copy all of the contents from within the mydata directory ( without copying the wrapping mydata directory).
If both the Dockerfile and build context are inside the same target, one must reference the same target twice, e.g. FROM DOCKERFILE -f +target/dir/Dockerfile +target/dir.
--build-arg <key>=<value>
Sets a value override of <value> for the Dockerfile build arg identified by <key>. This option is similar to the docker build --build-arg <key>=<value> option.
--target <target-name>
In a multi-stage Dockerfile, sets the target to be used for the build. This option is similar to the docker build --target <target-name> option.
--platform <platform>
Specifies the platform to build on.
For more information see the multi-platform guide.
WITH DOCKER
Synopsis
1
WITH DOCKER [--pull <image-name>] [--load <image-name>=<target-ref>] [--compose <compose-file>]
2
            [--service <compose-service>] [--allow-privileged]
3
  <commands>
4
  ...
5
END
Copied!
Description
The clause WITH DOCKER initializes a Docker daemon to be used in the context of a RUN command. The Docker daemon can be pre-loaded with a set of images using options such as -pull and --load. Once the execution of the RUN command has completed, the Docker daemon is stopped and all of its data is deleted, including any volumes and network configuration. Any other files that may have been created are kept, however.
The clause WITH DOCKER automatically implies the RUN --privileged flag.
The WITH DOCKER clause only supports the command RUN. Other commands (such as COPY) need to be run either before or after WITH DOCKER ... END. In addition, only one RUN command is permitted within WITH DOCKER. However, multiple shell commands may be stringed together using ; or &&.
A typical example of a WITH DOCKER clause might be:
1
FROM earthly/dind:alpine
2
WORKDIR /test
3
COPY docker-compose.yml ./
4
WITH DOCKER \
5
        --compose docker-compose.yml \
6
        --load image-name:latest=(+some-target --SOME_BUILD_ARG=value) \
7
        --load another-image-name:latest=+another-target \
8
        --pull some-image:latest
9
    RUN docker run ... && \
10
        docker run ... && \
11
        ...
12
END
Copied!
For more examples, see the Docker in Earthly guide and the Integration testing guide.
Note
For performance reasons, it is recommended to use a Docker image that already contains dockerd. If dockerd is not found, Earthly will attempt to install it.
Earthly provides officially supported images such as earthly/dind:alpine and earthly/dind:ubuntu to be used together with WITH DOCKER.
Options
--pull <image-name>
Pulls the Docker image <image-name> from a remote registry and then loads it into the temporary Docker daemon created by WITH DOCKER.
This option may be repeated in order to provide multiple images to be pulled.
Note
It is recommended that you avoid issuing RUN docker pull ... and use WITH DOCKER --pull ... instead. The classical docker pull command does not take into account Earthly caching and so it would redownload the image much more frequently than necessary.
--load <image-name>=<target-ref>
Builds the image referenced by <target-ref> and then loads it into the temporary Docker daemon created by WITH DOCKER. The image can be referenced as <image-name> within WITH DOCKER.
<target-ref> may be a simple target reference (+some-target), or a target reference with a build arg (+some-target --SOME_BUILD_ARG=value).
This option may be repeated in order to provide multiple images to be loaded.
The WITH DOCKER --load option does not mark any saved images or artifacts of the referenced target for local output, nor does it mark any push commands of the referenced target for pushing. For that, please use BUILD.
--compose <compose-file>
Loads the compose definition defined in <compose-file>, adds all applicable images to the pull list and starts up all applicable compose services within.
This option may be repeated, thus having the same effect as repeating the -f flag in the docker-compose command.
--service <compose-service>
Specifies which compose service to pull and start up. If no services are specified and --compose is used, then all services are pulled and started up.
This option can only be used if --compose has been specified.
This option may be repeated in order to specify multiple services.
--platform <platform>
Specifies the platform for any referenced --load and --pull images.
For more information see the multi-platform guide.
--allow-privileged
Same as FROM --allow-privileged.
--build-arg <key>=<value> (deprecated)
This option is deprecated. Please use --load <image-name>=(<target-ref> --<build-arg-key>=<build-arg-value>) instead.
IF
Synopsis
1
IF [<condition-options>...] <condition>
2
  <if-block>
3
END
Copied!
1
IF [<condition-options>...] <condition>
2
  <if-block>
3
ELSE
4
  <else-block>
5
END
Copied!
1
IF [<condition-options>...] <condition>
2
  <if-block>
3
ELSE IF [<condition-options>...] <condition>
4
  <else-if-block>
5
...
6
ELSE
7
  <else-block>
8
END
Copied!
Description
The IF clause can perform varying commands depending on the outcome of one or more conditions. The expression passed as part of <condition> is evaluated by running it in the build environment. If the exit code of the expression is zero, then the block of that condition is executed. Otherwise, the control continues to the next ELSE IF condition (if any), or if no condition returns a non-zero exit code, the control continues to executing the <else-block>, if one is provided.
A very common pattern is to use the POSIX shell [ ... ] conditions. For example the following marks port 8080 as exposed if the file ./foo exists.
1
IF [ -f ./foo ]
2
  EXPOSE 8080
3
END
Copied!
Note
Performing a condition requires that a FROM (or a from-like command, such as LOCALLY) has been issued before the condition itself.
For example, the following is NOT a valid Earthfile.
1
# NOT A VALID EARTHFILE.
2
ARG base=alpine
3
IF [ "$base" = "alpine" ]
4
    FROM alpine:3.15
5
ELSE
6
    FROM ubuntu:20.04
7
END
Copied!
The reason this is invalid is because the IF condition is actually running the /usr/bin/[ executable to test if the condition is true or false, and therefore requires that a valid build environment has been initialized.
Here is how this might be fixed.
1
ARG base=alpine
2
FROM busybox
3
IF [ "$base" = "alpine" ]
4
    FROM alpine:3.15
5
ELSE
6
    FROM ubuntu:20.04
7
END
Copied!
By initializing the build environment with FROM busybox, the IF condition can execute on top of the busybox image.
Important
Changes to the filesystem in any of the conditions are not preserved. If a file is created as part of a condition, then that file will not be present in the build environment for any subsequent commands.
Options
--privileged
Same as RUN --privileged.
--ssh
Same as RUN --ssh.
--no-cache
Same as RUN --no-cache.
--mount <mount-spec>
Same as RUN --mount <mount-spec>.
--secret <env-var>=<secret-ref>
Same as RUN --secret <env-var>=<secret-ref>.
FOR
Enable via VERSION 0.6.
Synopsis
1
FOR [<options>...] <variable-name> IN <expression>
2
  <for-block>
3
END
Copied!
Description
The FOR clause can iterate over the items resulting from the expression <expression>. On each iteration, the value of <variable-name> is set to the current item in the iteration and the block of commands <for-block> is executed in the context of that variable set as a build arg.
The expression may be either a constant list of items (e.g. foo bar buz), or the output of a command (e.g. $(echo foo bar buz)), or a parameterized list of items (e.g. foo $BARBUZ). The result of the expression is then tokenized using the list of separators provided via the --sep option. If unspecified, the separator list defaults to [tab], [new line] and [space] (\t\n ).
Important
Changes to the filesystem in expressions are not preserved. If a file is created as part of a FOR expression, then that file will not be present in the build environment for any subsequent commands.
Examples
As an example, FOR may be used to iterate over a list of files for compilation
1
FOR file IN $(ls)
2
  RUN gcc "${file}" -o "${file}.o" -c
3
END
Copied!
As another example, FOR may be used to iterate over a set of directories in a monorepo and invoking targets within them.
1
FOR dir IN $(ls -d */)
2
  BUILD "./$dir+build"
3
END
Copied!
Options
--sep <separator-list>
The list of separators to use when tokenizing the output of the expression. If unspecified, the separator list defaults to [tab], [new line] and [space] (\t\n ).
--privileged
Same as RUN --privileged.
--ssh
Same as RUN --ssh.
--no-cache
Same as RUN --no-cache.
--mount <mount-spec>
Same as RUN --mount <mount-spec>.
--secret <env-var>=<secret-ref>
Same as RUN --secret <env-var>=<secret-ref>.
LOCALLY
Synopsis
LOCALLY
Description
The LOCALLY command can be used in place of a FROM command, which will cause earthly to execute all commands under the target directly on the host system, rather than inside a container. Commands within a LOCALLY target will never be cached. This feature should be used with caution as locally run commands have no guarantee they will behave the same on different systems.
Only RUN commands are supported under a LOCALLY defined target; furthermore only RUN's --push flag is supported.
RUN commands have access to the environment variables which are exposed to the earthly command; however, the commands are executed within a working directory which is set to the location of the referenced Earthfile and not where the earthly command is run from.
For example, the following Earthfile will display the current user, hostname, and directory where the Earthfile is stored:
1
whoami:
2
    LOCALLY
3
    RUN echo "I am currently running under $USER on $(hostname) under $(pwd)"
Copied!
Note
In Earthly, outputting images and artifacts locally takes place only at the end of a successful build. In order to use such images or artifacts in LOCALLY targets, they need to be referenced correctly.
For images, use the --load option under WITH DOCKER:
1
my-image:
2
    FROM alpine 3.13
3
    ...
4
    SAVE IMAGE my-example-image
5
​
6
a-locally-example:
7
    LOCALLY
8
    WITH DOCKER --load=+my-image
9
        RUN docker run --rm my-example-image
10
    END
Copied!
Do NOT use BUILD for using images in LOCALLY targets:
1
# INCORRECT - do not use!
2
my-image:
3
    FROM alpine 3.13
4
    ...
5
    SAVE IMAGE my-example-image
6
​
7
a-locally-example:
8
    LOCALLY
9
    BUILD +my-image
10
    # The image will not be available here because the local export of the
11
    # image only takes place at the end of an entire successful build.
12
    RUN docker run --rm my-example-image
Copied!
For artifacts, use COPY, the same way you would in a regular target:
1
my-artifact:
2
    FROM alpine 3.13
3
    ...
4
    SAVE ARTIFACT ./my-example-artifact
5
​
6
a-locally-example:
7
    LOCALLY
8
    COPY +my-artifact/my-example-artifact ./
9
    RUN cat ./my-example-artifact
Copied!
Do NOT use SAVE ARTIFACT ... AS LOCAL and BUILD for referencing artifacts in LOCALLY targets:
1
# INCORRECT - do not use!
2
my-artifact:
3
    FROM alpine 3.13
4
    ...
5
    SAVE ARTIFACT ./my-example-artifact AS LOCAL ./my-example-artifact
6
​
7
a-locally-example:
8
    LOCALLY
9
    BUILD +my-artifact
10
    # The artifact will not be available here because the local export of the
11
    # artifact only takes place at the end of an entire successful build.
12
    RUN cat ./my-example-artifact
Copied!
COMMAND
Synopsis
COMMAND
Description
The command COMMAND marks the beginning of a user-defined command (UDC) definition. UDCs are templates (much like functions in regular programming languages), which can be used to define a series of steps to be executed in sequence. In order to reference and execute a UDC, you may use the command DO.
Unlike performing a BUILD +target, UDCs inherit the build context and the build environment from the caller.
UDCs create their own ARG scope, which is distinct from the caller. Any ARG that needs to be passed from the caller needs to be passed explicitly via DO +COMMAND --<build-arg-key>=<build-arg-value>.
Global imports and global args are inherited from the base target of the same Earthfile where the command is defined in (this may be distinct from the base target of the caller).
For more information see the User-defined commands guide.
DO
Synopsis
DO [--allow-privileged] <command-ref> [--<build-arg-key>=<build-arg-value>...]
Description
The command DO expands and executes the series of commands contained within a user-defined command (UDC) referenced by <command-ref>.
Unlike performing a BUILD +target, UDCs inherit the build context and the build environment from the caller.
UDCs create their own ARG scope, which is distinct from the caller. Any ARG that needs to be passed from the caller needs to be passed explicitly via DO +COMMAND --<build-arg-key>=<build-arg-value>.
For more information see the User-defined commands guide.
Options
--allow-privileged
Same as FROM --allow-privileged.
IMPORT
Synopsis
IMPORT [--allow-privileged] <project-ref> [AS <alias>]
Description
The command IMPORT aliases a project reference (<project-ref>) that can be used in subsequent target, artifact or command references.
If not provided, the <alias> is inferred automatically as the last element of the path provided in <project-ref>. For example, if <project-ref> is github.com/foo/bar/buz:v1.2.3, then the alias is inferred as buz.
The <project-ref> can be a reference to any directory other than .. If the reference ends in .., then mentioning AS <alias> is mandatory.
If an IMPORT is defined in the base target of the Earthfile, then it becomes a global IMPORT and it is made available to every other target or command in that file, regardless of their base images used.
For more information see the target, artifact and command references guide.
Options
--allow-privileged
Similar to FROM --allow-privileged, extend the ability to request privileged capabilities to all invocations of the imported alias.
CMD (same as Dockerfile CMD)
Synopsis
CMD ["executable", "arg1", "arg2"] (exec form)
CMD ["arg1, "arg2"] (as default arguments to the entrypoint)
CMD command arg1 arg2 (shell form)
Description
The command CMD sets default arguments for an image, when executing as a container. It works the same way as the Dockerfile CMD command.
LABEL (same as Dockerfile LABEL)
Synopsis
LABEL <key>=<value> <key>=<value> ...