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

# Agent Commands

> Create, manage, and monitor AI agents with the Crewship CLI.

# crewship agent

Create, configure, and inspect the AI agents that do the work inside a crew. Reach for these commands to provision a new agent, tweak its adapter or model, browse its runs and chats, or peek inside its container (files, logs, git history, peer inbox).

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

## Subcommands

| Command       | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| `list`        | List all agents in the workspace                                       |
| `get`         | Show agent details                                                     |
| `create`      | Create a new agent                                                     |
| `update`      | Update an agent                                                        |
| `delete`      | Delete an agent                                                        |
| `runs`        | List runs for an agent                                                 |
| `chats`       | List recent chats for an agent (alias: `sessions`)                     |
| `stop`        | Stop a running agent                                                   |
| `logs`        | Show agent container logs                                              |
| `debug`       | Show agent debug info (container state, env, crewshipd status)         |
| `skills`      | List skills assigned to an agent                                       |
| `credentials` | List credentials assigned to an agent                                  |
| `mcp`         | Show or set MCP server configuration for an agent                      |
| `files`       | List files in the agent's working directory, or download a single file |
| `file-write`  | Write a file into the agent's working directory                        |
| `inbox`       | Show peer messages received by the agent                               |
| `git-log`     | Show git log inside the agent's container                              |

***

## `crewship agent list`

List all agents in the workspace.

```bash theme={null}
crewship agent list
crewship agent list --crew backend-team
```

| Flag     | Type     | Default | Description                |
| -------- | -------- | ------- | -------------------------- |
| `--crew` | `string` |         | Filter by crew slug or ID. |

**Output columns:** SLUG, ROLE, CREW, STATUS, ADAPTER, MEMORY

***

## `crewship agent get`

Show detailed information about an agent.

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

**Output fields:** Name, Slug, ID, Role, Role Title, Crew, Status, CLI Adapter, Tool Profile, Memory, Timeout, Created, Skills count, Credentials count.

***

## `crewship agent create`

Create a new agent.

```bash theme={null}
crewship agent create --name "Viktor" --crew backend-team --role LEAD
```

| Flag              | Type     | Default            | Description                                                                                                                                   |
| ----------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name`          | `string` | *(required)*       | Agent name.                                                                                                                                   |
| `--slug`          | `string` | *(auto from name)* | Agent slug.                                                                                                                                   |
| `--crew`          | `string` |                    | Crew slug or ID.                                                                                                                              |
| `--role`          | `string` | `AGENT`            | Agent role: `AGENT` or `LEAD`.                                                                                                                |
| `--role-title`    | `string` |                    | Human-readable role title.                                                                                                                    |
| `--cli-adapter`   | `string` | `CLAUDE_CODE`      | CLI adapter: `CLAUDE_CODE`, `CODEX_CLI`, `GEMINI_CLI`, `OPENCODE`, `CURSOR_CLI`, `FACTORY_DROID`.                                             |
| `--system-prompt` | `string` |                    | System prompt text or `@file.txt` to read from file.                                                                                          |
| `--tool-profile`  | `string` | `CODING`           | Tool profile: `MINIMAL`, `CODING`, `FULL`.                                                                                                    |
| `--llm-provider`  | `string` |                    | LLM provider: `ANTHROPIC`, `OPENAI`, `GOOGLE`.                                                                                                |
| `--llm-model`     | `string` |                    | LLM model (e.g., `claude-haiku-4-5`).                                                                                                         |
| `--memory`        | `bool`   | `false`            | Enable memory.                                                                                                                                |
| `--lead-mode`     | `string` |                    | Lead mode: `active` or `passive`.                                                                                                             |
| `--timeout`       | `int`    | `0`                | Timeout in seconds.                                                                                                                           |
| `--avatar-seed`   | `string` | *(agent name)*     | Avatar seed for avatar generation.                                                                                                            |
| `--avatar-style`  | `string` |                    | Avatar style: `bottts-neutral`, `adventurer`, `fun-emoji`, `pixel-art`, `micah`, `notionists`, `thumbs`, `lorelei`, `big-smile`, `avataaars`. |

<Tip>
  Use `@file.txt` syntax with `--system-prompt` to load the prompt from a file:

  ```bash theme={null}
  crewship agent create --name Viktor --system-prompt @prompts/backend-lead.md
  ```
</Tip>

***

## `crewship agent update`

Update an existing agent. Only changed flags are sent.

```bash theme={null}
crewship agent update <slug-or-id> --role LEAD --memory
```

| Flag              | Type     | Default | Description                                    |
| ----------------- | -------- | ------- | ---------------------------------------------- |
| `--name`          | `string` |         | Agent name.                                    |
| `--role`          | `string` |         | Agent role.                                    |
| `--role-title`    | `string` |         | Human-readable role title.                     |
| `--cli-adapter`   | `string` |         | CLI adapter.                                   |
| `--system-prompt` | `string` |         | System prompt text or `@file.txt`.             |
| `--tool-profile`  | `string` |         | Tool profile.                                  |
| `--llm-provider`  | `string` |         | LLM provider: `ANTHROPIC`, `OPENAI`, `GOOGLE`. |
| `--llm-model`     | `string` |         | LLM model.                                     |
| `--memory`        | `bool`   | `false` | Enable memory.                                 |
| `--lead-mode`     | `string` |         | Lead mode.                                     |
| `--timeout`       | `int`    | `0`     | Timeout in seconds.                            |
| `--avatar-seed`   | `string` |         | Avatar seed.                                   |
| `--avatar-style`  | `string` |         | Avatar style.                                  |

***

## `crewship agent delete`

Delete an agent. Prompts for confirmation unless `--yes` is passed.

```bash theme={null}
crewship agent delete <slug-or-id>
crewship agent delete viktor --yes
```

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

<Warning>
  Deletion is permanent. `--yes` skips the prompt — reserve it for scripts where you already know the slug is correct.
</Warning>

***

## `crewship agent runs`

List runs for an agent.

```bash theme={null}
crewship agent runs <slug-or-id>
```

**Output columns:** ID, STATUS, TRIGGER, CREATED, FINISHED

***

## `crewship agent stop`

Stop a running agent.

```bash theme={null}
crewship agent stop <slug-or-id>
```

***

## `crewship agent logs`

Show agent container logs.

```bash theme={null}
crewship agent logs <slug-or-id>
crewship agent logs viktor --tail 50
```

| Flag     | Type  | Default | Description                  |
| -------- | ----- | ------- | ---------------------------- |
| `--tail` | `int` | `100`   | Number of log lines to show. |

***

## `crewship agent debug`

Show agent debug info including container state, environment variables, and crewshipd status. Output is always JSON.

```bash theme={null}
crewship agent debug <slug-or-id>
```

***

## `crewship agent skills`

List skills assigned to an agent.

```bash theme={null}
crewship agent skills <slug-or-id>
```

**Output columns:** SKILL ID, NAME, CATEGORY, ENABLED

***

## `crewship agent credentials`

List credentials assigned to an agent.

```bash theme={null}
crewship agent credentials <slug-or-id>
```

**Output columns:** ID, NAME, PROVIDER, TYPE, ENV VAR

***

## `crewship agent mcp`

Show or set MCP server configuration for an agent.

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

# Show effective (merged crew + agent) config
crewship agent mcp <agent-slug> --resolved

# Set from inline JSON
crewship agent mcp <agent-slug> --set '{"mcpServers":{...}}'

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

| Flag         | Type     | Default | Description                                                        |
| ------------ | -------- | ------- | ------------------------------------------------------------------ |
| `--set`      | `string` |         | Set MCP config from JSON string. Pass empty string to clear.       |
| `--set-file` | `string` |         | Set MCP config from file path.                                     |
| `--resolved` | `bool`   | `false` | Show effective merged config (crew + agent). Agent overrides crew. |

<Note>
  The JSON must contain a `"mcpServers"` object at the top level. `--set` and `--set-file` are mutually exclusive. `--resolved` cannot be combined with set operations.
</Note>

***

## `crewship agent chats`

List the agent's recent chat sessions — id, title, status, message count, and start/end timestamps. Mirrors the **SessionsSidebar** panel in the web UI. Alias: `sessions`.

```bash theme={null}
crewship agent chats viktor
crewship agent chats viktor --format json | jq '.[] | select(.status=="ACTIVE")'
```

**Output columns:** CHAT ID, TITLE, STATUS, MSGS, STARTED, ENDED.

Backed by `GET /api/v1/agents/{id}/chats`.

***

## `crewship agent files`

List the agent's `/output/<slug>/` working-directory artefacts, or download a single file. Same view the web Files panel renders.

```bash theme={null}
crewship agent files viktor
crewship agent files viktor --download README.md
crewship agent files viktor --download report.txt --out /tmp/saved.txt
crewship agent files viktor --filter '.[] | .name'      # piped through the jq binary
```

| Flag                | Type   | Default          | Description                                                                                                                                             |
| ------------------- | ------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--download <name>` | string |                  | Download this file instead of listing.                                                                                                                  |
| `--out <path>`      | string | basename of file | Output path for `--download`. Pass `-` to stream the file body to stdout.                                                                               |
| `--filter <expr>`   | string |                  | jq filter applied before rendering (when not downloading). Piped through the external `jq` binary on `PATH`; if `jq` is absent the raw output is shown. |

Downloads stream into a tempfile next to the target and `rename(2)` only on success — Ctrl-C or transport errors mid-copy do not clobber an existing good file with a truncated one.

Backed by `GET /api/v1/agents/{id}/files` and `GET /api/v1/agents/{id}/files/download?path=…`.

***

## `crewship agent file-write`

Upload bytes to the agent's working directory. Source comes from `--from` (local file), `--content` (inline string), or stdin when neither flag is given. `--content` and `--from` are mutually exclusive.

```bash theme={null}
echo "draft" | crewship agent file-write viktor notes/draft.md
crewship agent file-write viktor config/x.toml --from ./local.toml
crewship agent file-write viktor README.md --content "# hi"
```

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

Backed by `PUT /api/v1/agents/{id}/files/save?path=<path>`. The handler reads `r.Body` raw — no JSON envelope — so binary uploads round-trip byte-for-byte.

***

## `crewship agent inbox`

List peer-to-peer messages addressed to this agent. Useful for debugging cross-agent collaboration: did the message arrive? was it read?

```bash theme={null}
crewship agent inbox viktor
crewship agent inbox viktor --filter '.[] | .from'
```

**Output columns:** WHEN, FROM (truncated to 15 chars), MESSAGE (truncated to 60 chars, newlines flattened).

Backed by `GET /api/v1/agents/{id}/inbox`.

***

## `crewship agent git-log`

Show the git commit log from inside the agent's container — useful for inspecting what code-writing agents have committed locally before any push.

```bash theme={null}
crewship agent git-log viktor
crewship agent git-log viktor --filter '.[] | .message'
crewship agent git-log viktor --format json
```

Default rendering prints short hash + relative date + truncated subject line. The handler tolerates both `[...]` and `{"commits":[...]}` shapes from the server side.

Backed by `GET /api/v1/agents/{id}/git-log`.