> For the complete documentation index, see [llms.txt](https://docs.earthbuild.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.earthbuild.dev/docs/guides/secrets.md).

# Secrets

Secrets are sensitive data that should not be stored in the Earthfile. For example, a password or an API key. Secrets are similar to build arguments, but they are not stored in the Earthfile and are not cached.

Access to secrets is declared explicitly in the commands that need them.

## Passing secrets to RUN commands

Here's an example Earthfile that accesses a secret stored under `passwd` and exposes it under the environment variable `mypassword`:

```dockerfile
FROM alpine:latest
hush:
    RUN --secret mypassword=passwd echo "my password is $mypassword"
```

If the environment variable name is identical to the secret ID. For example to accesses a secret stored under `passwd` and exposes it under the environment variable `passwd` you can use the shorthand :

```dockerfile
FROM alpine:latest
hush:
    RUN --secret passwd echo "my password is $passwd"
```

{% hint style="info" %}
It's also possible to temporarily mount a secret as a file:

```dockerfile
RUN --mount type=secret,target=/root/mypassword,id=passwd echo "my password is $(cat /root/mypassword)"
```

The file will not be saved to the image snapshot.
{% endhint %}

## Setting secret values

The value for `passwd` in examples above must then be supplied when earth is invoked.

This is possible in a few ways:

1. Directly, on the command line:

   ```bash
   earth --secret passwd=itsasecret +hush
   ```
2. Via an environment variable:

   ```bash
   export passwd=itsasecret
   earth --secret passwd +hush
   ```

   If the value of the secret is omitted on the command line EarthBuild will lookup the environment variable with that name.
3. Via the environment variable `EARTH_SECRETS`

   ```bash
   export EARTH_SECRETS="passwd=itsasecret"
   earth +hush
   ```

   Multiple secrets can be specified by separating them with a comma.
4. Via the `.secret` file.

   Create a `.secret` file in the same directory where you plan to run `earth` from. Its contents should be:

   ```
   passwd=itsasecret
   ```

   Then simply run earth:

   ```bash
   earth +hello
   ```
5. Via your own secret manager. To share secrets across a team, fetch them from a system you control (for example HashiCorp Vault, AWS Secrets Manager, or your CI provider's secret store) and pass them in using one of the approaches above.

Regardless of the approach chosen from above, once earth is invoked, in our example, it will output:

```
+hush | --> RUN echo "my password is $mypassword"
+hush | my password is itsasecret
```

{% hint style="info" %}

### How Arguments and Secrets affect caching

Commands in earth must be re-evaluated when the command itself changes (e.g. `echo "hello $name"` is changed to `echo "greetings $name"`), or when one of its inputs has changed (e.g. `--name=world` is changed to `--name=banana`). EarthBuild creates a hash based on both the contents of the command and the contents of all defined arguments of the target build context.

However, in the case of secrets, the contents of the secret *is not* included in the hash; therefore, if the contents of a secret changes, EarthBuild is unable to detect such a change, and thus the command will not be re-evaluated.
{% endhint %}

## Storage of local secrets

EarthBuild stores the contents of command-line-supplied secrets in memory on the localhost. When a `RUN` command that requires a secret is evaluated by BuildKit, the BuildKit daemon will request the secret from the earth command-line process and will temporarily mount the secret inside the runc container that is evaluating the `RUN` command. Once the command finishes the secret is unmounted. It will not persist as an environment variable within the saved container snapshot. Secrets will be kept in-memory until the earth command exits.

Secrets are never written to disk by EarthBuild, and never leave the machine running the build.

{% hint style="info" %}
**Cloud-based secrets have been removed**

Earthly previously offered a hosted secret store, managed with `earthly secret set ...`. That service and the `secret`/`secrets` commands were removed as part of the cloud teardown and are not part of EarthBuild. To share secrets across a team, fetch them from a secret manager you control and pass them in via `--secret`, `--secret-file-path`, or the environment. See [Migrating from Earthly](https://docs.earthbuild.dev/migrating-from-earthly.md) for the full list of removed commands.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.earthbuild.dev/docs/guides/secrets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
