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

# Crew Commands

> Create and manage crews, members, connections, and MCP configurations.

# crewship crew

A crew is a team of AI agents that share one runtime container and a common Shared Ship volume. Use these commands to create and tune crews, manage members and cross-crew connections, wire up MCP servers, drive the devcontainer build pipeline (provision, rebuild, cache), and read or write files in the crew's shared workspace.

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

## Subcommands

| Command              | Description                                                                |
| -------------------- | -------------------------------------------------------------------------- |
| `list`               | List all crews in the workspace                                            |
| `get`                | Show crew details                                                          |
| `create`             | Create a new crew                                                          |
| `update`             | Update a crew                                                              |
| `delete`             | Delete a crew                                                              |
| `status`             | Show live crew status (agents, assignments, escalations)                   |
| `standup`            | Show crew standup summary (last 24h activity)                              |
| `peer-conversations` | List peer conversations in a crew                                          |
| `suggest`            | Get AI-powered crew suggestions based on a goal                            |
| `member list`        | List crew members                                                          |
| `member add`         | Add a user to a crew                                                       |
| `member remove`      | Remove a member from a crew                                                |
| `connect`            | Create a connection between two crews                                      |
| `disconnect`         | Remove a crew connection                                                   |
| `connections`        | List all crew connections in the workspace                                 |
| `mcp`                | Show or set MCP server configuration for a crew                            |
| `config`             | Manage runtime configuration (devcontainer, mise, runtime image)           |
| `provision`          | Trigger devcontainer provisioning                                          |
| `provision status`   | Check provisioning status                                                  |
| `restart-agents`     | Drop the runtime container so the next exec rebuilds from the cached image |
| `rebuild`            | Invalidate the cache and re-provision the container                        |
| `cache list`         | List cached devcontainer images (`crewship-cache:*`)                       |
| `cache prune`        | Remove old or unreferenced cached images                                   |
| `files list`         | List entries under the crew's `/crew/shared/` Shared Ship volume           |
| `files get`          | Download a file from the crew's shared volume                              |
| `files save`         | Upload bytes (stdin / `--file` / `--content`) into the shared volume       |

***

## `crewship crew list`

List all crews in the workspace.

```bash theme={null}
crewship crew list
```

**Output columns:** SLUG, NAME, AGENTS, NETWORK, MEMORY, CPUS

***

## `crewship crew get`

Show detailed information about a crew.

```bash theme={null}
crewship crew get <slug-or-id>
```

**Output fields:** Name, Slug, ID, Description, Memory, CPUs, TTL, Network Mode, Allowed Domains, Created.

***

## `crewship crew create`

Create a new crew.

```bash theme={null}
crewship crew create --name "Backend Team" --memory-mb 4096 --cpus 2.0
```

| Flag                | Type      | Default            | Description                                          |
| ------------------- | --------- | ------------------ | ---------------------------------------------------- |
| `--name`            | `string`  | *(required)*       | Crew name.                                           |
| `--slug`            | `string`  | *(auto from name)* | Crew slug.                                           |
| `--description`     | `string`  |                    | Description.                                         |
| `--color`           | `string`  |                    | Hex color (e.g. `#3B82F6`).                          |
| `--icon`            | `string`  |                    | Emoji icon.                                          |
| `--memory-mb`       | `int`     | `0`                | Container memory limit in MB.                        |
| `--cpus`            | `float64` | `0`                | Container CPU limit.                                 |
| `--ttl`             | `int`     | `0`                | Auto-stop after idle hours (0 = never stop).         |
| `--network-mode`    | `string`  |                    | Network policy: `free` or `restricted`.              |
| `--allowed-domains` | `string`  |                    | Comma-separated allowed domains for restricted mode. |

***

## `crewship crew update`

Update a crew. Only changed flags are sent.

```bash theme={null}
crewship crew update <slug-or-id> --memory-mb 8192 --cpus 4.0
```

| Flag                | Type      | Default | Description                                                  |
| ------------------- | --------- | ------- | ------------------------------------------------------------ |
| `--name`            | `string`  |         | Crew name.                                                   |
| `--description`     | `string`  |         | Description.                                                 |
| `--color`           | `string`  |         | Hex color.                                                   |
| `--icon`            | `string`  |         | Emoji icon.                                                  |
| `--memory-mb`       | `int`     |         | Container memory limit in MB.                                |
| `--cpus`            | `float64` |         | Container CPU limit.                                         |
| `--ttl`             | `int`     | `-1`    | Auto-stop after idle hours (0 = disable TTL).                |
| `--network-mode`    | `string`  |         | Network policy: `free` or `restricted`.                      |
| `--allowed-domains` | `string`  |         | Comma-separated allowed domains. Pass empty string to clear. |

***

## `crewship crew delete`

Delete a crew. Prompts for confirmation.

```bash theme={null}
crewship crew delete <slug-or-id>
crewship crew delete backend-team --yes
```

| Flag    | Short | Type   | Default | Description               |
| ------- | ----- | ------ | ------- | ------------------------- |
| `--yes` | `-y`  | `bool` | `false` | Skip confirmation prompt. |

<Warning>
  Deleting a crew removes its agents and runtime context. `--yes` bypasses the prompt — use it only in scripts.
</Warning>

***

## `crewship crew status`

Show live crew status including agents, recent assignments, and open escalations.

```bash theme={null}
crewship crew status <slug-or-id>
```

Displays a compound view with three sections:

* **AGENTS** -- all agents with their slug, role, and status
* **ASSIGNMENTS (last 5)** -- recent task assignments with status colors
* **ESCALATIONS (open)** -- pending or open escalations

***

## `crewship crew standup`

Show crew standup summary (last 24h activity).

```bash theme={null}
crewship crew standup <slug-or-id>
crewship crew standup backend-team --since 2024-01-01T00:00:00Z
```

| Flag      | Type     | Default     | Description                              |
| --------- | -------- | ----------- | ---------------------------------------- |
| `--since` | `string` | *(24h ago)* | Show activity since (RFC3339 timestamp). |

***

## `crewship crew peer-conversations`

List peer conversations in a crew.

```bash theme={null}
crewship crew peer-conversations <slug-or-id>
crewship crew peer-conversations backend-team --limit 20
```

| Flag      | Type  | Default | Description                      |
| --------- | ----- | ------- | -------------------------------- |
| `--limit` | `int` | `50`    | Number of conversations to show. |

**Output columns:** ID, FROM, TO, QUESTION, STATUS, ESCALATED, CREATED

***

## `crewship crew suggest`

Get AI-powered crew suggestions based on a goal.

```bash theme={null}
crewship crew suggest --goal "Build a SaaS billing system"
```

| Flag     | Type     | Default      | Description                       |
| -------- | -------- | ------------ | --------------------------------- |
| `--goal` | `string` | *(required)* | What should this crew accomplish? |

***

## Crew Members

### `crewship crew member list`

List members of a crew.

```bash theme={null}
crewship crew member list <crew-slug-or-id>
```

**Output columns:** ID, USER, EMAIL, JOINED

### `crewship crew member add`

Add a user to a crew.

```bash theme={null}
crewship crew member add <crew-slug-or-id> <user-id>
```

### `crewship crew member remove`

Remove a member from a crew.

```bash theme={null}
crewship crew member remove <crew-slug-or-id> <member-id>
```

***

## Crew Connections

Crew connections enable cross-crew task dispatch between two crews.

### `crewship crew connect`

Create a connection between two crews.

```bash theme={null}
crewship crew connect <crew-slug-A> <crew-slug-B>
crewship crew connect backend-team frontend-team --direction unidirectional
```

| Flag          | Type     | Default         | Description                                                |
| ------------- | -------- | --------------- | ---------------------------------------------------------- |
| `--direction` | `string` | `bidirectional` | Connection direction: `bidirectional` or `unidirectional`. |

### `crewship crew disconnect`

Remove a crew connection by connection ID.

```bash theme={null}
crewship crew disconnect <connection-id>
```

### `crewship crew connections`

List all crew connections in the workspace.

```bash theme={null}
crewship crew connections
```

**Output columns:** ID, FROM, TO, DIRECTION, STATUS, CREATED

***

## `crewship crew mcp`

Show or set MCP server configuration for a crew.

```bash theme={null}
# Show current config
crewship crew mcp <crew-slug>

# Set from inline JSON
crewship crew mcp <crew-slug> --set '{"mcpServers":{"github":{"command":"npx","args":["-y","@modelcontextprotocol/server-github"]}}}'

# Set from file
crewship crew mcp <crew-slug> --set-file .mcp.json

# Clear config
crewship crew mcp <crew-slug> --set ''
```

| Flag         | Type     | Default | Description                                           |
| ------------ | -------- | ------- | ----------------------------------------------------- |
| `--set`      | `string` |         | Set MCP config from JSON string. Pass empty to clear. |
| `--set-file` | `string` |         | Set MCP config from file path.                        |

<Note>
  `--set` and `--set-file` are mutually exclusive. The JSON must contain a `"mcpServers"` top-level object.
</Note>

***

## `crewship crew config`

Manage runtime configuration for a crew — the devcontainer `devcontainer.json`, mise tool config, and optional runtime base image override. Together these drive what `crewship crew provision` builds.

```bash theme={null}
# Inspect current config
crewship crew config <slug-or-id> --show

# Emit as JSON (pipe into jq / stash in a secret store)
crewship crew config <slug-or-id> --export

# Upload a devcontainer.json
crewship crew config <slug-or-id> --devcontainer ./devcontainer.json

# Upload a mise config alongside the devcontainer
crewship crew config <slug-or-id> --devcontainer ./devcontainer.json --mise ./.mise.toml.json

# Pin a custom base image instead of the default runtime
crewship crew config <slug-or-id> --runtime-image debian:bookworm-slim

# Reset everything back to defaults
crewship crew config <slug-or-id> --clear
```

| Flag              | Type     | Default | Description                                                |
| ----------------- | -------- | ------- | ---------------------------------------------------------- |
| `--show`          | `bool`   | `false` | Pretty-print the current runtime configuration.            |
| `--export`        | `bool`   | `false` | Export runtime configuration as JSON to stdout.            |
| `--clear`         | `bool`   | `false` | Clear all runtime configuration (sets to NULL in the DB).  |
| `--devcontainer`  | `string` |         | Path to a `devcontainer.json` file to upload.              |
| `--mise`          | `string` |         | Path to a mise config JSON file to upload.                 |
| `--runtime-image` | `string` |         | Custom base image reference (e.g. `debian:bookworm-slim`). |

`--show`, `--export`, and `--clear` are read-or-reset operations; the three upload flags apply a new value. Combine upload flags in one invocation to update multiple fields atomically.

After changing runtime configuration, run `crewship crew rebuild` to invalidate the container cache and apply the new build.

***

## `crewship crew provision`

Trigger devcontainer provisioning for a crew. Kicks off the same build pipeline the server runs when an agent first starts in a fresh workspace. Streams live build progress until the build completes or fails — pass `--no-watch` to fire-and-forget.

```bash theme={null}
crewship crew provision <slug-or-id>
crewship crew provision <slug-or-id> --no-watch
```

| Flag         | Type   | Default | Description                                                 |
| ------------ | ------ | ------- | ----------------------------------------------------------- |
| `--no-watch` | `bool` | `false` | Do not watch progress; return immediately after triggering. |

### `crewship crew provision status`

Check provisioning status for a crew. Prints the current status, cached image tag, config hash, and resolved devcontainer config. Pass `--watch` to stream live progress until the build completes. Exit code is always `0` — branch on the `Status` field (`ready`, `building`, `failed`, `not-provisioned`) in downstream scripts rather than relying on the exit code.

```bash theme={null}
crewship crew provision status <slug-or-id>
crewship crew provision status <slug-or-id> --watch
```

| Flag      | Type   | Default | Description                                     |
| --------- | ------ | ------- | ----------------------------------------------- |
| `--watch` | `bool` | `false` | Stream live progress until the build completes. |

***

## `crewship crew rebuild`

Invalidate the crew's cached devcontainer image and re-provision. Use after changing `crewship crew config` values — `provision` alone will reuse the cached layer keyed by the old config hash. Streams live progress unless `--no-watch` is passed.

```bash theme={null}
crewship crew rebuild <slug-or-id>
crewship crew rebuild <slug-or-id> --no-watch
```

| Flag         | Type   | Default | Description                                                 |
| ------------ | ------ | ------- | ----------------------------------------------------------- |
| `--no-watch` | `bool` | `false` | Do not watch progress; return immediately after triggering. |

***

## `crewship crew restart-agents`

Force-remove the crew's runtime container. The next agent exec recreates it from the current cached image, so agents pick up a new system prompt, new MCP config, and new env vars **without** a full rebuild. Idempotent — succeeds with `restarted=0` when no container was running.

```bash theme={null}
crewship crew restart-agents <slug-or-id>
crewship crew restart-agents <slug-or-id> --format json
```

Backed by `POST /api/v1/crews/{crewId}/restart-agents`. The handler returns `{"restarted": <n>}`. Use `restart-agents` for hot config refreshes; reach for [`rebuild`](#crewship-crew-rebuild) only when the image itself has changed.

<Note>
  `restarted: <n>` (n > 0) confirms the container was actually dropped; a fresh one is created cold on the next exec. `restarted: 0` means no running container was found for this crew — expected when the crew is idle, but if you *know* a container is up and still see `0`, you're on a build that predates the container-name-matching fix (the matcher looked for `crewship-team-<slug>` and missed the real `<prefix>-team-<slug>-<crewID>` name on any multi-instance or post-cross-tenant-fix deployment, so the drop silently no-op'd). Upgrade the server.
</Note>

***

## `crewship crew files`

Inspect or write files in the crew's `/crew/shared/` directory — the inter-agent **Shared Ship** namespace. Alias: `crew file`. Server routes live in `internal/api/proxy_files.go`; the CLI download path mirrors [`crewship agent files`](/cli/agent#crewship-agent-files) so the table / json / yaml output feels identical across scopes.

### `crewship crew files list <slug-or-id>`

```bash theme={null}
crewship crew files list demo-crew
crewship crew files list demo-crew --path /shared/notes
crewship crew files list demo-crew --recursive --format json --filter '.[] | .name'
```

| Flag              | Type   | Default | Description                                                         |
| ----------------- | ------ | ------- | ------------------------------------------------------------------- |
| `--path <subdir>` | string | (root)  | Subdirectory under `/crew/shared` to list. Forwarded as `?subdir=`. |
| `--recursive`     | bool   | `false` | Recurse into subdirectories. Forwarded as `?recursive=true`.        |
| `--filter <expr>` | string |         | jq filter applied before rendering.                                 |

### `crewship crew files get <slug-or-id> <path>`

Stream a file from the crew shared volume. Defaults to stdout when no `--out` is given so the output is pipe-friendly; pass `--out <file>` (or `-` to force stdout) to land bytes on disk.

```bash theme={null}
crewship crew files get demo-crew shared/notes.md
crewship crew files get demo-crew shared/dump.bin --out /tmp/dump.bin
```

| Flag           | Type   | Default  | Description                             |
| -------------- | ------ | -------- | --------------------------------------- |
| `--out <path>` | string | (stdout) | Output path. `-` or empty means stdout. |

Disk writes use the same atomic-tempfile-then-`rename(2)` pattern as `agent files --download`, so a Ctrl-C or transport hiccup mid-copy does not clobber an existing good file.

### `crewship crew files save <slug-or-id> <path>`

Upload bytes to the crew shared volume. Source comes from `--file` (local path), `--content` (inline string), or stdin when neither flag is given. `--content` and `--file` are mutually exclusive.

```bash theme={null}
echo "hi" | crewship crew files save demo-crew shared/hi.txt
crewship crew files save demo-crew shared/note.md --content "draft"
crewship crew files save demo-crew shared/data.bin --file /tmp/data.bin
```

| Flag        | Type   | Default | Description                |
| ----------- | ------ | ------- | -------------------------- |
| `--content` | string |         | Inline content string.     |
| `--file`    | string |         | Local file path to upload. |

Save issues a raw `PUT /api/v1/crews/{crewId}/files/save?path=…` with `Content-Type: application/octet-stream` so binary uploads round-trip byte-for-byte.

***

## `crewship crew cache`

Manage the devcontainer image cache shared across crews. Cache tags use the `crewship-cache:*` prefix and are keyed by a hash of `devcontainer.json` + mise config + runtime image, so two crews with identical configs share a single image.

### `crewship crew cache list`

```bash theme={null}
crewship crew cache list
```

**Output columns:** TAG, SIZE, CREATED, USED BY (comma-joined list of crew slugs that reference the image — empty when unreferenced).

### `crewship crew cache prune`

Remove old or unreferenced cached images. With no flags, defaults to `--older-than 30d` and leaves referenced images alone.

```bash theme={null}
# Default — drop images older than 30 days, keep referenced ones
crewship crew cache prune

# Drop only images no crew currently points at
crewship crew cache prune --unused

# Tighter window
crewship crew cache prune --older-than 7d

# Scripted / CI
crewship crew cache prune --older-than 7d --force
```

| Flag           | Type     | Default                     | Description                                                  |
| -------------- | -------- | --------------------------- | ------------------------------------------------------------ |
| `--older-than` | `string` | `30d` *(when no flags set)* | Remove images older than this duration (e.g. `30d`, `72h`).  |
| `--unused`     | `bool`   | `false`                     | Remove only images not referenced by any crew.               |
| `--force`      | `bool`   | `false`                     | Skip interactive confirmation. Required in non-TTY sessions. |

<Warning>
  Pruning a referenced image forces the next `crewship crew provision` on that crew to rebuild from scratch (seconds to minutes). `--force` bypasses the confirmation prompt — use it only in scripts.
</Warning>

## See also

* [Guides → Devcontainers & Runtime Images](/guides/devcontainers) — end-to-end walkthrough of the provisioning pipeline.
* [Configuration → Devcontainers](/configuration/devcontainers) — flat reference for config fields and env vars.
* [`crewship features`](/cli/features) — browse the devcontainer feature catalog before editing `devcontainer.json`.
* [`crewship runtimes`](/cli/runtimes) — browse the mise runtime catalog before editing the mise config.