afy workspaces

The afy workspaces command group in the Aetherfy CLI

An Aetherfy workspace groups agents so they can share secrets, share vector collections, and reach each other over HTTP. The command group has two aliases, workspace and ws.

Creating an Aetherfy workspace

afy workspaces create <name> creates a workspace. It takes exactly one positional argument.

afy workspaces create research
afy workspaces create research -d "Shared retrieval corpus and scrapers"

Aetherfy enforces the name rules server-side:

Valid: research, sales-ops, team-2. Invalid: Research (uppercase), -research (leading hyphen), ab (too short).

Listing Aetherfy workspaces

afy workspaces list prints every workspace in the account. It takes no arguments and no flags of its own.

afy workspaces list
afy workspaces list -o json

Note that on an empty result afy workspaces list prints a text message even under -o json. Scripts against Aetherfy must handle that case rather than assuming valid JSON on every run.

Inspecting an Aetherfy workspace

afy workspaces info <name> prints one workspace in detail. It takes one positional argument and no flags of its own.

afy workspaces info research
afy workspaces info research -o json

Fields printed: ID, Name, Description, Agents, Created, Updated.

Updating an Aetherfy workspace description

afy workspaces update <name> changes the workspace description.

--description is required; running afy workspaces update without it is an error.

# Set a description
afy workspaces update research -d "Retrieval corpus, scrapers, and evaluators"
 
# Clear it
afy workspaces update research -d ""

The description is the only mutable field. Aetherfy workspace names are immutable after creation — there is no rename. To change a name, delete the workspace and recreate it under the new name, then reassign the agents with afy agents update <agent> --workspace <new-name>.

Deleting an Aetherfy workspace

afy workspaces delete <name> deletes a workspace.

Without --force the Aetherfy CLI asks for confirmation and requires you to type the workspace name exactly.

afy workspaces delete research
afy workspaces delete research --force

What deletion does and does not touch:

The vector collections surviving a workspace deletion is deliberate and worth planning for: they continue to exist and continue to count against your Aetherfy storage. Remove them through the vector API or SDKs — see /vectors.

Listing the agents in an Aetherfy workspace

afy workspaces agents <workspace> lists the agents assigned to a workspace. It takes one positional argument and no flags of its own.

afy workspaces agents research
afy workspaces agents research -o json

Like afy workspaces list, this command prints text on an empty result even under -o json.

How Aetherfy agents join and use a workspace

There is no --workspace flag on afy agents create and none on afy deploy. An Aetherfy agent joins a workspace in one of two ways:

# 1. Assign an existing agent
afy agents update catalogue-scraper --workspace research
 
# 2. Or declare it in aetherfy.yaml before deploying

workspace: research

To remove an agent from a workspace, run afy agents update <name> --no-workspace. Passing --workspace "" is rejected.

Agents that share an Aetherfy workspace can reach each other over HTTP: for each sibling agent, Aetherfy injects an environment variable named AETHERFY_AGENT_<NAME>_URL holding that agent’s URL. This is why the AETHERFY_ prefix is reserved and cannot be used for your own secret keys — see /cli/secrets.