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, Regions, 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>.

Changing the regions an Aetherfy workspace allows

afy workspaces regions <name> changes the regions a workspace allows. A workspace’s regions are a ceiling on where its agents and collections may be placed, not a placement: adding a region copies nothing, and removing one is refused while an agent or a collection of the workspace still uses it. So the change copies and deletes no data, and asks nothing.

afy workspaces regions research --regions us-east-1,eu-central-1
afy workspaces regions research --regions us-east-1 --wait -o json

The change runs in the background, and afy workspaces info <name> shows the regions once it finishes. --wait follows it, as afy start --wait follows a start: exit 0 when it succeeds, 1 when it fails, and 4 when it is still running after 30 minutes. Asking for the regions the workspace already allows changes nothing and exits 0. Removing a region still in use is refused with 422 WORKSPACE_NARROW_BLOCKED_BY_RESOURCES: re-deploy the agents and change the collections’ regions first (see /cli/vectors). The refusals are listed on /agents/api-workspaces.

Under -o json the output holds workspace, change (the control plane’s answer: operation_id, status, current_regions, from_regions, to_regions, regions_to_add and regions_to_remove) and operation, the finished operation under --wait, else null.

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. Move them out with afy collections move <name> --workspace <workspace> --to "" (--to= on Windows PowerShell 5.1, which drops an empty argument), or delete them — see /cli/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.