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 logo set <file>`	Upload or replace the current workspace’s logo (PNG, JPEG or WebP, max 2MB; ADMIN+).
`workspace logo remove`	Remove the logo; the workspace is drawn with its initial again (ADMIN+).
`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, Pages theme, ID, and Created; machine formats use the corresponding API fields id, name, slug, created_at, preferred_language, allow_privileged_credentials and pages_theme. Pages theme lists the shared Page colours as key=#RRGGBB pairs, or (SDK defaults) when none is set — see workspace update --pages-theme.

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.
`--approvals-retention-days`	Days of decided `approvals_queue` history (approved/denied/timeout/cancelled) to keep. `0` means keep forever. Leave unset to use the 90-day default. A pending approval is never swept regardless of age. Rejected above `106751` days (~292 years) — past that the day count overflows the retention sweep’s `int64`-nanosecond cutoff arithmetic.
`--pages-theme <json\|@file>`	The shared colours every custom Page application reads through the `--crewship-page-` design tokens: a JSON object whose keys are `accent`, `background`, `surface`, `text`, `muted` and `border` and whose values are `#RRGGBB` colours. Inline (`'{"accent":"#0f766e"}'`) or `@theme.json`. The object replaces* the stored one — omitted keys fall back to the SDK defaults — and `{}` resets it. Any other key, any other colour form, or more than 1 KiB is refused by the server. This is the same setting as Settings → General → Pages appearance; `OWNER`/`ADMIN` only, and audited.

Only flags you actually pass are sent, and that matters here: 0 is a meaningful value on all three 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 logo`

Sets or removes the logo the current workspace is drawn with (the switcher, Admin lists, the Backups and Security scope). Same rules as auth avatar: PNG, JPEG or WebP, at most 2MB and 4096 px a side. Needs ADMIN or OWNER.

crewship workspace logo set ./logo.png
crewship workspace logo remove

`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. The ACCESS column (access_mode in machine formats) is the member’s access mode, trusted or restricted, kept apart from ROLE: a restricted MEMBER and a trusted MEMBER share a role. The mode is part of the member access policy, so the server sends it only to a trusted OWNER/ADMIN whose token may administer the workspace; everyone else sees - and no access_mode field. Settings › Members marks the same members Restricted next to their role. Change the mode with workspace member access set.

`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.

Removal also drops every crew membership the person holds in this workspace, and first transfers any page they own to a crew — a page that resolves to no crew refuses the whole removal. Adding them back later restores neither: crew membership and any per-crew role override have to be granted again. See Remove member.

`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`.
`--create-only`	`false`	Require a new account. If the email already exists, return `409` before changing membership, role or setup tokens.

Use --create-only for isolated demo provisioning when an existing person must remain untouched. The default provisioning behavior is unchanged when omitted; the flag does not reset an existing account’s password.

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 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, routine.run, skill.create, credential.create, credential.rotate, credentials:reveal, issue.create, page.create, memory.write. Note the colon in credentials:reveal — it is the one capability spelled the way the security document names it.

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` + `routine.run` + `issue.create` + `memory.write` (trusted team members).
`admin`	full set, including `credential.create`, `credential.rotate` and `credentials:reveal` (everything but `page.create`). An OWNER/ADMIN with no explicit set holds the admin preset minus `routine.run` (the role clears that gate on its own).

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 / --approvals-retention-days / --pages-theme.
--pages-theme must be a JSON object … — the value (or the @file) did not parse as a JSON object of strings. The colour vocabulary itself is checked by the server: pages_theme supports accent, background, surface, text, muted and border as #RRGGBB colors is its answer to an unknown key or a named colour.
no workspace selected — update ran without an active workspace. Run crewship workspace use first or pass --workspace.

`crewship workspace member access`

Read or replace a member’s resource access policy. These grants limit specific agent/project operations in addition to roles and capabilities. Current trusted OWNER/ADMIN access is required; scoped tokens need workspace:admin. Restricted mode currently blocks unintegrated routes, including model execution. It also applies to sessions with mixed trusted/restricted memberships.

`crewship workspace member access get <member-id-or-user-id>`

Read the complete policy, including membership_id, mode, revision and rights. Accepts either a membership row ID or user ID. There are no command-specific flags. The default table shows MEMBER, MODE, REVISION and RIGHTS count; --format json returns the editable document.

crewship --workspace WORKSPACE --format json workspace member access get MEMBER > policy.json

`crewship workspace member access set <member-id-or-user-id>`

Replace the complete policy using its original membership ID and revision. Edit the mode and rights fields from access get; do not invent a revision. An explicit empty rights array in restricted mode denies all resource grants. Trusted mode requires empty rights and restores ordinary workspace access.

Flag	Required	Description
`--file`	Yes	Complete policy JSON file; `-` reads JSON from stdin.

crewship --workspace WORKSPACE --format json workspace member access set MEMBER --file policy.json

Success prints the resulting policy using the same output formats as get. A stale revision exits nonzero with HTTP 409; the command does not retry or silently refresh it. Revisions may advance by more than one. Missing/null rights, unknown fields and a document for a different membership are rejected. This command does not enable restricted model execution or stop an already running shared process. See the API contract.

​crewship workspace

​Subcommands

​crewship workspace get [slug-or-id]

​Flags

​workspace create

​workspace update

​workspace logo

​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 member access

​crewship workspace member access get <member-id-or-user-id>

​crewship workspace member access set <member-id-or-user-id>

crewship workspace

Subcommands

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

Flags

`workspace create`

`workspace update`

`workspace logo`

`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 member access`

`crewship workspace member access get <member-id-or-user-id>`

`crewship workspace member access set <member-id-or-user-id>`