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

# archal workspace

> Manage workspace-scoped CLI credentials for CI and runtime automation.

Use workspace API keys for CI, headless shells, and automation. They are bound
to one workspace and can run clones, upload/read traces, and read usage for that
workspace. They cannot manage API keys or audit events.

Create, list, and revoke keys with an owner/admin user session from
`archal login`:

```bash theme={null}
archal workspace api-key create ci-runner
archal workspace api-keys
archal workspace api-key revoke <key-id>
```

`create` prints the secret once. Store it as `ARCHAL_TOKEN`:

```bash theme={null}
export ARCHAL_TOKEN=archal_ws_<your-key>
```

Use `--workspace <name|id>` when your user belongs to multiple workspaces:

```bash theme={null}
archal workspace api-key create ci-runner --workspace acme-prod
```

## JSON output

```bash theme={null}
archal workspace api-key create ci-runner --json
archal workspace api-keys --json
archal workspace api-key revoke <key-id> --json
```

## Scopes

The default scopes are enough for CI runs:

```bash theme={null}
archal workspace api-key create ci-runner \
  --scope sessions:read sessions:write workspaces:read
```

Use `archal login` or a dashboard-issued user API key for workspace
administration. Workspace API keys cannot create or revoke other workspace API
keys.