> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Manage workspaces and run CLI commands inside a workspace with the Coval CLI

[Workspaces](https://docs.coval.ai/guides/workspaces.md) separate agents, test sets, personas, metrics, runs, and other resources within your organization. Every CLI command runs in your organization's default workspace unless you choose another one.

> [!NOTE]
>
> Workspace commands and the `--workspace` flag require CLI version 0.11.0 or later. Run `coval --version` to check, and see [Installation](https://docs.coval.ai/cli/installation.md) to upgrade.

Your API key needs `workspaces:read` for `list` and `get`, and `workspaces:write` for `create`, `update`, `archive`, and `delete`.

`create` and `update` also accept `--input-json` (inline JSON, `@file`, or `-` for stdin); explicit flags override fields from the JSON. See [Input JSON](https://docs.coval.ai/cli/agent-mode.md#input-json).

## Run Commands in a Workspace

Pass `--workspace <workspace_id>` to any command to scope it to that workspace:

```bash theme={null}
coval --workspace 01HZXW6Q8V4M2R7N5K3J9T1BCD agents list
coval --workspace 01HZXW6Q8V4M2R7N5K3J9T1BCD runs launch \
  --agent-id abc123 --persona-id xyz789 --test-set-id ts123
```

To use the same workspace for every command, set the `COVAL_WORKSPACE_ID` environment variable or the `workspace_id` config key:

```bash theme={null}
export COVAL_WORKSPACE_ID=01HZXW6Q8V4M2R7N5K3J9T1BCD

# Or save it in the CLI config; set an empty value to clear it
coval config set workspace_id 01HZXW6Q8V4M2R7N5K3J9T1BCD
coval config set workspace_id ""
```

The flag overrides the environment variable, which overrides the config file. The CLI sends the selected ID in the `X-Coval-Workspace-Id` header. The workspace must be active and belong to your organization; an archived, deleted, or unknown workspace is rejected.

## List Workspaces

```bash theme={null}
coval workspaces list
```

Lists active and archived workspaces.

**Output columns:** ID, Name, Status, Type, Created At

## Get Workspace

```bash theme={null}
coval workspaces get <workspace_id>
```

| Argument | Type | Required | Description |
| - | - | - | - |
| `workspace_id` | string | **Yes** | The workspace ID |

## Create Workspace

```bash theme={null}
coval workspaces create [OPTIONS]
```

| Option | Type | Required | Description |
| - | - | - | - |
| `--name` | string | **Yes** | Workspace display name (alias `--display-name`) |

```bash theme={null}
coval workspaces create --name "Staging agents"
```

Use the returned `id` to refer to the workspace. Workspace slugs are deprecated.

## Update Workspace

```bash theme={null}
coval workspaces update <workspace_id> --name <name>
```

| Argument | Type | Required | Description |
| - | - | - | - |
| `workspace_id` | string | **Yes** | The workspace ID to rename |

| Option | Type | Required | Description |
| - | - | - | - |
| `--name` | string | **Yes** | New display name (alias `--display-name`) |

The default workspace cannot be renamed.

## Archive Workspace

```bash theme={null}
coval workspaces archive <workspace_id>
```

| Argument | Type | Required | Description |
| - | - | - | - |
| `workspace_id` | string | **Yes** | The workspace ID to archive |

Archiving an already archived workspace succeeds. The default workspace cannot be archived.

## Delete Workspace

```bash theme={null}
coval workspaces delete <workspace_id>
```

| Argument | Type | Required | Description |
| - | - | - | - |
| `workspace_id` | string | **Yes** | The workspace ID to delete |

Deleting blocks access to the workspace's resources, and there is no restore action, so treat it as permanent. The default workspace cannot be deleted.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.