---
slug: cli/workspaces
title: afy workspaces — Aetherfy workspace reference
kind: reference
surface: cli
summary: Reference for afy workspaces in the Aetherfy CLI — create, list, info, update, delete, and agents, with the name rules, the immutable-name constraint, and what workspace deletion does and does not remove.
sources:
  - aetherfy-cli:cmd/workspaces.go
  - aetherfy-cli:internal/api/workspaces.go
---

# 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`.

| Subcommand | Purpose |
|---|---|
| `afy workspaces create <name>` | Create a workspace |
| `afy workspaces list` | List all workspaces |
| `afy workspaces info <name>` | Show one workspace in detail |
| `afy workspaces update <name>` | Change the description |
| `afy workspaces delete <name>` | Delete a workspace and its secrets |
| `afy workspaces agents <workspace>` | List the agents in a workspace |

## Creating an Aetherfy workspace

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

| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
| `--description` | `-d` | string | empty | Workspace description |

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

Aetherfy enforces the name rules server-side:

| Rule | Detail |
|---|---|
| Length | 3–63 characters |
| Character set | Lowercase alphanumeric and hyphens |
| Boundaries | Cannot start or end with a hyphen |

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.

```bash
afy workspaces list
afy workspaces list -o json
```

| Column | Meaning |
|---|---|
| Name | The workspace name |
| Agents | Number of agents assigned to it |
| Description | The description, if set |
| Created | Creation timestamp |

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.

```bash
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.

| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
| `--description` | `-d` | string | empty | Workspace description — **required** |

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

```bash
# 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.

| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
| `--force` | `-f` | bool | false | Skip confirmation prompt |

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

```bash
afy workspaces delete research
afy workspaces delete research --force
```

What deletion does and does not touch:

| Item | Effect |
|---|---|
| The workspace record | Deleted |
| Workspace-scoped secrets | Deleted with it |
| Active agents | The workspace must have **none** — remove or reassign them first |
| Vector collections in the workspace | **Not deleted.** Clean them up separately. |

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](/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.

```bash
afy workspaces agents research
afy workspaces agents research -o json
```

| Column | Meaning |
|---|---|
| Name | The agent name |
| Type | `SERVICE` or `JOB` |
| Status | Current lifecycle status |
| Created | Creation timestamp |

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:

```bash
# 1. Assign an existing agent
afy agents update catalogue-scraper --workspace research

# 2. Or declare it in aetherfy.yaml before deploying
```

```yaml
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](/cli/secrets).