diff --git a/CHANGELOG.md b/CHANGELOG.md index 72e60cf8..33c7c727 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ - `issue update --clear-due-date`, `--clear-estimate`, `--clear-parent`, `--clear-project`, and `--clear-milestone`, plus `project update --clear-lead`, `--clear-start-date`, and `--clear-target-date`, to remove a value the way `--unassign` and `--clear-cycle` already do. Each sends an explicit `null` to Linear and errors when combined with its set flag; `--clear-project` also rejects `--milestone`, since a milestone belongs to the project being removed. Previously these fields could only be changed, never cleared: cliffy treats `--due-date ""` as a missing value - `project update` now changes teams, labels, and initiatives with the same three operations `issue update` has for labels: `--team`, `--label`, and `--initiative` replace the whole set, `--add-team`/`--add-label`/`--add-initiative` append, and `--remove-team`/`--remove-label`/`--remove-initiative` detach, all repeatable, with a replace flag rejected alongside its add/remove flags. Linear's project input only accepts a full `teamIds`/`labelIds` list, so add and remove read the project's current set (every page of it) and send the computed set; initiatives have no input field at all and go through the initiative-to-project link mutations, so `project update` previously could not change them after `project create --initiative`. Removing a team, label, or initiative the project does not have errors and lists what it does have, and a link change that fails part-way reports what was applied and what is still pending - `--json` (`-j`) on `team list`, `cycle list`, `cycle view`, `milestone list`, `milestone view`, and `project view`, the last read commands without machine-readable output. List commands emit the same `{ nodes, pageInfo }` connection shape as the other list commands, after the same filtering and ordering as the table; view commands emit the GraphQL object as fetched, including every issue rather than the ten-item preview, and `milestone view --all --json` includes every page. (A 2.0.0 entry claimed `cycle list --json`; that change never actually landed.) ([#276](https://github.com/schpet/linear-cli/issues/276); thanks @lakardion) +- `template list` and `template view`, and `--template ` on `issue create` and `project create`, mirroring what Linear's MCP server exposes. `template list` shows every issue, project, and document template in the workspace, filtered with `--type` and `--team` (a team's own templates plus workspace-level ones); `template view` prints a template's metadata and every value it pre-fills, with the rich-text body rendered as markdown, and `--json` on both returns the raw GraphQL objects with `templateData` still JSON-encoded. `--template` sends the template's ID so Linear applies it server-side: explicit flags override the template's values, `--label` merges with its labels, `--description` replaces its body (omit it to keep the body), and `issue create --template` makes `--title` optional. Linear rejects `useDefaultTemplate` next to `templateId`, so `--template` takes the place of the team's default template and `--no-use-default-template` is implied. Names resolve exactly and case-insensitively within the target type and team; a name shared by several eligible templates errors with their IDs. Document templates can be listed and viewed only: `DocumentCreateInput` has no `templateId` ### Fixed diff --git a/README.md b/README.md index e9c4e328..4578f01e 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,7 @@ linear issue start # create/switch to issue branch and mark as started linear issue create # create a new issue (interactive prompts) linear issue create -t "title" -d "description" # create with flags linear issue create --project "My Project" --milestone "Phase 1" # create with milestone +linear issue create --template "Bug report" -t "Login fails" # create from a template (see template commands) linear issue update # update an issue (interactive prompts) linear issue update ENG-123 --milestone "Phase 2" # set milestone on existing issue linear issue update ENG-123 --clear-due-date --clear-parent # remove values (also --clear-estimate, --clear-project, --clear-milestone, --clear-cycle, --unassign) @@ -202,6 +203,7 @@ linear project view # view project details linear project view --json # project details as JSON linear project create --name "API v2" --team ENG --content-file overview.md linear project create --name "Mobile launch" --team APP --priority high --label Launch --member jane@example.com +linear project create --name "Q3 launch" --team APP --template "Kickoff" # create from a project template linear project update --content-file overview.md # replace the project's overview body linear project update --clear-lead --clear-target-date # remove values (also --clear-start-date) linear project update --add-team OPS --remove-label Launch --add-initiative "Q4 Bets" # change teams, labels, initiatives incrementally @@ -300,6 +302,23 @@ linear document delete --bulk # bulk delete content updates are refused by default when a document has active inline Linear comments, because replacing markdown can detach or hide those anchors. top-level document comments do not block updates. review the inline comment first, then rerun with `--force` if you intentionally want to replace the content anyway. +### template commands + +```bash +linear template list # every issue, project, and document template in the workspace +linear template list --type issue --team ENG # ENG's issue templates plus workspace-level ones +linear template list --json # the raw template objects (templateData is a JSON-encoded string) +linear template view "Bug report" # what the template pre-fills: title, priority, labels, body, sub-issues, ... +linear template view --json # raw GraphQL object; `jq '.templateData | fromjson'` decodes the data + +# apply a template on create (name or ID). Linear fills the template in server-side. +linear issue create --team ENG --template "Bug report" # the template supplies the title +linear issue create --team ENG --template "Bug report" -t "Login fails" -l security # flags override, labels merge +linear project create --name "Q3 launch" --team APP --template "Kickoff" +``` + +`--template` takes the place of the team's default template, so it never needs `--no-use-default-template` (passing both is fine). Anything you pass explicitly overrides the template's value; `--label` merges with the template's labels; `--description` replaces the template body, so leave it out to keep the body. Document templates can be listed and viewed, but Linear's API has no way to apply one when creating a document. + ### other commands ```bash diff --git a/docs/usage.md b/docs/usage.md index 1356845c..38255d05 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -150,6 +150,21 @@ linear issue create --team TEAM linear issue create --start ``` +create from a template (name or ID, applied by Linear server-side): + +```bash +# The template supplies the title, body, and fields; --title is optional +linear issue create --team ENG --template "Bug report" + +# Flags you pass override the template's values; labels merge with the template's +linear issue create --team ENG --template "Bug report" --title "Login fails" --label security + +# --description replaces the template body; leave it out to keep the body +linear issue create --team ENG --template "Bug report" --description "Just this text" +``` + +`--template` takes the place of the team's default template (`--no-use-default-template` is implied; passing it too is fine). See [templates](#templates) for listing and inspecting them. + #### update an issue update the current issue: @@ -304,6 +319,9 @@ linear project create --name "API v2" --team ENG --content-file overview.md # Create with priority, labels, members, icon, and color linear project create --name "Mobile launch" --team APP --priority high --label Launch --member jane@example.com --icon rocket --color "#5E6AD2" + +# Create from a project template (name or ID); explicit flags override the template's values +linear project create --name "Q3 launch" --team APP --template "Kickoff" ``` #### update a project @@ -366,6 +384,40 @@ linear initiative comment list "Platform" linear initiative comment add "Platform" --body "Scope locked for Q3" ``` +### templates + +Linear templates pre-fill an issue, project, or document. A template belongs to a team or to the whole workspace; team templates are only available in that team, workspace templates everywhere. + +#### list templates + +```bash +linear template list # every template in the workspace +linear template list --type issue # issue, project, or document +linear template list --team ENG # ENG's templates plus workspace-level ones +linear template list --type project --json # raw template objects, after the same filtering and ordering as the table +``` + +#### view a template + +```bash +linear template view "Bug report" # by name (exact, case-insensitive) +linear template view # by ID; needed when the same name exists in several teams +linear template view "Bug report" --json # raw GraphQL object +linear template view "Bug report" --json | jq '.templateData | fromjson' # decode the pre-filled data +``` + +The human view prints the template's metadata and then every key of its pre-filled data: title, priority, estimate, labels, state, sub-issues, and the body (Linear stores the body as rich text; it is shown as markdown). References come back as IDs, which `linear team states`, `linear label list`, and `linear user list` can map to names. + +#### apply a template + +Pass `--template ` to `issue create` or `project create`. Linear applies the template server-side on create; the CLI only sends the template's ID. + +- Anything you pass explicitly (title, priority, state, description, and so on) overrides the template's value. +- `--label` merges with the template's labels rather than replacing them. +- `--description` replaces the template body. Leave it out to keep the body. +- `issue create --template` makes `--title` optional and takes the place of the team's default template (`--no-use-default-template` is implied and may be passed as well). +- Document templates can be listed and viewed, but Linear's API offers no way to apply one when creating a document, so `document create` has no `--template` flag. + ### shell completions generate shell completions for better command-line experience: diff --git a/skills/linear-cli/SKILL.md b/skills/linear-cli/SKILL.md index a85f0aa4..365cf62e 100644 --- a/skills/linear-cli/SKILL.md +++ b/skills/linear-cli/SKILL.md @@ -67,6 +67,17 @@ linear issue update ENG-123 --remove-label sprint-42 --add-label sprint-43 # at linear issue update ENG-123 --label infra --label security # replaces the label set ``` +### Create an issue or project from a template + +```bash +linear template list --type issue --team ENG # find the template a team expects +linear template view "Bug report" # see what it pre-fills (title, fields, body, sub-issues) +linear issue create --team ENG --template "Bug report" --title "Login fails on Safari" +linear project create --name "Q3 launch" --team ENG --template "Kickoff" +``` + +Explicit flags override the template's values, `--label` merges with its labels, and `--description` replaces its body (omit it to keep the body). Document templates cannot be applied through the API. + ### Add a comment ```bash @@ -277,6 +288,10 @@ linear team list linear team members linear team states +linear template +linear template list +linear template view + linear user linear user list ``` @@ -298,6 +313,7 @@ linear user list - [project-update](references/project-update.md) - Manage project status updates - [schema](references/schema.md) - Print the GraphQL schema to stdout - [team](references/team.md) - Manage Linear teams +- [template](references/template.md) - Browse Linear issue, project, and document templates. Apply one with `issue create --template` or `project create --template`. - [user](references/user.md) - Manage Linear users For curated examples of organization features (initiatives, labels, projects, bulk operations), see [organization-features](references/organization-features.md). diff --git a/skills/linear-cli/SKILL.template.md b/skills/linear-cli/SKILL.template.md index e5986fe1..abc65972 100644 --- a/skills/linear-cli/SKILL.template.md +++ b/skills/linear-cli/SKILL.template.md @@ -67,6 +67,17 @@ linear issue update ENG-123 --remove-label sprint-42 --add-label sprint-43 # at linear issue update ENG-123 --label infra --label security # replaces the label set ``` +### Create an issue or project from a template + +```bash +linear template list --type issue --team ENG # find the template a team expects +linear template view "Bug report" # see what it pre-fills (title, fields, body, sub-issues) +linear issue create --team ENG --template "Bug report" --title "Login fails on Safari" +linear project create --name "Q3 launch" --team ENG --template "Kickoff" +``` + +Explicit flags override the template's values, `--label` merges with its labels, and `--description` replaces its body (omit it to keep the body). Document templates cannot be applied through the API. + ### Add a comment ```bash diff --git a/skills/linear-cli/references/commands.md b/skills/linear-cli/references/commands.md index 27f34e56..2d392eb8 100644 --- a/skills/linear-cli/references/commands.md +++ b/skills/linear-cli/references/commands.md @@ -17,6 +17,7 @@ - [project-update](./project-update.md) - Manage project status updates - [schema](./schema.md) - Print the GraphQL schema to stdout - [team](./team.md) - Manage Linear teams +- [template](./template.md) - Browse Linear issue, project, and document templates. Apply one with `issue create --template` or `project create --template`. - [user](./user.md) - Manage Linear users ## Quick Reference diff --git a/skills/linear-cli/references/issue.md b/skills/linear-cli/references/issue.md index d3453c92..6c1413a5 100644 --- a/skills/linear-cli/references/issue.md +++ b/skills/linear-cli/references/issue.md @@ -278,6 +278,11 @@ Options: --cycle - Cycle name, number, 'active'/'now', 'next', 'previous', or a relative offset like +1 (use --cycle=-1 for negatives) --no-use-default-template - Do not use default template for the issue + --template