afy secrets
The afy secrets command group in the Aetherfy CLI
afy secrets manages encrypted configuration values for Aetherfy agents. The
group has two aliases, secret and s.
| Subcommand | Purpose |
|---|---|
afy secrets list [agent] | List secret keys (never values) |
afy secrets set [agent] <KEY=value>... | Create or replace secrets |
afy secrets delete [agent] <key> | Delete one secret |
Every subcommand works in one of two scopes:
| Scope | How to select it |
|---|---|
| Agent-scoped | Pass the agent name as the first positional argument |
| Workspace-scoped | Pass --workspace <name> / -w <name> instead |
Listing Aetherfy secrets
afy secrets list [agent] lists the secret keys in a scope.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--workspace | -w | string | empty | Workspace name (for workspace-scoped secrets) |
Provide an agent name or --workspace, not both.
# Agent-scoped
afy secrets list catalogue-scraper
# Workspace-scoped
afy secrets list --workspace research
# As JSON
afy secrets list catalogue-scraper --jsonThe table has three columns: Key, Created, Updated. Values are never returned
by Aetherfy — there is no command that reads a secret back. afy secrets list
prints [] for an empty result under --json.
Setting Aetherfy secrets
afy secrets set creates or replaces secrets. Setting an existing key
overwrites it.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--workspace | -w | string | empty | Workspace name (for workspace-scoped secrets) |
--stdin | bool | false | Read secret value from stdin |
Argument parsing depends on the scope, which is the one genuinely confusing part of this Aetherfy command:
| Scope | Positional arguments |
|---|---|
Without --workspace | The first argument is the agent name; every argument after it is a KEY=value pair |
With --workspace | All positional arguments are KEY=value pairs |
# Agent-scoped, several at once
afy secrets set catalogue-scraper OPENAI_API_KEY=sk-xxxx DB_URL=postgres://...
# Workspace-scoped — no agent argument
afy secrets set --workspace research SHARED_TOKEN=abc123Malformed pairs are reported and skipped; the Aetherfy CLI does not abort the
whole command because one argument lacks an =.
--stdin reads the value from standard input and requires exactly one key
name as the argument — a bare key, not a KEY=value pair. This keeps the
secret out of your shell history and out of the process list:
# Agent-scoped
printf '%s' "$OPENAI_KEY" | afy secrets set catalogue-scraper OPENAI_API_KEY --stdin
# Workspace-scoped
cat private.pem | afy secrets set --workspace research SIGNING_KEY --stdinSetting several secrets, and when some are refused
afy secrets set handles each KEY=value in turn and goes on after a refused one: an
invalid pair (Invalid format '<pair>'. Use KEY=value), an empty key, a key beginning
AETHERFY_ (reserved for the platform), or a key the server refuses. Each stored key
prints Secret '<KEY>' set, and each refusal prints its reason. If any pair was not
stored, the command exits 1 (not every secret was set).
With --json the command writes one document on stdout, even when it exits 1. This is
the one refusal where stdout is not empty, because the document says which keys landed:
{"scope": "agent", "target": "catalogue-scraper",
"secrets": [{"key": "OPENAI_API_KEY", "set": true},
{"key": "AETHERFY_X", "set": false, "error": "Key 'AETHERFY_X' is reserved for platform use. Names starting with AETHERFY_ are not allowed."}]}scope is agent or workspace, target the agent or workspace name, and each
entry in secrets has key, set, and, when it was refused by the server, its code
and error. A refusal raised by the CLI itself, such as a bad pair, has only an error.
Deleting an Aetherfy secret
afy secrets delete [agent] <key> removes a single secret.
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--workspace | -w | string | empty | Workspace name (for workspace-scoped secrets) |
--yes | -y | bool | false | Delete without asking |
With --workspace you pass only the key. Without it, you pass the agent name and
then the key.
# Agent-scoped
afy secrets delete catalogue-scraper OPENAI_API_KEY
# Workspace-scoped
afy secrets delete --workspace research SHARED_TOKEN
# From a script
afy secrets delete catalogue-scraper OPENAI_API_KEY --yesWithout --yes the command asks [y/N]. Any other answer cancels: it exits 1
with Cancelled, deletes nothing, and under --json writes an error document (code CLI_CANCELLED) on
stderr and nothing on stdout. Without a terminal the question cannot be answered,
so the command is refused before asking, with exit 2: This deletes secret '<key>' from agent '<agent>'; pass --yes to confirm without a prompt. (workspace '<workspace>' with --workspace).
How Aetherfy resolves secret scope and precedence
An Aetherfy agent sees the union of the secrets in its workspace and its own agent-scoped secrets.
| Situation | Result |
|---|---|
| Key exists only on the workspace | The workspace value is injected |
| Key exists only on the agent | The agent value is injected |
| Key exists on both | The agent-scoped value wins |
Agent-scoped secrets override workspace-scoped secrets with the same key. This is how a single Aetherfy agent overrides a shared workspace default without changing the workspace.
Reserved key names in Aetherfy secrets
Any key beginning with AETHERFY_, in any letter case, is reserved by the
platform and rejected. AETHERFY_API_KEY, aetherfy_region, and
Aetherfy_Anything are all refused.
The reservation exists because Aetherfy injects its own AETHERFY_-prefixed
variables into the agent environment — among them AETHERFY_WORKSPACE_ID, AETHERFY_SPAWN_URL
and AETHERFY_PEERS_URL, the template agents in a workspace use to look each other up. See
/cli/workspaces.
How Aetherfy delivers secrets to an agent
| Property | Behaviour |
|---|---|
| Storage | Encrypted at rest with AES-256 by Aetherfy |
| Delivery | Injected as environment variables when a machine is created, and kept for that machine’s life |
| Readback | Never — no Aetherfy command or API returns a secret value |
| Propagation | Changing a secret does not redeploy or restart a running agent |
| Read failure | A deploy that cannot read the secrets (after four attempts) fails with nothing built: “Couldn’t read this agent’s secrets, so it wasn’t deployed. Retry the deploy.” An agent is never deployed without them |
Because a change does not redeploy, a new value takes effect on the next
afy deploy. A type: job agent is the exception: Aetherfy records the secret
set each machine was created from and will not run on a machine whose set is out
of date, so the next run gets a new machine with the current values — correct,
but a cold start every run until you deploy. To pick up a rotated credential on a
running service agent, redeploy it:
afy secrets set catalogue-scraper OPENAI_API_KEY --stdin < newkey.txt
afy deployNote also that .env and .env.* files are excluded from every Aetherfy deploy
archive, so secrets must go through this command group rather than being shipped
as files. See /cli/deploy.