Skip to main content
Workspaces 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.
Workspace commands and the --workspace flag require CLI version 0.11.0 or later. Run coval --version to check, and see Installation 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.

​
Run Commands in a Workspace

Pass --workspace <workspace_id> to any command to scope it to that workspace:
To use the same workspace for every command, set the COVAL_WORKSPACE_ID environment variable or the workspace_id config key:
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

Lists active and archived workspaces. Output columns: ID, Name, Status, Type, Created At

​
Get Workspace

​
Create Workspace

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

​
Update Workspace

The default workspace cannot be renamed.

​
Archive Workspace

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

​
Delete Workspace

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.