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

# Workspace

> Switch the active workspace, list members, invite users, and update workspace settings.

# crewship workspace

A workspace is the top-level tenant. Every other resource — crews, agents, credentials, projects, integrations — lives inside one. Aliases: `ws`. Defined in `cmd/crewship/cmd_workspace.go`.

```bash theme={null}
crewship workspace <subcommand> [flags]
crewship ws <subcommand> [flags]
```

The active workspace is stored in `~/.crewship/cli-config.yaml` under `workspace` (slug or id). It is sent as `workspace_id=` on every API request by the CLI client, so switching workspaces is purely client-side — no server round-trip.

<Note>
  **Auth:** `list`, `use`, and `get` require `crewship login`; mutations additionally require an active workspace context. Role gates apply server-side — `OWNER`/`ADMIN` to update or invite, `MEMBER+` to read.
</Note>

## Subcommands

| Command                             | Purpose                                                                                                           |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `workspace list`                    | List every workspace the caller can see; marks the active one with `*`.                                           |
| `workspace use <slug-or-id>`        | Set the default workspace in the local config.                                                                    |
| `workspace get [slug-or-id]`        | Show workspace details (defaults to the active one).                                                              |
| `workspace create`                  | Create a new workspace (you become its OWNER).                                                                    |
| `workspace update`                  | Patch mutable fields on the current workspace.                                                                    |
| `workspace member list`             | List members of the active workspace.                                                                             |
| `workspace member add <user-id>`    | Add an existing user to the workspace.                                                                            |
| `workspace member remove <user-id>` | Remove a member (prompts unless `-y`).                                                                            |
| `workspace member capabilities ...` | Manage per-member capability grants (aliases: `caps`, `capability`). See [below](#workspace-member-capabilities). |
| `workspace invite [email]`          | Invite by email (shortcut for `invite create`).                                                                   |
| `workspace invite create <email>`   | Create an invitation.                                                                                             |
| `workspace invite list`             | List pending invitations.                                                                                         |

## Flags

### `workspace create`

| Flag                | Default          | Effect                                                                                                                                                                                                       |
| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--name <string>`   | (required)       | Display name.                                                                                                                                                                                                |
| `--slug <string>`   | (auto)           | URL slug. Auto-generated from `--name` if omitted.                                                                                                                                                           |
| `--language <code>` | (server default) | Preferred reply language for agents (e.g. `cs`, `en`). Reinforced at the top and bottom of every agent prompt — including chat sessions, assignments, and pipelines — so the agent answers in this language. |

### `workspace update`

Only flags you actually set are sent — passing nothing returns `no fields to update`.

| Flag                | Effect                                                                                                                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--name <string>`   | Rename the workspace.                                                                                                                                                                                        |
| `--slug <string>`   | Change the slug (URLs flip immediately).                                                                                                                                                                     |
| `--language <code>` | Preferred reply language for agents (e.g. `cs`, `en`). Reinforced at the top and bottom of every agent prompt — including chat sessions, assignments, and pipelines — so the agent answers in this language. |

### `workspace member add`

| Flag            | Default  | Effect                                                                  |
| --------------- | -------- | ----------------------------------------------------------------------- |
| `--role <ROLE>` | `MEMBER` | One of `MEMBER` or `ADMIN`. Owners are seeded at workspace-create time. |

### `workspace member remove`

| Flag          | Default | Effect                        |
| ------------- | ------- | ----------------------------- |
| `-y`, `--yes` | `false` | Skip the confirmation prompt. |

### `workspace invite` / `workspace invite create`

| Flag            | Default  | Effect                                            |
| --------------- | -------- | ------------------------------------------------- |
| `--role <ROLE>` | `MEMBER` | Role to grant on acceptance. `MEMBER` or `ADMIN`. |

The role flag is mirrored on the parent `invite` command so the shortcut form (`workspace invite alice@example.com --role ADMIN`) works without an explicit `create`.

## Examples

### List + switch

```bash theme={null}
crewship workspace list
# SLUG                     NAME                ID        ROLE
# acme-engineering *       ACME Engineering    ws_…      OWNER
# acme-design              ACME Design         ws_…      MEMBER

crewship ws use acme-design
# ✓ Default workspace set to: acme-design
```

`workspace use` validates that the slug actually exists and is accessible before writing the config, so a typo doesn't quietly orphan every future command.

### Create a workspace

```bash theme={null}
crewship workspace create \
  --name "ACME Platform" \
  --slug acme-platform \
  --language en
```

### Update a workspace

```bash theme={null}
crewship workspace update --name "ACME Platform Team" --language cs
```

### Member management

```bash theme={null}
crewship workspace member list
crewship workspace member add usr_abc123 --role ADMIN
crewship workspace member remove usr_abc123 --yes
```

User IDs come from `crewship admin list-users` or the web UI's user table.

## `workspace member capabilities`

Per-member capabilities grant individual high-value actions (create routines, skills, credentials, ...) to one member **without** promoting them to a wider RBAC role. They layer on top of the member's role — a `MEMBER` can be handed `routine.create` while everyone else in that role stays chat-only.

Aliases: `caps`, `capability`. **ADMIN+ required** to mutate; the CLI exits non-zero on a `403` so a misconfigured CI pipeline fails loudly. Capabilities are workspace-scoped — a user in multiple workspaces is configured separately in each.

The `chat` capability is always implied and cannot be granted or revoked individually; removing chat means removing the member entirely (`workspace member remove`). The OWNER target is immutable, and you cannot mutate your own row (downgrade-then-restore defence).

Valid capability strings: `chat`, `routine.create`, `skill.create`, `credential.create`, `credential.rotate`, `issue.create`, `memory.write`.

### Subcommands

| Command                                              | Args      | Purpose                                                                               |
| ---------------------------------------------------- | --------- | ------------------------------------------------------------------------------------- |
| `capabilities list <user-id>`                        | exactly 1 | Show capabilities granted to one member.                                              |
| `capabilities grant <user-id> <cap> [<cap>...]`      | 2+        | Grant one or more capabilities incrementally (existing grants preserved).             |
| `capabilities revoke <user-id> <cap> [<cap>...]`     | 2+        | Revoke one or more capabilities incrementally (other grants preserved).               |
| `capabilities preset <user-id> <chat\|power\|admin>` | exactly 2 | Replace the member's capability set with a named bundle (overwrites existing grants). |

Bundles map to common combinations:

| Bundle  | Capabilities                                                                      |
| ------- | --------------------------------------------------------------------------------- |
| `chat`  | chat-only baseline (default for new MEMBERs).                                     |
| `power` | chat + `routine.create` + `issue.create` + `memory.write` (trusted team members). |
| `admin` | full set, including `credential.create` + `credential.rotate`.                    |

```bash theme={null}
crewship workspace member capabilities list usr_abc123
crewship workspace member caps grant usr_abc123 routine.create issue.create memory.write
crewship workspace member caps revoke usr_abc123 memory.write
crewship workspace member caps preset usr_abc123 power
```

Unknown capability strings are rejected server-side (`400`, typo guard). Revoking `chat` is rejected by the server. The `list` command prints `USER`, `ROLE`, `CAPABILITIES` columns; mutations print the resulting capability set.

### Invitations

```bash theme={null}
crewship workspace invite alice@acme.com --role ADMIN
# ✓ Invitation sent to alice@acme.com (ADMIN role).

crewship workspace invite list
# ID            EMAIL                ROLE     EXPIRES               CREATED
# inv_…         alice@acme.com       ADMIN    2026-05-26T…          2026-05-19T…
```

The shortcut form (`invite <email>`) and the explicit form (`invite create <email>`) share one implementation, so role flags behave identically on both.

## Common errors

<Accordion title="Common errors and what they mean">
  * **`workspace "X" not found or not accessible`** — `workspace use` validated against `/api/v1/workspaces` and your token has no membership.
  * **`--name is required`** — `create` needs at least a name.
  * **`no fields to update`** — `update` was called without any of `--name` / `--slug` / `--language`.
  * **`no workspace selected`** — `update` ran without an active workspace. Run `crewship workspace use` first or pass `--workspace`.
</Accordion>

## See also

* [`crewship login`](/cli/login) — `crewship login --workspace <slug>` sets the workspace at login time.
* [`crewship config`](/cli/config) — direct access to the `workspace` config key.
* [`crewship admin`](/guides/admin-cli) — cross-workspace operations (only OWNER on the workspace itself, or instance admin).
* [Workspaces API](/api-reference/workspaces) — `GET /api/v1/workspaces`.