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

Aetherfy refuses the deletion while the workspace still holds resources. Both preconditions are checked before anything is removed:

Once both hold, deletion removes the workspace record and its workspace-scoped secrets:

The collections precondition is the one that surprises people, because an empty-looking workspace in the agents view can still be holding collections. Delete those through the vector API or SDKs first — 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 create and none on afy deploy. An Aetherfy agent joins a workspace in one of two ways:

# 1. Assign an existing agent
afy 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 update <name> --no-workspace. Passing --workspace "" is rejected.

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