> ## 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. # Project > Group missions and issues under a delivery project. Status, priority, health, progress, breakdown stats. # crewship project Projects are the unit of delivery — a named bundle of missions, issues, and crews working toward a target date. They carry status, priority, and health independently, so a planning dashboard can show "in progress / at risk / 60% complete" without reading every issue. Aliases: `projects`. Defined in `cmd/crewship/cmd_project.go`. ```bash theme={null} crewship project [flags] ``` Every subcommand requires `crewship login` plus an active workspace. The PATCH/DELETE surface mirrors `internal/api/project_handler.go` — fields you don't set with `Changed()` aren't sent, so partial updates won't clobber unrelated columns. ## Subcommands | Command | Purpose | | ------------------------------------------ | ------------------------------------------------------------------------------- | | `project list` | List every project in the workspace with progress + health. | | `project create` | Create a project. | | `project get ` | Show detail view (issues totals, lead, target, description). | | `project update ` | Patch any mutable field. | | `project delete ` | Delete the project. Issues are unlinked (set `project_id = NULL`), not deleted. | | `project stats ` | Breakdown by status / assignee / label / crews. | | `project milestone list ` | List milestones for a project. | | `project milestone create --name ` | Create a milestone. | | `project milestone update ` | Patch a milestone. | | `project milestone delete ` | Delete a milestone (prompts unless `-y`). Aliases: `remove`, `rm`. | ## Flags ### `project create` | Flag | Default | Effect | | ------------------------ | ---------- | ------------------------------------------------------------------------ | | `--name ` | (required) | Display name. | | `--description ` | (unset) | Free-text description. | | `--color ` | (unset) | Hex color (e.g. `#3B82F6`). | | `--icon ` | (unset) | Lucide icon name. | | `--status ` | `planned` | `backlog`, `planned`, `in_progress`, `paused`, `completed`, `cancelled`. | | `--priority ` | `none` | `none`, `low`, `medium`, `high`, `urgent`. | | `--lead-id ` | (unset) | User or agent ID that leads the project. | | `--lead-type ` | (unset) | `user` or `agent`. | | `--start-date ` | (unset) | ISO date (e.g. `2026-05-01`). | | `--target-date ` | (unset) | ISO date target. | ### `project update` Every flag is opt-in — only fields the user actually set hit the wire. Pass an explicit empty string to clear a nullable column. | Flag | Effect | | | | | | | ------------------------ | -------------------- | -------- | ------------ | -------- | ----------- | ------------ | | `--name ` | Rename. | | | | | | | `--description ` | Replace description. | | | | | | | `--icon ` | Lucide icon. | | | | | | | `--color ` | Hex color. | | | | | | | `--status ` | \`backlog | planned | in\_progress | paused | completed | cancelled\`. | | `--priority ` | \`none | low | medium | high | urgent\`. | | | `--health ` | \`on\_track | at\_risk | off\_track | on\_hold | complete\`. | | | `--lead-id ` | Lead user/agent ID. | | | | | | | `--lead-type ` | `user` or `agent`. | | | | | | | `--start-date ` | ISO start date. | | | | | | | `--target-date ` | ISO target date. | | | | | | ### `project delete` | Flag | Default | Effect | | ------------- | ------- | ----------------------------- | | `-y`, `--yes` | `false` | Skip the confirmation prompt. | ## Examples ### List ```bash theme={null} crewship project list # NAME STATUS PRIORITY HEALTH ISSUES PROGRESS TARGET # Onboarding rewrite in_progress high on_track 4/12 33% 2026-06-30 # Q3 platform-eng planned medium - 0/0 0% - ``` ### Create ```bash theme={null} crewship project create \ --name "Mobile launch" \ --status in_progress \ --priority high \ --target-date 2026-07-15 \ --lead-id usr_abc \ --lead-type user ``` ### Get details ```bash theme={null} crewship project get mobile-launch # Name Mobile launch # Status in_progress # Priority high # Health on_track # Lead Petra Nováková # Issues 12 total, 4 done # Progress 33% # Target 2026-07-15 # Description Phase 1 — auth + onboarding only. ``` ### Update ```bash theme={null} # Bump the health and slip the target date. crewship project update mobile-launch --health at_risk --target-date 2026-08-15 ``` You can clear a nullable field by passing an empty string explicitly — `--description ""` removes the description, while omitting the flag leaves it untouched. ### Breakdown stats ```bash theme={null} crewship project stats mobile-launch # Issues: 12 total / 4 completed (33%) # # By status: # todo 5 # in_progress 3 # done 4 # # By assignee: # daniel 6 total / 2 done # viktor 4 total / 2 done # # By label: # bug 3 # feature 7 # # Crews: [code-review onboarding] ``` `--format json` returns the raw shape for piping into jq. ### Delete ```bash theme={null} crewship project delete mobile-launch # Delete project "mobile-launch"? (issues will be unlinked, not deleted) [y/N] ``` Delete unlinks every issue and mission (sets `project_id = NULL` in the same transaction) so the destroy doesn't cascade into issue loss — but the project itself is gone. Prompts unless `-y`. ### Milestones Each project carries an ordered list of milestones (named delivery checkpoints with an optional target date). Backed by `/api/v1/projects/{id}/milestones` for list/create and `/api/v1/milestones/{id}` for update/delete (see `internal/api/milestone_handler.go`). Alias on the parent verb: `milestones`. ```bash theme={null} # List milestones — columns: ID, NAME, STATUS, TARGET, ISSUES (done/total), POS crewship project milestone list mobile-launch # Create crewship project milestone create mobile-launch \ --name "Phase 1 — onboarding" \ --target-date 2026-06-15 \ --status active # Update (any subset of fields) crewship project milestone update mil_abc123 \ --status completed --position 2 # Delete (prompts unless --yes) crewship project milestone delete mil_abc123 --yes crewship project milestones rm mil_abc123 --yes # alias on the group + verb ``` | Verb | Flags | Notes | | -------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `create` | `--name` (required), `--description`, `--target-date` (ISO 8601), `--status` (default `active`) | Posts to `/projects/{id}/milestones`. | | `update` | `--name`, `--description`, `--target-date`, `--status`, `--position` | PATCH; only flags actually `Changed()` are forwarded. Reject with `no fields to update` when none are. | | `delete` | `-y`, `--yes` | DELETE. Aliases: `remove`, `rm`. | `update`/`delete` take the **milestone id** (not the project id) because milestones are keyed independently once created. ## Common errors * **`--name is required`** — `create` was called without a name. * **`no fields to update — pass at least one of --name/--status/--priority/--health/--lead-id/--lead-type/--start-date/--target-date/--icon/--color/--description`** — `update` needs at least one field. * **`workspace_id required`** — no active workspace; run `crewship workspace use ` first. ## See also * [`crewship mission`](/cli/mission) — missions roll up into projects. * [`crewship issue`](/cli/issue) — issues live inside projects (or float unlinked). * [`crewship label`](/cli/label) — the labels referenced in the breakdown. * [Issues API](/api-reference/issues) — covers project endpoints (`GET /api/v1/projects`).