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.

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 workspace-scoped API requests by the CLI client. Switching workspaces writes local config and, when authenticated, validates the slug or ID against the server.

Auth: list, get, and create require crewship login. update, all member operations, and invite additionally require an active workspace. use writes the local config and validates the slug or ID against the server when you’re already logged in. Role gates apply server-side — OWNER/ADMIN to update or invite, OWNER only to delete, MEMBER+ to read.

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 delete [slug-or-id]`	Delete a workspace (OWNER only, irreversible). Requires `--confirm <slug>`.
`workspace member list`	List members of the active workspace.
`workspace member add <user-id>`	Add an existing user to the workspace. Takes a user id.
`workspace member role <member-id-or-user-id> <ROLE>`	Change a member’s role (`MANAGER+`, ladder-guarded).
`workspace member remove <member-id-or-user-id>`	Remove a member (prompts unless `-y`).
`workspace member invite <email>`	Add someone by email, creating an account if needed, and print a one-time setup link.
`workspace member capabilities ...`	Manage per-member capability grants (aliases: `caps`, `capability`). See below.
`workspace invite [email]`	Record an invitation row by email (shortcut for `invite create`; no email is sent).
`workspace invite create <email>`	Create an invitation.
`workspace invite list`	List pending invitations.

`crewship workspace get [slug-or-id]`

Show details for the specified workspace, or for the active workspace when no argument is supplied.

crewship workspace get
crewship workspace get acme-platform

The command takes no command-specific flags. It prints Name, Slug, Language, Allow privileged credentials, ID, and Created; machine formats use the corresponding API fields id, name, slug, created_at, preferred_language, and allow_privileged_credentials.

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.
`--allow-privileged-credentials`	Allow credentials in a `--privileged` crew despite the UID isolation boundary. Defaults to `false` (fails closed).
`--credential-audit-retention-days`	Days of `credential_audit` history to keep. `0` means keep forever. Leave unset to use the 90-day default.
`--audit-log-retention-days`	Days of `audit_logs` history to keep. `0` means keep forever, which is the default — `audit_logs` is the compliance trail and its retention obligation is yours to declare.

Only flags you actually pass are sent, and that matters here: 0 is a meaningful value on both retention flags (an explicit “keep forever”), so an unset flag must not be transmitted as zero. crewship workspace update --name x never touches your retention windows.

`workspace delete`

Deletes a workspace and everything under it. Soft-delete with cascade over crews and agents; OWNER only, and refused if it is your only workspace.

Flag	Default	Effect
`--confirm <slug>`	(required)	Re-type the workspace slug to confirm. Sent as `confirm_slug`; the server re-validates it.
`-y`, `--yes`	`false`	Skip the interactive confirmation prompt (the `--confirm` slug is still required).

`workspace member add`

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

Which id do the member commands take?

workspace member list prints two ids per row and they are not interchangeable at the API:

Column	What it is	Consumed by
`MEMBER ID`	The `workspace_members` row	`PATCH` / `DELETE /api/v1/workspaces/{id}/members/{memberId}`
`USER ID`	The person	`POST /api/v1/workspaces/{id}/members`

So member add takes a user id while the endpoints behind member role and member remove match only a membership row. Passing the user id used to answer a bare Member not found — which reads as “that person is not in this workspace” rather than “wrong id”, and cost a test suite its most important assertion (#1829). Both commands now accept either column and resolve it for you. An argument that is in neither is refused by name before any request goes out:

no workspace member matches "nobody": it is neither a MEMBER ID nor a USER ID
in 'crewship workspace member list'

Resolution is a convenience, not a new dependency: if the member roster cannot be read (permissions, an unreachable server), the argument is sent through untouched and the server answers as it always did. workspace member list --format json carries the address in a flat email field and in the nested user.email the server sends. The flat field used to be present and always empty — a shape that silently broke every jq 'select(.email == …)' written against it.

`workspace member role`

crewship workspace member role <member-id-or-user-id> <ROLE>

<ROLE> is one of OWNER, ADMIN, MANAGER, MEMBER, VIEWER (case-insensitive). MANAGER+ only, and subject to the server ladder: you can only grant a role below your own, cannot modify a member ranked above you, and cannot demote the last OWNER.

`workspace member remove`

crewship workspace member remove <member-id-or-user-id> --yes

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

`workspace invite` / `workspace invite create`

Flag	Default	Effect
`--role <ROLE>`	`MEMBER`	Role to grant. `MEMBER` or `ADMIN`. This records an invitation row; no email is sent.

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. No mailer is wired for this command.

`crewship workspace invite create <email>`

Record a workspace invitation for an email address. No email is sent; use workspace member invite when account provisioning and a setup link are needed.

crewship workspace invite create alice@acme.com
crewship workspace invite create alice@acme.com --role ADMIN

Flag	Default	Effect
`--role <ROLE>`	`MEMBER`	Role recorded on the invitation: `MEMBER` or `ADMIN`.

On success the CLI prints Invitation recorded for <email> (<role> role). followed by a warning that no email was sent.

`workspace member invite`

This provisioning command is distinct from workspace invite: it creates the account when needed, adds the membership, and prints a one-time setup link.

Flag	Default	Effect
`--role <ROLE>`	`MEMBER`	Role to grant: `ADMIN`, `MANAGER`, `MEMBER`, or `VIEWER`.

Examples

List + switch

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

crewship workspace create \
  --name "ACME Platform" \
  --slug acme-platform \
  --language en

Update a workspace

crewship workspace update --name "ACME Platform Team" --language cs

# Keep two years of audit_logs; keep credential reads forever.
crewship workspace update --audit-log-retention-days 730 --credential-audit-retention-days 0

Delete a workspace

# OWNER only, irreversible. Re-type the slug to confirm.
crewship workspace delete acme-robotics --confirm acme-robotics --yes

Refused with 409 if it is your only workspace, and with 403 if you are not the OWNER.

Member management

crewship workspace member list
crewship workspace member add usr_abc123 --role ADMIN
crewship workspace member remove usr_abc123 --yes   # user id or MEMBER ID both work
crewship workspace member invite alice@acme.com --role MEMBER

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 dashboard equivalent is Settings → Members: one row per person, expanded to reveal that member’s role and their eight capability grants side by side. The collapsed row summarises the grants so a capability stays comparable across the roster without expanding every row. Presets apply to the whole workspace from the card header, with a before/after diff for every member they would change. 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).

`crewship workspace member capabilities grant <user-id> <capability> [<capability>...]`

Grant one or more capabilities incrementally; existing grants are preserved.

crewship workspace member capabilities grant ludmila routine.create issue.create memory.write

The command requires at least one capability and has no command-specific flags. Valid values are chat, routine.create, skill.create, credential.create, credential.rotate, issue.create, and memory.write. On success it prints <user-id> (<role>): <capabilities>.

`crewship workspace member capabilities revoke <user-id> <capability> [<capability>...]`

Revoke one or more capabilities incrementally; other grants are preserved.

crewship workspace member capabilities revoke ludmila memory.write

The command requires at least one capability and has no command-specific flags. Revoking chat is rejected because chat is always implied; remove the member instead. On success it prints <user-id> (<role>): <capabilities>.

`crewship workspace member capabilities preset <user-id> <chat|power|admin>`

Replace the member’s capability set with the named bundle, overwriting existing grants.

crewship workspace member capabilities preset ludmila power

The command takes exactly the user ID and one of chat, power, or admin, with no command-specific flags. On success it prints <user-id> (<role>): <capabilities>. 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`.

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

crewship workspace invite alice@acme.com --role ADMIN
# ✓ Invitation recorded for alice@acme.com (ADMIN role).
# ! No email was sent — no mailer is wired. Use `crewship workspace member invite` to create the account and get a setup link.

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

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 / --allow-privileged-credentials / --credential-audit-retention-days / --audit-log-retention-days.
no workspace selected — update ran without an active workspace. Run crewship workspace use first or pass --workspace.

​crewship workspace

​Subcommands

​crewship workspace get [slug-or-id]

​Flags

​workspace create

​workspace update

​workspace delete

​workspace member add

​Which id do the member commands take?

​workspace member role

​workspace member remove

​workspace invite / workspace invite create

​crewship workspace invite create <email>

​workspace member invite

​Examples

​List + switch

​Create a workspace

​Update a workspace

​Delete a workspace

​Member management

​workspace member capabilities

​Subcommands

​crewship workspace member capabilities grant <user-id> <capability> [<capability>...]

​crewship workspace member capabilities revoke <user-id> <capability> [<capability>...]

​crewship workspace member capabilities preset <user-id> <chat|power|admin>

​Invitations

​Common errors

​See also

crewship workspace

Subcommands

`crewship workspace get [slug-or-id]`

Flags

`workspace create`

`workspace update`

`workspace delete`

`workspace member add`

Which id do the member commands take?

`workspace member role`

`workspace member remove`

`workspace invite` / `workspace invite create`

`crewship workspace invite create <email>`

`workspace member invite`

Examples

List + switch

Create a workspace

Update a workspace

Delete a workspace

Member management

`workspace member capabilities`

Subcommands

`crewship workspace member capabilities grant <user-id> <capability> [<capability>...]`

`crewship workspace member capabilities revoke <user-id> <capability> [<capability>...]`

`crewship workspace member capabilities preset <user-id> <chat|power|admin>`

Invitations

Common errors

See also