> ## 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={"dark"}
aether secret upload .env
```

The first argument is both the local path and the path the file will have inside the workspace. Use `--from <file>` when the local path differs. To pipe content, opt in explicitly with `--stdin`:

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

The CLI accepts regular UTF-8 files up to 1 MiB and rejects symlinks and special files.

## Listing Files

```bash theme={"dark"}
aether secret list
```

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

## Reading a File

```bash theme={"dark"}
aether secret get .env
```

Prints the decrypted contents to stdout.

## Deleting a File

```bash theme={"dark"}
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={"dark"}
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={"dark"}
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)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.