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:
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.
Listing secret files shows paths and update times only — never the decrypted contents.
Uploading a File
The aether secret command manages secret files (aliases: secrets, secret-file, secret-files).
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:
The CLI accepts regular UTF-8 files up to 1 MiB and rejects symlinks and special files.
Listing Files
Reading a File
Prints the decrypted contents to stdout.
Deleting a File
Pass --force to skip the confirmation prompt.
Bulk Upload
Upload every file in a local directory as secret files in one call:
Files keep their paths relative to the directory you point at. Add --prefix to nest them under a path inside the workspace:
API Endpoints
Secret files are also available through the REST API. See the API reference for request and response shapes:
