Builtin args

Builtin args are variables with values automatically filled-in by Earthly.

The value of a builtin arg can never be overridden. However, you can always have an additional ARG, which takes as the default value, the value of the builtin arg. The additional arg can be overridden. Example

ARG EARTHLY_TARGET_TAG
ARG TAG=$EARTHLY_TARGET_TAG
SAVE IMAGE --push some/name:$TAG

{% hint style='danger' %}

Important

Earthly builtin args need to be pre-declared before they can be used. For example

ARG EARTHLY_TARGET
RUN echo "The current target is $EARTHLY_TARGET"

{% endhint %}

General args

Target-related args

Git-related args

Platform-related args

The default value of the TARGETPLATFORM arg is the native platform of the runner, for non-LOCALLY targets. This can be overriden by using the --platform flag, when using the earthly CLI. For example, earthly --platform linux/amd64 +my-target will set the TARGETPLATFORM arg to linux/amd64. You can also override the target platform in an Earthfile, when issuing BUILD commands. For example, BUILD --platform linux/amd64 +my-target. Or you can override the platform within the target definition by setting the platform in the FROM statement. For example FROM --platform linux/amd64 alpine:3.13.

Under LOCALLY, the TARGETPLATFORM arg is always set to the user platform (the environment the earthly binary is invoked from) and it is not overriden by the --platform flag.

{% hint style='info' %}

Note

Under LOCALLY targets, it is important to declare the TARGETPLATFORM arg after the LOCALLY command, to ensure that it gets the approriate user platform value. For example:

my-target:
    LOCALLY
    ARG TARGETPLATFORM
    RUN echo "The target platform under LOCALLY is $TARGETPLATFORM"

{% endhint %}