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.

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)
`work`	Take over an issue, hand it to a person or agent, or submit human work
`review-policy`	Require or drop human acceptance before an issue’s work counts as done
`result`	Show what one of an issue’s runs reported back
`activity`	Show the activity timeline for an issue
`events`	Show the ordered, seq-cursored event log for an issue (for resync after a dropped realtime frame)
`runs`	List runs triggered by an issue
`sessions`	List an issue’s agent sessions
`checkpoints`	List the checkpoints one of an issue’s agent sessions has written
`changes`	Show the git diff produced by work on 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
`links`	List the pull requests linked to an issue (aliases: `code-links`, `prs`)
`link`	Attach a pull request / merge request to an issue
`relink`	Re-read a linked pull request’s state from its provider (alias: `refresh-link`)
`unlink`	Remove a pull-request link from an issue
`attachments`	List the files attached to an issue (alias: `files`)
`attach`	Attach a local file to an issue
`attachment`	Download one attached file (alias: `download`)
`detach`	Remove an attached file from an issue (alias: `unattach`)
`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.

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"
crewship issue list --counts --crew backend-team

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 identifier, on the server (sent as `q`).
`--limit`	`int`	`50`	Rows per page (the server caps it at 500).
`--offset`	`int`	`0`	Skip this many rows. Page with `--offset 50`, `--offset 100`, …
`--counts`	`bool`	`false`	Also report how many issues sit in each status under the same filter (`?counts=1`, read from the `X-Status-Counts` header). A human table gains a `status counts: BACKLOG 12 · TODO 4 · DONE 31` line in workflow order; `json` / `yaml` switch from the bare array to `{ "issues": [...], "status_counts": { "TODO": 4, ... } }` (and `ndjson` emits that one object as its single line instead of one issue per line), since a header is invisible to `jq`. Opt-in, so pipelines that read the array today are unchanged.

Output columns: ID, TITLE, STATUS, PRIORITY, ASSIGNEE, CREATOR, CREW, LABELS, UPDATED A human table ends with showing 1–50 of 1 015 · next page: --offset 50, read from the X-Total-Count / X-Limit / X-Offset headers every paged list sends. Machine formats stay flat — json / yaml a bare array, ndjson one issue object per line — since scripts decode them directly (the one exception is --counts, above); quiet stays one id per line. The response also carries X-Has-More (#2286) for clients that only read that boolean.

`crewship issue get`

Show issue details including comments.

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, Owner, Delegate, Description, Due Date, Mission Type, Labels, Comments count, Created By, Created, Updated, ID. Owner and Delegate are the typed projection of the issue’s human owner and agent delegate (owner/delegate in the API — #2297, independent of each other and of the legacy Assignee/Assignee Type pair above). Each shows the resolved name, or - when nobody occupies that slot. In --format json / --format yaml, the same data is owner/delegate objects ({id, name}), omitted entirely when unset. 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.

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`.
`--status`	`string`	`BACKLOG`	Starting status: `BACKLOG`, `TODO`, `IN_PROGRESS`, `CANCELLED`, `DUPLICATE` — anything not one step from `BACKLOG` is refused with a 400.
`--assignee`	`string`		Who the issue goes to. With the default `--assignee-type agent`, an agent slug or ID (resolved client-side) — this sets the issue’s delegate. With `--assignee-type user`, a workspace member’s email or user ID — this sets the issue’s human owner.
`--assignee-type`	`string`	`agent`	`agent` (writes `delegate_agent_id`) or `user` (writes `owner_user_id`). Any other value is rejected before a request is sent.
`--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).

Owner and delegate are independent slots (#2297): assigning a person never clears the agent already delegated, and delegating to an agent never changes the owner. To clear both, crewship issue update <id> --assignee "".

`crewship issue update`

Update an issue. Only changed flags are sent.

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: an agent slug or ID (sets the delegate), or with `--assignee-type user` a member’s email or user ID (sets the human owner). Empty string clears both owner and delegate.
`--assignee-type`	`string`		`agent` or `user`; requires `--assignee` and defaults to `agent` when it is given. A type alone is refused without changing the assignment. Use `--assignee ""` to clear both slots.
`--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.
`--force`	`bool`	`false`	Move a parent to DONE/REVIEW even though a sub-issue or plan task is still open; the server writes a receipt naming who forced it and which children were open (the terminal-children rule, #2377). Sent as `?force=true`.

crewship issue update BE-42 --assignee jana@example.com --assignee-type user   # human owner
crewship issue update BE-42 --assignee franta                                  # agent delegate
crewship issue update BE-42 --status DONE --force

`crewship issue delete`

Delete an issue. Prompts for confirmation.

crewship issue delete <identifier>
crewship issue delete BE-42 --yes

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

Deletion is permanent. --yes skips the prompt — reserve it for scripts.

`crewship issue comment`

Add a comment to an issue.

crewship issue comment <identifier> This is a comment
crewship issue comment BE-42 --body "Detailed comment here"
crewship issue comment BE-42 --mention riley "the CSV job is failing on empty rows"
crewship issue comment BE-42 --mention riley --mention casey "over to you both"

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).
`--mention`	`string`		Mention an agent by slug. Repeatable. Resolved against the workspace agent roster (same lookup as `--assignee` elsewhere) and prepended to the body as the real `[@slug](crewship:agent/<id>)` link the server requires — one per mention, space-separated, before the rest of the text. Fails with a clear error naming the slug and the workspace’s real agents if a slug does not resolve. `--mention` alone with no other text is a valid comment.

A bare @slug typed into the body (positionally or via --body) is not a mention — it is plain text, and the mentioned agent is never notified or dispatched. The server only recognises the Markdown link form [@slug](crewship:agent/<agentId>) (internal/mentions, docs/guides/issue-mentions.mdx). Use --mention to write a real one.

`crewship issue labels`

List all workspace labels.

crewship issue labels

Output columns: NAME, COLOR, GROUP

`crewship issue work`

Take over an issue, hand it to a person or agent, or submit human work for review. Requires workspace OWNER, ADMIN, or MANAGER access. The owner stays accountable even when the current worker changes.

crewship issue work ENG-42
crewship issue work ENG-42 --action handoff_human --target user_123 --note "Verify the attached report"
crewship issue work ENG-42 --action handoff_agent --target agent_123 --note "Publish the approved version"
crewship issue work ENG-42 --action submit --note "Verified all findings against the source"

Flag	Type	Default	Description
`--action`	string	`take_over`	`take_over`, `handoff_human`, `handoff_agent`, or `submit`
`--target`	string	—	Workspace user or agent ID; required for a handoff
`--note`	string	—	Result, verification or next instructions; required except takeover
`--operation-id`	string	Generated	Stable operation ID when retrying the same request
`--revision`	integer	Current issue revision	Expected `work_revision`; pin this along with operation ID for an exact retry

An exact retry returns the saved receipt. A changed request under the same ID or a stale revision fails with a conflict. Human takeover fences new agent work and requests cancellation of active runs. Handback and submission wait until those runs have stopped. Handing back to an agent prepares a new step; use crewship issue start to execute it. submit moves human work to review.

`crewship issue review-policy`

Set whether a person has to accept the work before this issue counts as done. Requires workspace OWNER, ADMIN, or MANAGER access.

crewship issue review-policy ENG-42 --required
crewship issue review-policy ENG-42 --required=false
crewship issue review-policy ENG-42 --required --revision 3 -f json

Flag	Type	Default	Description
`--required`	boolean	—	Required. `--required` asks for acceptance, `--required=false` drops it
`--revision`	integer	Current issue revision	Expected `work_revision`; a concurrent change is refused rather than overwritten

The flag has no default on purpose: a bare call is refused rather than guessing, because dropping acceptance removes a gate somebody set. The policy can change only while the issue is TODO or BACKLOG with no live assignment — once work starts the server answers 409 instead of moving the goalposts under the worker.

`crewship issue result`

Print one run’s result summary, outcome and status — what the worker reported back, where crewship issue runs lists only that the run happened.

crewship issue runs ENG-42
crewship issue result ENG-42 m_1a0864071c85b082f6adb2c
crewship issue result ENG-42 m_1a0864071c85b082f6adb2c -f json

Takes the issue identifier and the assignment id — the id field of crewship issue runs <identifier> -f json. It is not the RUN column of that command’s table: that column is the journal trace id, and passing it answers 404 Run not found for this issue. A run that belongs to another issue answers 404 rather than reading across issues; a run that reported nothing says so instead of printing an empty result.

`crewship issue start`

Start an issue — dispatches work to the assigned agent.

crewship issue start <identifier>
crewship issue start BE-42

`crewship issue stop`

Stop an issue. Ships in two tiers, both fired by this one command:

Tier 1 (cooperative, always applied). Marks pending/in-progress tasks CANCELLED and stamps cancel_requested_at on every live assignment; a run that hasn’t started its exec yet never starts, and the runner polls the stamp at every step boundary. No further step is scheduled.
Tier 2 (hard, opt in with --hard). After the Tier 1 stamp lands, ends each live run’s own tmux session (tmux kill-session -t agent-{slug}, run as a brand-new exec into the run’s same container), escalating to a direct kill -KILL on that session’s own process group if it hasn’t exited after a short grace period. Most agent runs own a tmux session named for their own agent slug — a container-visible identity — so this never runs a container-level kill and never signals by OS pid: the crew’s container is shared by every agent on the crew, and a pid resolved from outside the container is not safe to signal from inside it (#2365 — the pre-fix mechanism did exactly that and silently signalled nothing). Only the run’s own session is ever touched; a sibling agent’s session keeps running untouched. A run whose exec bypassed tmux entirely (an oversized prompt delivered via stdin, or a container without tmux installed) has no session to end — confirmed first by listing its pane pids before touching anything, then reported NOT_FOUND immediately rather than sending a signal that reaches nothing. Bounded to a few seconds; what was signalled and the result (TERMINATED_TERM, TERMINATED_KILL, ALREADY_EXITED, NOT_FOUND, PENDING_EXEC — the run was RUNNING but its exec had not appeared within the wait window, so there was nothing to signal yet; Tier 1’s stamp still ends it CANCELLED when it reports back — UNSUPPORTED, ERROR) is recorded on the run (also readable via crewship issue runs -f json’s hard_stop_result/hard_stop_at) and in the issue’s journal. Without --hard, a step already mid-exec simply finishes that exec and is then recorded CANCELLED regardless of what it reports — nothing mid-exec is interrupted.

Also reaches a run an @mention dispatched on an issue that was never started (BACKLOG/TODO): the assignment gets the same cancel_requested_at stamp (and, with --hard, the same signal if it’s already RUNNING), and the issue’s own status is left unchanged. stop still refuses when the issue is not IN_PROGRESS/REVIEW and has no live run to reach.

crewship issue stop <identifier>
crewship issue stop BE-42
crewship issue stop BE-42 --hard

Flag	Type	Default	Description
`--hard`	`bool`	`false`	Also terminate the running process (Tier 2). Cooperative stop alone only prevents further work from starting; a step already mid-exec is left to finish on its own.

`crewship issue review`

Review an issue — approve or request changes.

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`).
`--revision`	`int`	(current)	Expected work revision. Defaults to the one the command just read from the issue; pin it to the value you actually reviewed and a concurrent change is refused instead of approved blind.
`--brief-revision`	`int`	(current)	Expected brief revision, same rule.

The review is a compare-and-set (#2448). The command always sends both revisions, so a plain call is safe; the server answers 409 and leaves the issue where it is when:

the revision or brief revision no longer matches (The issue changed. Refresh before reviewing.);
a run or a Lead review is still live on the issue (Work or Lead review is still running — issue stop it or wait);
on approve, a person submitted the work and the brief changed after that submission (Submit an updated result before approving);
on approve, the latest agent execution ran against an older brief (Run the updated work before approving).

400 when the issue is not IN_PROGRESS/REVIEW. Full rules: API reference → Issues → Review Issue.

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

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.

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

The same mission_activity rows as activity, but ordered by seq (the B1 event log’s monotonic per-issue cursor) instead of created_at, and NOT capped at 50 — this is the endpoint the board’s client-side gap detector calls to resync after a WebSocket frame is dropped under load (F43, work package B11, #2368). Hits GET /api/v1/crews/{crewId}/issues/{ident}/events?after_seq=. The server caps a single response at 500 rows; the CLI (like the client-side gap detector) follows after_seq pages automatically until it has everything up to the issue’s current latest_seq, so --format json’s events array is always the full requested range, never just the first page.

crewship issue events BE-42                    # full history, seq order
crewship issue events BE-42 --after-seq 42     # only what happened after seq 42
crewship issue events BE-42 --format json | jq '.latest_seq'
crewship issue events BE-42 --before-seq 0 --limit 20    # the newest 20 events
crewship issue events BE-42 --before-seq 81 --limit 20   # the 20 before seq 81

Flag	Type	Default	Description
`--after-seq`	`int`	`0`	Only return events with `seq` greater than this. `0` returns the full history.
`--before-seq`	`int`	—	Read ONE page of older events: the newest `--limit` events with `seq` below this (`0` = from the newest). JSON adds `before_seq` and `has_older`. Cannot be combined with `--after-seq`.
`--limit`	`int`	`0`	Page size for `--before-seq` (server cap 500).

Output columns: SEQ, WHEN (relative time), ACTOR (type/name), ACTION, DETAILS (truncated to 60 chars). In --format json, the response is {"events": [...], "after_seq": N, "latest_seq": N} — latest_seq is the issue’s current high-water mark, so a client with no new events can still tell “caught up at N” from “server has never heard of this issue”.

`crewship issue runs`

List every run attributed to an issue — mission tasks, mention-dispatched runs, and delegation-hop runs alike — the data the dashboard’s issue “Runs” tab shows. Hits GET /api/v1/crews/{crewId}/issues/{ident}/runs after resolving <identifier> to its crew via fetchIssue.

crewship issue runs BE-42
crewship issue runs BE-42 --format json | jq '.[] | select(.source=="mention")'
crewship issue runs BE-42 --limit 20 --offset 20

Flag	Type	Default	Description
`--limit`	`int`	`100`	Runs per page (the server caps it at 500).
`--offset`	`int`	`0`	Skip this many runs; the footer names the next page.

Output columns: RUN (the journal run id — what crewship journal --run-id and the Activity page take; — when the assignment never reached a run), AGENT (slug), TASK (truncated to 28), STATUS, OUTCOME, STARTED (relative time), DURATION, SOURCE, RESULT (error message or result summary; ANSI-sanitised, truncated to 50 chars). SOURCE is why the run is attributed to the issue: task (the issue’s own mission-task plan), mention (an @mention dispatch), or delegation (a sub-agent’s own further /assign call mid-mission). In --format json, the same run also carries mission_id (the issue’s mission ID; omitted on a legacy row that predates assignments.mission_id), run_id / trace_id, agent_id and agent_slug, and hard_stop_result / hard_stop_at (work package B7b, #2365) — what a Tier 2 issue stop --hard did to this run and when, omitted on a run that was never hard-stopped. Not shown as a table column; read it with --format json so a live check can confirm a hard stop actually landed without reading the journal. OUTCOME is the §9.6 routing decision (work package B6, #2349) — NO_CHANGE, SUCCEEDED, WORK_CREATED, PARTIAL, NEEDS_HUMAN, FAILED, or CANCELLED; - on a run that predates the outcome column. It answers a different question than STATUS: a COMPLETED run that never reported a recognised outcome shows FAILED here, with its error naming "no outcome reported" — an absent outcome is treated as a bug, not a silent success. NEEDS_HUMAN is the one outcome that raises an inbox item (crewship inbox list --kind run_needs_human). Full vocabulary and routing table: API reference → Issues → Outcome.

`crewship issue sessions`

Session lifecycle: issue_agent_sessions is work package B1 of the Issues & Routines architecture (docs/prd/PRD-ISSUES-AND-ROUTINES-2026.md). A mention resolves or creates a session — mentioning the same agent on the same issue twice reuses it rather than creating a second. As of B4 (#2348) the session’s state moves pending → active → idle/error with active_run_id set while a run is live; since B6 (#2358) a run that reports NEEDS_HUMAN parks the session in awaiting_input until the inbox item is answered. Only the idle → stale sweep is not wired yet — nothing writes stale. As of B5 (#2345), every session-bearing dispatch also reads the session back into the agent’s context — see crewship issue checkpoints below and Sessions, checkpoints and the context pack.

List the durable, per-(issue, agent) sessions a mention has opened on an issue. Hits GET /api/v1/crews/{crewId}/issues/{ident}/sessions after resolving <identifier> to its crew via fetchIssue.

crewship issue sessions BE-42
crewship issue sessions BE-42 --format json

Output columns: AGENT, STATE, LAST SEQ (last_consumed_seq), VERSION (agent_version, - when the agent has no config history), UPDATED (relative time).

`crewship issue checkpoints`

Work package B5 of the Issues & Routines architecture (docs/prd/PRD-ISSUES-AND-ROUTINES-2026.md §9.5, #2345). A checkpoint is the done/plan/facts/blockers/next_step/confidence block a session-bearing run reports when it finishes; the next run on the same session is handed the latest one as part of its §11.1 context pack, so it does not repeat completed work.

List a session’s checkpoint history. Hits GET /api/v1/crews/{crewId}/issues/{ident}/sessions/{sessionId}/checkpoints after resolving <identifier> to its crew via fetchIssue and the session via GET .../sessions.

crewship issue checkpoints BE-42                    # only works when the issue has exactly one session
crewship issue checkpoints BE-42 --agent backend-dev
crewship issue checkpoints BE-42 --agent backend-dev --format json

Flag	Type	Default	Description
`--agent`	`string`	`""`	Agent slug or id whose session to read. Required when the issue has more than one session; a slug/id that resolves to an agent with no session on this issue errors by name.

Output columns: RUN (the run that wrote it, - if none), SEQ (seq_at_write), DONE (truncated to 40), NEXT STEP (truncated to 40), CONFIDENCE, PARSED (true/false — false means the run ended without a valid ---CHECKPOINT--- block), CREATED (relative time).

`crewship issue changes`

Show the base-branch git diff produced by the crew working an issue — the data the dashboard’s issue “Changes” tab renders. Hits GET /api/v1/crews/{crewId}/git-diff.

crewship issue changes BE-42
crewship issue changes BE-42 --patch   # print the raw unified diff

Flag	Type	Default	Description
`--patch`	`bool`	`false`	Print the raw unified diff instead of the per-file summary.

Without --patch, prints a per-file summary table (STATUS, FILE, +, −). When the crew workspace has no git repo, prints No git repository in this crew's workspace — nothing to diff.; with no changes against the base branch, prints No changes against the base branch.

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

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.

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.

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

crewship issue unrelate rel_01HVZ...

`crewship issue link`

Attach a GitHub pull request or GitLab merge request to an issue. Wraps POST /api/v1/crews/{crewId}/issues/{ident}/code-links.

crewship issue link BE-42 https://github.com/acme/thing/pull/7
crewship issue link BE-42 https://gitlab.com/acme/thing/-/merge_requests/7
crewship issue link BE-42 https://ghe.acme.internal/platform/gw/pull/12

The provider is recognised from the URL’s path (/pull/ → GitHub, /-/merge_requests/ → GitLab), so recognising a self-hosted instance of either needs no provider-specific configuration. Crewship then fetches the request through that provider’s API using a stored GITHUB / GITLAB credential in the workspace. Two things a self-hosted forge does still need: a credential labelled with its host (below), and — if it lives on a private/intranet address — the operator opt-in described in Git links. Without the opt-in the fetch is refused with blocked-host. For a self-hosted forge, set the credential’s account label to the forge’s host so it is matched by host:

crewship credential create --name ghe-ro --type SECRET --provider GITHUB \
  --account-label ghe.acme.internal --value-stdin

Common failures (each a distinct RFC 7807 code): no-credential (412), blocked-host (422 — the forge is on a private address; see Git links), credential-rejected (502 — the token was revoked), rate-limited (429), already-linked (409).

`crewship issue links`

List an issue’s pull-request links. Aliases: code-links, prs.

crewship issue links BE-42

Output columns: ID, STATE, REF (owner/repo#number), TITLE, BRANCH (source → target), SYNCED. A link whose last refresh failed shows its state as … (stale) — the data is the last one successfully fetched.

`crewship issue relink`

Re-read a link’s state from its provider. Alias: refresh-link. State is never polled in the background; this is how you ask again.

crewship issue relink BE-42 cmsezurje0003d5e624ad

A failed refresh keeps the last known state and records why on the link.

`crewship issue unlink`

Remove a link by its link ID (the first column of issue links).

crewship issue unlink BE-42 cmsezurje0003d5e624ad

`crewship issue attach`

Attach a local file to an issue. Wraps POST /api/v1/crews/{crewId}/issues/{ident}/attachments.

crewship issue attach BE-42 ./crash.log
crewship issue attach BE-42 ~/Desktop/screenshot.png

The type is decided by the file’s extension, against an allowlist — never by what the client claims, because a server that trusted a client-supplied content type would store and later serve markup from its own origin. Allowed: .txt .log .md .csv .tsv .json .yaml .yml .toml .xml .diff .patch .png .jpg .jpeg .gif .webp .avif .pdf .zip .gz .tgz. Anything else is refused with a 415 that lists the set. Maximum 25 MiB; a larger file is refused locally, naming its size, before anything is uploaded. Attaching the same bytes twice is the same attachment, so a retry is safe and does not add a second timeline entry. The agent working the issue can read what you attach — see Issue attachments.

`crewship issue attachments`

List an issue’s attached files. Alias: files.

crewship issue attachments BE-42

Output columns: ID, FILENAME, TYPE, SIZE, BY ((agent) when an agent attached it), ADDED. Filenames are printed with control bytes stripped — they are chosen by whoever uploaded the file.

`crewship issue attachment`

Download one attachment by its attachment ID (the first column of issue attachments). Alias: download.

crewship issue attachment BE-42 cmsf1a2b30001d5e6aa11 | less
crewship issue attachment BE-42 cmsf1a2b30001d5e6aa11 -o ./crash.log

Flag	Short	Description
`--output-file`	`-o`	Write the file to this path instead of stdout

Without -o the bytes go to stdout, so the command composes with a pager or a pipeline. The server’s stored filename is never used to choose a local destination: it is a value someone else typed, and letting it name a path is how a download writes somewhere you did not ask for.

`crewship issue detach`

Remove an attachment by its attachment ID. Alias: unattach.

crewship issue detach BE-42 cmsf1a2b30001d5e6aa11

The stored bytes go too — but only if no other issue, comment or chat in the workspace still references the same file. Attachments are stored by content, so two issues carrying an identical file share one copy.

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

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

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

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.

​crewship issue

​Subcommands

​crewship issue list

​crewship issue get

​Who created an issue

​crewship issue create

​crewship issue update

​crewship issue delete

​crewship issue comment

​crewship issue labels

​crewship issue work

​crewship issue review-policy

​crewship issue result

​crewship issue start

​crewship issue stop

​crewship issue review

​crewship issue comments

​crewship issue activity

​crewship issue events

​crewship issue runs

​crewship issue sessions

​crewship issue checkpoints

​crewship issue changes

​crewship issue subtasks

​crewship issue relate

​crewship issue relations

​crewship issue unrelate

​crewship issue link

​crewship issue links

​crewship issue relink

​crewship issue unlink

​crewship issue attach

​crewship issue attachments

​crewship issue attachment

​crewship issue detach

​crewship issue bind-routine

​crewship issue unbind-routine

​crewship issue bulk update

crewship issue

Subcommands

`crewship issue list`

`crewship issue get`

Who created an issue

`crewship issue create`

`crewship issue update`

`crewship issue delete`

`crewship issue comment`

`crewship issue labels`

`crewship issue work`

`crewship issue review-policy`

`crewship issue result`

`crewship issue start`

`crewship issue stop`

`crewship issue review`

`crewship issue comments`

`crewship issue activity`

`crewship issue events`

`crewship issue runs`

`crewship issue sessions`

`crewship issue checkpoints`

`crewship issue changes`

`crewship issue subtasks`

`crewship issue relate`

`crewship issue relations`

`crewship issue unrelate`

`crewship issue link`

`crewship issue links`

`crewship issue relink`

`crewship issue unlink`

`crewship issue attach`

`crewship issue attachments`

`crewship issue attachment`

`crewship issue detach`

`crewship issue bind-routine`

`crewship issue unbind-routine`

`crewship issue bulk update`