Skip to Content
CLIafy secrets
Raw

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.

SubcommandPurpose
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:

ScopeHow to select it
Agent-scopedPass the agent name as the first positional argument
Workspace-scopedPass --workspace <name> / -w <name> instead

Listing Aetherfy secrets

afy secrets list [agent] lists the secret keys in a scope.

FlagShortTypeDefaultDescription
--workspace-wstringemptyWorkspace 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 --json

The 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.

FlagShortTypeDefaultDescription
--workspace-wstringemptyWorkspace name (for workspace-scoped secrets)
--stdinboolfalseRead secret value from stdin

Argument parsing depends on the scope, which is the one genuinely confusing part of this Aetherfy command:

ScopePositional arguments
Without --workspaceThe first argument is the agent name; every argument after it is a KEY=value pair
With --workspaceAll 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=abc123

Malformed 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 --stdin

Setting 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.

FlagShortTypeDefaultDescription
--workspace-wstringemptyWorkspace name (for workspace-scoped secrets)
--yes-yboolfalseDelete 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 --yes

Without --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.

SituationResult
Key exists only on the workspaceThe workspace value is injected
Key exists only on the agentThe agent value is injected
Key exists on bothThe 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

PropertyBehaviour
StorageEncrypted at rest with AES-256 by Aetherfy
DeliveryInjected as environment variables when a machine is created, and kept for that machine’s life
ReadbackNever — no Aetherfy command or API returns a secret value
PropagationChanging a secret does not redeploy or restart a running agent
Read failureA 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 deploy

Note 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.

Last updated on