Skip to content

Add template list, template view, and --template on issue and project create #283

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
schpetbot wants to merge 1 commit into
base: schpet/project-collection-flags
Choose a base branch
from
Open

Add template list, template view, and --template on issue and project create #283

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <name|id>` 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

Expand Down
19 changes: 19 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -202,6 +203,7 @@ linear project view # view project details
linear project view <projectId> --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 <projectId> --content-file overview.md # replace the project's overview body
linear project update <projectId> --clear-lead --clear-target-date # remove values (also --clear-start-date)
linear project update <projectId> --add-team OPS --remove-label Launch --add-initiative "Q4 Bets" # change teams, labels, initiatives incrementally
Expand Down Expand Up @@ -300,6 +302,23 @@ linear document delete --bulk <slug1> <slug2> # 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 <template-id> --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
Expand Down
52 changes: 52 additions & 0 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 <template-id> # 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 <name|id>` 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:
Expand Down
16 changes: 16 additions & 0 deletions skills/linear-cli/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
```
Expand All @@ -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).
Expand Down
11 changes: 11 additions & 0 deletions skills/linear-cli/SKILL.template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions skills/linear-cli/references/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions skills/linear-cli/references/issue.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,6 +278,11 @@ Options:
--cycle <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 <template> - Issue template to apply, by name or ID (the team's templates plus workspace
ones). Takes the place of the team's default template. The template fills in
anything you do not pass: explicit flags override it, --label merges with
the template's labels, and --description replaces the template body (omit it
to keep the body). Makes --title optional.
--no-interactive - Disable interactive prompts
-t, --title <title> - Title of the issue
```
Expand Down
43 changes: 23 additions & 20 deletions skills/linear-cli/references/project.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,26 +109,29 @@ Description:

Options:

-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-n, --name <name> - Project name (required)
-d, --description <description> - Project description (max 255 characters, enforced by Linear's API)
-f, --description-file <path> - Read project description from file (still subject to the 255-character API
limit)
--content <markdown> - Project overview markdown
--content-file <path> - Read project overview markdown from a file
-t, --team <team> - Team key, name, or ID (required, can be repeated for multiple teams)
-l, --lead <lead> - Project lead (username, email, or @me)
-s, --status <status> - Project status (planned, started, paused, completed, canceled, backlog)
--start-date <startDate> - Start date (YYYY-MM-DD)
--target-date <targetDate> - Target completion date (YYYY-MM-DD)
--priority <priority> - Project priority (none, urgent, high, medium, low)
--label <label> - Project label associated with the project. May be repeated.
--member <user> - Project member (username, email, display name, or @me). May be repeated.
--icon <icon> - Project icon
--color <color> - Project color as a HEX string
--initiative <initiative> - Add to initiative immediately (ID, slug, or name)
-i, --interactive - Interactive mode (default if no flags provided)
-h, --help - Show this help.
--workspace <slug> - Target workspace (uses credentials)
-n, --name <name> - Project name (required)
-d, --description <description> - Project description (max 255 characters, enforced by Linear's API)
-f, --description-file <path> - Read project description from file (still subject to the 255-character API
limit)
--content <markdown> - Project overview markdown
--content-file <path> - Read project overview markdown from a file
-t, --team <team> - Team key, name, or ID (required, can be repeated for multiple teams)
-l, --lead <lead> - Project lead (username, email, or @me)
-s, --status <status> - Project status (planned, started, paused, completed, canceled, backlog)
--start-date <startDate> - Start date (YYYY-MM-DD)
--target-date <targetDate> - Target completion date (YYYY-MM-DD)
--priority <priority> - Project priority (none, urgent, high, medium, low)
--label <label> - Project label associated with the project. May be repeated.
--member <user> - Project member (username, email, display name, or @me). May be repeated.
--icon <icon> - Project icon
--color <color> - Project color as a HEX string
--initiative <initiative> - Add to initiative immediately (ID, slug, or name)
--template <template> - Project template to apply, by name or ID (workspace templates plus those of the
project's teams). The template fills in anything you do not pass; explicit
flags override it. Applied on create only.
-i, --interactive - Interactive mode (default if no flags provided)
-j, --json - Output created project as JSON
```

Expand Down
Loading
Loading