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

# Issue Commands

> Issue tracking with labels, comments, and agent dispatch.

# crewship issue

Issue tracking wired directly into agent dispatch. Use these commands to create and triage issues, manage labels, comments, relations, and sub-issues, and hand work to an assigned agent (`start` / `stop` / `review`). Issues can also be bound to a routine so a fixed workflow runs whenever the issue is started.

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

**Alias:** `crewship issues`

## Subcommands

| Command          | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| `list`           | List issues in the workspace                                     |
| `get`            | Show issue details                                               |
| `create`         | Create a new issue                                               |
| `update`         | Update an issue                                                  |
| `delete`         | Delete an issue                                                  |
| `comment`        | Add a comment to an issue                                        |
| `comments`       | List comments on an issue                                        |
| `labels`         | List workspace labels                                            |
| `start`          | Start an issue (dispatch to assigned agent)                      |
| `stop`           | Stop an issue (cancel running tasks)                             |
| `review`         | Review an issue (approve or request changes)                     |
| `activity`       | Show the activity timeline for an issue                          |
| `subtasks`       | List sub-issues of an issue (aliases: `subissues`, `sub-issues`) |
| `relate`         | Create a relation between two issues                             |
| `relations`      | List relations for an issue (alias: `relates`)                   |
| `unrelate`       | Remove a relation by relation ID                                 |
| `bind-routine`   | Bind a routine slug to an issue (sets `routine_id`)              |
| `unbind-routine` | Clear the routine binding on an issue                            |
| `bulk update`    | Apply the same patch to up to 100 issues in one round-trip       |

***

## `crewship issue list`

List issues in the workspace with optional filters.

```bash theme={null}
crewship issue list
crewship issue list --status IN_PROGRESS --crew backend-team
crewship issue list --priority high --label bug
crewship issue list --search "auth flow"
```

| Flag         | Type     | Default | Description                                                                                               |
| ------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `--status`   | `string` |         | Filter by status: `BACKLOG`, `TODO`, `IN_PROGRESS`, `REVIEW`, `DONE`, `FAILED`, `CANCELLED`, `DUPLICATE`. |
| `--priority` | `string` |         | Filter by priority: `none`, `low`, `medium`, `high`, `urgent`.                                            |
| `--crew`     | `string` |         | Filter by crew slug or ID.                                                                                |
| `--assignee` | `string` |         | Filter by assignee ID.                                                                                    |
| `--label`    | `string` |         | Filter by label name.                                                                                     |
| `--search`   | `string` |         | Search issues by title or description.                                                                    |
| `--limit`    | `int`    | `50`    | Maximum number of issues to return.                                                                       |

**Output columns:** ID, TITLE, STATUS, PRIORITY, ASSIGNEE, CREATOR, CREW, LABELS, UPDATED

***

## `crewship issue get`

Show issue details including comments.

```bash theme={null}
crewship issue get <identifier>
crewship issue get BE-42
```

The identifier can be the issue identifier (e.g., `BE-42`) or the full ID.

**Output fields:** Identifier, Title, Status, Priority, Crew, Assignee, Assignee Type, Description, Due Date, Mission Type, Labels, Comments count, Created By, Created, Updated, ID.

Comments are displayed below the detail section.

### Who created an issue

Every issue records its creator. The `Created By` field (and the `CREATOR`
column in `issue list`) shows the resolved name, suffixed with `(agent)` when
the issue was created by an agent through a tool call rather than by a human:

```
Created By   Scout (agent)     # created by the "Scout" agent
Created By   Pavel Srba        # created by a human via the API/UI
Created By   -                 # legacy issue, predates creator attribution
```

In `--output json`, the same information is available as the `created_by`
object (`{type, id, name}`, where `type` is `user` or `agent`) plus
`authored_via` (`user_api` or `agent_tool_call`).

***

## `crewship issue create`

Create a new issue.

```bash theme={null}
crewship issue create --crew backend-team --title "Fix login bug" --priority high
crewship issue create --crew backend-team --title "Add caching" --assignee viktor --labels <label-id>
```

| Flag                | Type      | Default      | Description                                                      |
| ------------------- | --------- | ------------ | ---------------------------------------------------------------- |
| `--crew`            | `string`  | *(required)* | Crew slug or ID.                                                 |
| `--title`           | `string`  | *(required)* | Issue title.                                                     |
| `--description`     | `string`  |              | Issue description.                                               |
| `--priority`        | `string`  | `none`       | Priority: `none`, `low`, `medium`, `high`, `urgent`.             |
| `--assignee`        | `string`  |              | Assignee agent slug or user email.                               |
| `--assignee-type`   | `string`  | `agent`      | Assignee type: `agent` or `user`.                                |
| `--labels`          | `string`  |              | Comma-separated label IDs.                                       |
| `--due-date`        | `string`  |              | Due date in ISO 8601 format.                                     |
| `--project-id`      | `string`  |              | Attach to a project (ID).                                        |
| `--milestone-id`    | `string`  |              | Attach to a milestone (ID).                                      |
| `--parent-issue-id` | `string`  |              | Make this a sub-issue of the given parent (issue ID).            |
| `--estimate`        | `int`     | `0`          | Effort estimate (story points or hours, depending on workspace). |
| `--sort-order`      | `float64` | `0`          | Manual sort order within a list (lower = top).                   |
| `--routine-id`      | `string`  |              | Bind to a routine (pipeline ID).                                 |

***

## `crewship issue update`

Update an issue. Only changed flags are sent.

```bash theme={null}
crewship issue update <identifier> --status IN_PROGRESS
crewship issue update BE-42 --priority urgent --assignee franta
```

| Flag                | Type      | Default | Description                                                                                         |
| ------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------- |
| `--title`           | `string`  |         | New title.                                                                                          |
| `--description`     | `string`  |         | New description.                                                                                    |
| `--status`          | `string`  |         | New status: `BACKLOG`, `TODO`, `IN_PROGRESS`, `REVIEW`, `DONE`, `FAILED`, `CANCELLED`, `DUPLICATE`. |
| `--priority`        | `string`  |         | New priority: `none`, `low`, `medium`, `high`, `urgent`.                                            |
| `--assignee`        | `string`  |         | New assignee (agent slug).                                                                          |
| `--assignee-type`   | `string`  |         | Assignee type: `agent` or `user`.                                                                   |
| `--due-date`        | `string`  |         | Due date (ISO 8601).                                                                                |
| `--project-id`      | `string`  |         | Project ID (empty string = unlink).                                                                 |
| `--milestone-id`    | `string`  |         | Milestone ID (empty string = unlink).                                                               |
| `--parent-issue-id` | `string`  |         | Parent issue ID (empty string = make top-level).                                                    |
| `--estimate`        | `int`     | `0`     | Effort estimate.                                                                                    |
| `--sort-order`      | `float64` | `0`     | Manual sort order.                                                                                  |
| `--routine-id`      | `string`  |         | Routine (pipeline) ID; empty string = unbind.                                                       |

***

## `crewship issue delete`

Delete an issue. Prompts for confirmation.

```bash theme={null}
crewship issue delete <identifier>
crewship issue delete BE-42 --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.
</Warning>

***

## `crewship issue comment`

Add a comment to an issue.

```bash theme={null}
crewship issue comment <identifier> This is a comment
crewship issue comment BE-42 --body "Detailed comment here"
```

The comment body can be passed as positional arguments after the identifier, or via the `--body` flag (which takes precedence).

| Flag     | Type     | Default | Description                                    |
| -------- | -------- | ------- | ---------------------------------------------- |
| `--body` | `string` |         | Comment body (alternative to positional args). |

***

## `crewship issue labels`

List all workspace labels.

```bash theme={null}
crewship issue labels
```

**Output columns:** NAME, COLOR, GROUP

***

## `crewship issue start`

Start an issue -- dispatches work to the assigned agent.

```bash theme={null}
crewship issue start <identifier>
crewship issue start BE-42
```

***

## `crewship issue stop`

Stop an issue -- cancels running tasks.

```bash theme={null}
crewship issue stop <identifier>
crewship issue stop BE-42
```

***

## `crewship issue review`

Review an issue -- approve or request changes.

```bash theme={null}
crewship issue review BE-42 --action approve
crewship issue review BE-42 --action request_changes --comment "Needs more tests" --reassign franta
```

| Flag         | Type     | Default      | Description                                        |
| ------------ | -------- | ------------ | -------------------------------------------------- |
| `--action`   | `string` | *(required)* | Review action: `approve` or `request_changes`.     |
| `--comment`  | `string` |              | Review comment.                                    |
| `--reassign` | `string` |              | Agent slug to reassign to (for `request_changes`). |

***

## `crewship issue comments`

List comments on an issue. Hits `GET /api/v1/crews/{crewId}/issues/{ident}/comments` after resolving `<identifier>` to its crew via `fetchIssue`.

```bash theme={null}
crewship issue comments BE-42
```

**Output columns:** ID, AUTHOR, TYPE, BODY (truncated to 60 chars, newlines flattened), CREATED.

***

## `crewship issue activity`

Dump the mission-activity timeline for an issue. Hits `GET /api/v1/crews/{crewId}/issues/{ident}/activity`. Server caps the result at 50 rows DESC — pipe through `jq` if you need older history.

```bash theme={null}
crewship issue activity BE-42
crewship issue activity BE-42 --format json | jq '.[] | select(.action=="status_changed")'
```

**Output columns:** WHEN (relative time), ACTOR (`type/name`), ACTION, DETAILS (truncated to 60 chars).

***

## `crewship issue subtasks`

List sub-issues — children whose `parent_issue_id` equals this issue's id. Mirrors the **SubIssues** panel on the issue-detail page.

Aliases: `subissues`, `sub-issues`.

```bash theme={null}
crewship issue subtasks BE-42
crewship issue subissues BE-42                # alias
```

**Output columns:** ID, TITLE (truncated to 50), STATUS, PRIORITY, ASSIGNEE.

***

## `crewship issue relate`

Create a typed link between two issues. Wraps `POST /api/v1/crews/{crewId}/issues/{ident}/relations`.

```bash theme={null}
crewship issue relate BE-42 BE-50 --type blocks
crewship issue relate BE-42 BE-50 --type blocked-by   # hyphens auto-normalised to underscores
```

| Flag     | Default      | Description                                                                                                                                                    |
| -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--type` | `relates_to` | Relation type: `blocks`, `blocked_by`, `relates_to`, `duplicate_of`. Hyphenated forms (`blocked-by`, `relates-to`, `duplicate-of`) are normalised client-side. |

## `crewship issue relations`

List existing relations on an issue. Alias: `relates`.

```bash theme={null}
crewship issue relations BE-42
```

**Output columns:** ID, TYPE, TARGET (identifier), TITLE (truncated to 40), STATUS.

## `crewship issue unrelate`

Remove a relation by its **relation ID** (not the issue identifier). Hits `DELETE /api/v1/relations/{id}`.

```bash theme={null}
crewship issue unrelate rel_01HVZ...
```

***

## `crewship issue bind-routine`

Bind a routine slug to an issue — the server stores the underlying `routine_id` (pipeline UUID) so subsequent routine renames don't break the link. Wraps `PATCH /api/v1/crews/{crewId}/issues/{ident}` with `{"routine_id": <id>}`.

```bash theme={null}
crewship issue bind-routine BE-42 my-pr-review-routine
```

The slug is resolved client-side via the workspace's routine list before the PATCH, so a typo surfaces as `routine "xyz": <404>` instead of a silent no-op.

## `crewship issue unbind-routine`

Clear the routine binding (server normalises empty string to SQL `NULL`).

```bash theme={null}
crewship issue unbind-routine BE-42
```

***

## `crewship issue bulk update`

Apply the same field updates to up to 100 issues in a single round-trip. Wraps `PATCH /api/v1/issues/bulk`. The 100-id cap is enforced both client-side (friendly error) and server-side (400).

```bash theme={null}
crewship issue bulk update --ids ms_a,ms_b,ms_c --status DONE
crewship issue bulk update --ids ms_a,ms_b --priority high --assignee agent_xyz
crewship issue bulk update --ids ms_a,ms_b --labels lbl_bug,lbl_p0
```

| Flag              | Type   | Default      | Description                                                                                                   |
| ----------------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------- |
| `--ids`           | string | *(required)* | Comma-separated issue IDs (CUIDs, not identifiers). Empty entries are stripped; >100 entries reject locally.  |
| `--status`        | string |              | New status for all listed issues.                                                                             |
| `--priority`      | string |              | New priority.                                                                                                 |
| `--assignee`      | string |              | Assignee ID (NOT a slug — bulk callers tend to script with IDs). Empty string clears the assignee.            |
| `--assignee-type` | string | `agent`      | Forwarded only when `--assignee` is non-empty.                                                                |
| `--project`       | string |              | Project ID. Empty string unlinks the issue from its project.                                                  |
| `--labels`        | string |              | Comma-separated label IDs. **REPLACES** the existing label set on each issue; empty string clears all labels. |

At least one of `--status` / `--priority` / `--assignee` / `--project` / `--labels` must be supplied. Response surfaces as `Bulk update applied to <updated>/<requested> issue(s).` — the two counts differ when some IDs were 404 or 403.