<target-ref>
(target form and image form) or <artifact-ref>
(artifact form). In the target form, the referenced target and its dependencies are built. In the artifact form, the referenced artifact and its dependencies are built, but only the specified artifact is output. The output path of the artifact can be optionally overridden by <dest-path>
. In the image form, the image produced by the referenced target and its dependencies are built, but only the specified image is output.--buildkit-host
is not specified, this command also starts up a container named earthly-buildkitd
to act as a build daemon.RUN --push
commands. During the local output phase, all applicable artifacts with an AS LOCAL
specification are written to the specified output location, and all applicable docker images are loaded onto the host's docker daemon.<target-ref>
can reference both local and remote targets.+<target-name>
will reference a target in the local Earthfile in the current directory.<local-path>+<target-name>
will reference a local Earthfile in a different directory as specified by <local-path>
, which must start with ./
, ../
, or /
.<gitvendor>/<namespace>/<project>/path/in/project[:some-tag]+<target-name>
will access a remote git repository.<artifact-ref>
can reference artifacts built by targets. <target-ref>/<artifact-path>
will reference a build target's artifact.earthly <target-ref> [--<build-arg-key>=<build-arg-value>...]
earthly --artifact (<target-ref>/<artifact-path> [--<build-arg-key>=<build-arg-value>...]) <dest-path>
earthly --image <target-ref> [--<build-arg-key>=<build-arg-value>...]
EARTHLY_BUILD_ARGS="<build-arg-key>=<build-arg-value>,<build-arg-key>=<build-arg-value>,..."
.<build-arg-key>
is set to <build-arg-value>
.earthly +some-target --NAME=john --SPECIES=human
. In the artifact form, the build args are passed immediately after the artifact reference, however they are surrounded by paranthesis, similar to a COPY
command. For example earthly --artifact (+some-target/some-artifact --NAME=john --SPECIES=human) ./dest/path/
..env
, if one exists in the current directory. The syntax of the .env
file is of the form#
are treated as comments. Blank lines are allowed. Here is a simple example:.env
file is the directory where earthly
is called from and not necessarily the directory where the Earthfile is located in..env
file are loaded by earthly
in three distinct ways:earthly
itself - the settings are loaded if they match the environment variable equivalent of an earthly
option..env
file is meant for settings which are specific to the local environment the build executes in. These settings may cause inconsistencies in the way the build executes on different systems, leading to builds that are difficult to reproduce. Keep the contents of .env
files to a minimum to avoid such issues.--config <path>
EARTHLY_CONFIG=<path>
.--ssh-auth-sock <path-to-sock>
EARTHLY_SSH_AUTH_SOCK=<path-to-sock>
.SSH_AUTH_SOCK
env var is already set if an SSH agent is running./run/host-services/ssh-auth.sock
to match recommendation in the official Docker documentation.--auth-token <value>
EARTHLY_TOKEN=<value>
.--verbose
EARTHLY_VERBOSE=1
.--git-username <git-user>
(deprecated)GIT_USERNAME=<git-user>
.--git-password <git-pass>
(deprecated)GIT_PASSWORD=<git-pass>
.--git-url-instead-of <git-instead-of>
(obsolete)GIT_URL_INSTEAD_OF=<git-instead-of>
.earthly
will automatically switch from ssh to HTTPS when no keys are found or the ssh-agent isn't running. Please use the configuration file to override the default behavior.--secret|-s <secret-id>[=<value>]
EARTHLY_SECRETS="<secret-id>=<value>,<secret-id>=<value>,..."
.<secret-id>
to the build environments. If <value>
is not specified, then the value becomes the value of the environment variable with the same name as <secret-id>
.RUN --secret <arbitrary-env-var-name>=+secrets/<secret-id>
. For more information see the RUN --secret
Earthfile command.--secret-file <secret-id>=<path>
EARTHLY_SECRET_FILES="<secret-id>=<path>,<secret-id>=<path>,..."
.<path>
into a secret with ID <secret-id>
for use within the build environments.RUN --secret <arbitrary-env-var-name>=+secrets/<secret-id>
. For more information see the RUN --secret
Earthfile command.--push
EARTHLY_PUSH=true
.--push
flag to remote docker registries and to run any RUN --push
commands. For more information see the SAVE IMAGE
Earthfile command and the RUN --push
Earthfile command.--no-output
EARTHLY_NO_OUTPUT=true
.--output
EARTHLY_OUTPUT=true
.--no-cache
EARTHLY_NO_CACHE=true
.--allow-privileged|-P
EARTHLY_ALLOW_PRIVILEGED=true
.RUN --privileged
command.--use-inline-cache
EARTHLY_USE_INLINE_CACHE=true
SAVE IMAGE --push
command is used to inform the system of possible inline cache sources. For more information see the shared caching guide.--save-inline-cache
EARTHLY_SAVE_INLINE_CACHE=true
--use-inline-cache
. For more information see the shared caching guide.--remote-cache <image-tag>
EARTHLY_REMOTE_CACHE=<image-tag>
<image-tag>
is used for storing and retrieving the cache to/from a Docker registry. Storing explicit cache is only enabled if the option --push
is also passed in. For more information see the shared caching guide.--max-remote-cache
EARTHLY_MAX_REMOTE_CACHE=true
--ci
EARTHLY_CI=true
--platform <platform>
EARTHLY_PLATFORMS=<platform>
.BUILD
command in your Earthfile:--build-arg <key>[=<value>]
(deprecated)earthly <target-ref> --<key>=<value>
.EARTHLY_BUILD_ARGS="<key>=<value>,<key>=<value>,..."
.<key>
. If <value>
is not specified, then the value becomes the value of the environment variable with the same name as <key>
. For more information see the ARG
Earthfile command.--interactive|-i
EARTHLY_INTERACTIVE=true
.RUN
command fails, earthly will display the error and exit. If the interactive mode is enabled and an error occurs, an interactive shell is presented which can be used for investigating the error interactively. Due to technical limitations, only a single interactive shell can be used on the system at any given time.--strict
NO_COLOR=1
disables the use of color.FORCE_COLOR=1
forces the use of color.EARTHLY_TARGET_PADDING=n
will set the column to the width of n
characters. If a name is longer than n
, its path will be truncated and remaining extra length will cause the column to go ragged.EARTHLY_FULL_TARGET=1
will always print the full target name, and leave the target name column ragged.earthly prune
eliminates Earthly cache. In the standard form it issues a prune command to the BuildKit daemon. In the reset form it restarts the BuildKit daemon, instructing it to completely delete the cache directory on startup, thus forcing it to start from scratch.--all|-a
--reset
~/.earthly/config.yml
. It does its best to preserve existing formatting and comments. [value]
must be a valid YAML literal for the given [key]
.--help
[key] --help
~/.earthly/auth.token
.key
is omitted, an interactive prompt is displayed to select a key to add.--write
flag is specified the token will have read+write access. The token will expire in 1 year from creation date unless a different date is supplied via the --expiry
option.<org-path>
can either be a top-level org access by granting permission on /<org-name>/
, or finer-grained access can be granted to a subpath e.g. /<org-name>/path/to/share/
. By default users are granted read-only access unless the --write
flag is given.-n
is given, no newline is printed after the contents of the secret.earthly
to function correctly. This command can be re-run to fix broken setups. It is recommended to run this with sudo.--no-buildkit
--with-autocomplete
sudo
to install them correctly.