> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret Files

> Store encrypted files that are materialized into the workspace at task start

Secret files are arbitrary, project-relative files — a `.env`, a service-account JSON, a TLS certificate — stored encrypted and written into your workspace when a task starts. Use them when a tool expects an actual file on disk rather than a value in the environment.

## Secret Files vs Environment Variables

These are two separate features. Pick by where your tooling expects the value:

|              | [Environment variables](/guides/environment-variables) | Secret files                               |
| ------------ | ------------------------------------------------------ | ------------------------------------------ |
| Shape        | Key/value pairs                                        | Whole files                                |
| Delivered as | Injected into the agent's process environment          | Written to disk in the project directory   |
| Managed with | `aether env`                                           | `aether secret`                            |
| Use for      | `DATABASE_URL`, API keys read from `process.env`       | `.env` files, certs, JSON credential files |

## How It Works

Each secret file is stored encrypted at rest against your project. When a task starts, the file is decrypted and written into the project working directory (`PROJECT_CWD`) inside the workspace VM with owner-only permissions (`0600`).

Paths are project-relative. A path must not be absolute and must not contain `..`. Nested paths are allowed — `config/service-account.json` lands at `config/service-account.json` under the project root.

<Warning>
  Listing secret files shows paths and update times only — never the decrypted contents.
</Warning>

## Uploading a File

The `aether secret` command manages secret files (aliases: `secrets`, `secret-file`, `secret-files`).

```bash theme={null}
aether secret upload .env --from .env
```

The first argument is the path the file will have inside the workspace; `--from` is the local file to read. You can also pipe content on stdin, in which case the local file is not needed:

```bash theme={null}
cat service-account.json | aether secret upload config/service-account.json
```

If you omit both `--from` and stdin, the CLI reads the local file at the same path as the argument.

## Listing Files

```bash theme={null}
aether secret list
```

```
PATH                          UPDATED
.env                          5 minutes ago
config/service-account.json   2 days ago
```

## Reading a File

```bash theme={null}
aether secret get .env
```

Prints the decrypted contents to stdout.

## Deleting a File

```bash theme={null}
aether secret delete .env
```

Pass `--force` to skip the confirmation prompt.

## Bulk Upload

Upload every file in a local directory as secret files in one call:

```bash theme={null}
aether secret bulk-upload ./secrets
```

Files keep their paths relative to the directory you point at. Add `--prefix` to nest them under a path inside the workspace:

```bash theme={null}
aether secret bulk-upload ./secrets --prefix config
```

## API Endpoints

Secret files are also available through the REST API. See the API reference for request and response shapes:

* [List secret files](/api-reference/v1/secret-files/get-projects-by-id-secret-files)
* [Upload a secret file](/api-reference/v1/secret-files/post-projects-by-id-secret-files)
* [Bulk upload](/api-reference/v1/secret-files/post-projects-by-id-secret-files-bulk)
* [Get a secret file](/api-reference/v1/secret-files/get-projects-by-id-secret-files-by-file-key)
* [Delete a secret file](/api-reference/v1/secret-files/delete-projects-by-id-secret-files-by-file-key)