Pp Linear

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/project-management/linear/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

Linear — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the linear-pp-cli binary. Do not invoke a command named linear when this skill is active. If linear-pp-cli is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install linear --cli-only

2. Verify: linear-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):

go install github.com/mvanhorn/printing-press-library/library/project-management/linear/cmd/linear-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

Agent Contract

• Add --agent to commands unless a human-readable table is explicitly needed. It implies JSON, compact output, non-interactive mode, no color, and confirmation-safe scripting.
• Use --data-source live for closeout/state/description checks where current truth matters. Use issues search for duplicate checks; it refreshes stale issue search data or fails visibly. Use --data-source local or similar only when stale/offline local duplicate search is intentional.
• Fields omitted from compact output are not absent from the issue. Request them explicitly, including nested labels: linear-pp-cli issues ENG-123 --agent --data-source live --select identifier,title,description,state.name,labels.nodes.id,labels.nodes.name,url.
• Fetch several known issues in one call with comma-separated identifiers: linear-pp-cli issues ENG-123,ENG-124 --agent. The result array preserves caller order and removes duplicate identifiers; a missing member fails the whole read instead of returning a partial set.
• Prefer the canonical read and comment forms shown here. Common agent phrasing is accepted without changing behavior: issues get|view|show ENG-123, documents get|view <ref>, and comments create are compatibility aliases for issues ENG-123, documents <ref>, and comments add. The aliases accept the same global flags, comma reads, body files, targets, and media flags as their canonical commands; there is deliberately no documents show alias.
• --label is UUID-only; --label-name resolves an exact label name at write time (team-owned or workspace-global). Before passing UUIDs to issues create or issues edit, run linear-pp-cli labels list --team ENG --agent --select id,name,global,team.key. The CLI preflights ownership and refuses cross-team labels before mutating.
• Never pass multiline Markdown, shell snippets, GraphQL, logs, backticks, $() expansions, or media-rich content as inline shell arguments. Write the body to a file or stdin and use the *-file / *-stdin flags below.

When to Use This CLI

Reach for this CLI when you need joined queries that span issues, cycles, projects, and milestones — questions Linear's UI answers across multiple tabs and the API answers across multiple round-trips. It's the right pick for agents driving Linear over MCP (the orchestration pair plus named intents covers the full surface in ~1K tokens), for engineering managers preparing Friday updates (cycle comparison, slipped, burndown, blocking queue), and for any agent that must mutate a real workspace under the pp_created fixture-lifecycle contract.

Unique Capabilities

These capabilities aren't available in any other tool for this API.

Local state that compounds

• today — See all of your assigned issues across every team for today, ranked by priority and cycle deadline.

  Reach for this when an agent or human needs a single ranked work queue across every team, without naming the underlying joins.

  linear-pp-cli today --json --agent

• bottleneck — See which team members are overloaded and which issues are blocked before sprint planning.

  Reach for this in sprint planning when you need to see who is overloaded and where work is stuck in one view.

  linear-pp-cli bottleneck --team ENG --json

• stale — Find issues that haven't been touched in N days, grouped by team and project.

  Reach for this during backlog grooming when you need to surface forgotten issues without exhausting the API rate limit.

  linear-pp-cli stale --days 30 --team ENG --json

• issues search / similar — Find issues that look like duplicates of a query string using local FTS5 search.

  Reach for this during triage when you suspect an incoming bug duplicates an existing issue.

  linear-pp-cli issues search "login redirect bug" --limit 5 --agent
  linear-pp-cli issues search "pipeline follow-up" --team SYMPH --limit 10 --agent
  linear-pp-cli similar "login redirect bug" --limit 5 --json
  linear-pp-cli similar "pipeline follow-up" --team SYMPH --limit 10 --agent

  Prefer issues search when checking for existing tickets before creating or updating follow-up work; it is the supported issue-search spelling agents tend to reach for. It coordinates freshness for duplicate checks: fresh local data is searched immediately, stale or empty issue data refreshes behind a cross-process lock before search, and refresh failures return a typed error instead of silently serving stale results. Add --team <key-name-or-uuid> when a common project name or label appears across teams and the duplicate check must stay inside the target team's queue. Multi-word issues search queries may be quoted or passed as separate words; both forms are joined into one FTS query. Under --agent / --json, issues search returns a provenance envelope with freshness metadata; similar keeps the legacy raw result array. Use --data-source local only when stale/offline local results are intentional.

Cross-entity rollups

• projects burndown — Project a project's landing date by linear-regressing remaining estimate against the team's measured velocity.

  Reach for this when stakeholders ask when a project will land and the project page only shows a static target date someone typed in months ago.

  linear-pp-cli projects burndown PROJ_ID --weeks 8 --json

• cycles compare — Side-by-side metrics between any two cycles: completion %, scope added, scope cut, carryover, average cycle time.

  Reach for this for cycle retros and Friday updates when you need a numeric diff rather than two browser tabs.

  linear-pp-cli cycles compare 42 43 --json

• slipped — Show what carried over from last cycle into this cycle, grouped by team and reason heuristic.

  Reach for this in Friday stakeholder updates when you need a structured slipped-from-last-cycle list, not just a saved view.

  linear-pp-cli slipped --team ENG --json

• velocity — Track sprint completion rates over the last N cycles to spot productivity trends.

  Reach for this in Monday sprint planning to ground rebalance decisions in actual completion data, not the team's last cycle alone.

  linear-pp-cli velocity --weeks 8 --json

• initiatives health — Rolled-up portfolio view per initiative: child project progress, milestone target-vs-projected dates, slippage flags.

  Reach for this in portfolio reviews when stakeholders want the initiative-level rollup, not seven open project tabs.

  linear-pp-cli initiatives health --json

• milestones at-risk — List portfolio milestones whose projected landing date has slipped past their target, ranked by slip magnitude.

  Reach for this in weekly portfolio review when the question is which milestone is most at risk, not which initiative is healthy.

  linear-pp-cli milestones at-risk --json

Personal queues

• blocking — Show issues you are blocking — sorted by downstream impact (downstream count × downstream priority).

  Reach for this every morning when you need to know which of your in-flight issues are stalling teammates downstream.

  linear-pp-cli blocking --json

Agent-native plumbing

• pp-test list — List Linear issues this CLI created in the current or named session, then archive them with pp-cleanup.

  Reach for this when an agent needs to clean up only the tickets it created in a session — the workspace's existing data must not be touched.

  linear-pp-cli pp-test list --json

• issues create --trust-mode strict — Refuse mutations on Linear issues not in the local pp_created ledger when --trust-mode strict is set; works on create and any future mutation surface.

  Reach for this when running an agent against a real workspace with real data — strict mode makes accidental mutation impossible.

  linear-pp-cli issues create --title "Test ticket" --team ENG --trust-mode strict

• Parent and sub-issue linking — Create child issues and set, change, or clear parent links without leaving the CLI for raw GraphQL.

  Reach for this when an agent is creating issue trees, epics, or follow-up hierarchies and needs parentage wired safely.

  linear-pp-cli issues create --title "Child task" --team ENG --parent ENG-123 --description-file /tmp/body.md --agent
  linear-pp-cli issues edit ENG-124 --parent ENG-123 --agent
  linear-pp-cli issues edit ENG-124 --no-parent --agent

• Team-safe issue labels — Discover labels that are valid for the target Linear team, including global labels, then attach them by UUID or exact name.

  Reach for this before attaching labels. --label is UUID-only; use --label-name when the input is a human label name. Linear rejects labels owned by another team, and the CLI preflights ownership before mutating.

  linear-pp-cli labels list --team ENG --agent --select id,name,global,team.key
  linear-pp-cli issues create --title "Title" --team ENG --label <global-or-eng-label-id> --agent
  linear-pp-cli issues create --title "Title" --team ENG --label-name "kind:bug" --label-name "source:user-report" --agent
  linear-pp-cli issues edit ENG-123 --label-name "area:review-tooling" --dry-run --agent
  linear-pp-cli issues edit ENG-123 --label-name "area:review-tooling" --agent

  --label-name always performs a live Linear read to resolve the UUID, even when the surrounding issue write is a dry-run. Writes require a normalized exact label-name match. Team-owned labels and workspace-global labels (no team) both resolve; labels owned by another team do not. --label and --label-name can be combined; resolved IDs are de-duplicated before the mutation. On create, the CLI verifies the mutation's returned label IDs and fails visibly if Linear did not attach the requested set; the exit-5 agent envelope includes created_issue.id, created_issue.identifier, and created_issue.url so the remote issue remains recoverable if local persistence is unavailable.

• Project and initiative name resolution — Resolve portfolio objects by human name before writing issue relationships.

  Reach for this when a user gives an issue identifier plus a project or initiative name. --project is UUID-only; use --project-name when the input is a human project name.

  linear-pp-cli projects list --agent --select id,name,team.key,state,url
  linear-pp-cli projects search "Autonomous Backlog Manager & Dispatch Governance" --team SYMPH --agent --select id,name,team.key,initiative.name,url
  linear-pp-cli initiatives list --agent --select id,name,status,url
  linear-pp-cli initiatives search "Dispatch Governance" --agent --select id,name,status,url
  linear-pp-cli issues edit SYMPH-795 --project-name "Autonomous Backlog Manager & Dispatch Governance" --dry-run --agent
  linear-pp-cli issues edit SYMPH-795 --project-name "Autonomous Backlog Manager & Dispatch Governance" --agent

  --project-name always performs a live Linear read to resolve the UUID, even when the surrounding issue write is a dry-run. Use projects search first when the name is partial; writes require a normalized exact project-name match.

• Shell-safe Linear writes with media — Create and update issue descriptions, comments, and Linear docs without putting Markdown bodies on the shell command line.

  Reach for this whenever a body contains newlines, quotes, backticks, $() expansions, shell commands, images, logs, or agent-generated Markdown.

  linear-pp-cli issues create --title "Title" --team ENG --description-file /tmp/body.md --media /tmp/screenshot.png --agent
  linear-pp-cli issues edit ENG-123 --description-file /tmp/body.md --agent
  linear-pp-cli issues edit ENG-123 --media /tmp/screenshot.png --agent
  linear-pp-cli comments add --issue ENG-123 --body-file /tmp/comment.md --media /tmp/screenshot.png --agent
  linear-pp-cli comments edit <comment-id> --body-file /tmp/comment.md --agent
  linear-pp-cli documents create --title "Runbook" --issue ENG-123 --content-file /tmp/runbook.md --agent
  linear-pp-cli documents create --title "Team runbook" --team ENG --content-file /tmp/runbook.md --agent
  linear-pp-cli documents edit <document-id-or-slug> --content-file /tmp/updated.md --agent

  documents create requires exactly one parent (--issue, --project, --team, --initiative, --cycle, --release, or --folder); --team accepts a key such as ENG or a UUID. issues edit --media, comments edit --media, and documents edit --media with no body/content flag fetch the existing Markdown live and append uploaded media links. Images become Markdown image embeds; non-images become Markdown links. Add --media-public only when the uploaded asset must be reachable outside the Linear workspace.

• Current issue reads and comments — Read full issue bodies and discussion without falling back to stale local state. comments list takes the issue positionally (preferred) or via --issue.

  linear-pp-cli issues ENG-123 --agent --data-source live --select identifier,title,description,state.id,state.name,labels.nodes.id,labels.nodes.name,url
  linear-pp-cli issues ENG-123,ENG-124 --agent --data-source live --select identifier,title,description,state.name,url
  linear-pp-cli comments list ENG-123 --agent
  linear-pp-cli comments list --issue ENG-123 --agent --limit 100

• State transitions — Move an issue between workflow states without raw SQL, GraphQL, or api spelunking. The exact recipe:

  1. List the states for the issue's team: workflow-states list --team <key> (alias: states list).
  2. Pick the target by name or type and copy its id UUID.
  3. Pass that UUID to issues edit --state.

  linear-pp-cli workflow-states list --team ENG --agent --select id,name,type
  linear-pp-cli issues edit ENG-123 --state <state-uuid> --agent

  Or skip the lookup entirely with one-command transitions resolved against the issue's own team:

  linear-pp-cli issues edit ENG-123 --state-name "In Progress" --agent
  linear-pp-cli issues edit ENG-123 --state-type started --agent   # usage error if the team has several 'started' states

  issues create takes the same trio, resolved against --team, so an issue can open directly in the right state. --state requires a UUID (a non-UUID value is a usage error pointing at --state-name):

  linear-pp-cli issues create --title "..." --team ENG --state-name "In Progress" --agent

  Do not use linear-pp-cli api or linear-pp-cli sql for workflow states — api only exposes generated REST-shaped interfaces (currently integrations), not Linear GraphQL objects.

• Linear document reads — documents <ref> accepts every identifier form Linear surfaces: the document UUID, the bare slugId (f7f48ab36080), the full URL slug (my-runbook-f7f48ab36080), or the entire document URL. Copy whichever you have; no slug trimming or parsing shims needed.

  linear-pp-cli documents my-runbook-f7f48ab36080 --agent --select title,updatedAt,content
  linear-pp-cli documents "https://linear.app/<org>/document/my-runbook-f7f48ab36080" --agent

Command Reference

attachments — Manage attachments

• linear-pp-cli attachments <id> — Get a single attachment

audit-entry-types — Manage audit-entry-types

• linear-pp-cli audit-entry-types — Get a single auditentrytype

auth-resolver-responses — Manage auth-resolver-responses

• linear-pp-cli auth-resolver-responses — Get a single authresolverresponse

authentication-session-responses — Manage authentication-session-responses

• linear-pp-cli authentication-session-responses — Get a single authenticationsessionresponse

email-intake-addresses — Manage email-intake-addresses

• linear-pp-cli email-intake-addresses <id> — Get a single emailintakeaddress

favorites — Manage favorites

• linear-pp-cli favorites <id> — Get a single favorite

initiative-relations — Manage initiative-relations

• linear-pp-cli initiative-relations <id> — Get a single initiativerelation

initiative-to-projects — Manage initiative-to-projects

• linear-pp-cli initiative-to-projects <id> — Get a single initiativetoproject

initiatives — Manage initiatives

• linear-pp-cli initiatives <id> — Get a single initiative
• linear-pp-cli initiatives list — List Linear initiatives
• linear-pp-cli initiatives search <query> — Search Linear initiatives by name
• linear-pp-cli initiatives resolve <name> — Resolve one Linear initiative name to its UUID

integrations — Manage integrations

• linear-pp-cli integrations create — Create a integration
• linear-pp-cli integrations delete — Delete a integration

issue-priority-values — Manage issue-priority-values

• linear-pp-cli issue-priority-values — Get a single issuepriorityvalue

labels — List Linear issue labels with team ownership

• linear-pp-cli labels list --team ENG — List global labels plus labels owned by the target team

organizations — Manage organizations

• linear-pp-cli organizations — Get a single organization

project-labels — Manage project-labels

• linear-pp-cli project-labels <id> — Get a single projectlabel

project-milestones — Manage project-milestones

• linear-pp-cli project-milestones <id> — Get a single projectmilestone

project-relations — Manage project-relations

• linear-pp-cli project-relations <id> — Get a single projectrelation

project-statuses — Manage project-statuses

• linear-pp-cli project-statuses <id> — Get a single projectstatus

project-updates — Create and list Linear project updates (status posts on a project)

• linear-pp-cli project-updates list --project <uuid> --agent — List project updates for a project
• linear-pp-cli project-updates list --project-name "My Project" --limit 10 --agent — List updates by project name
• linear-pp-cli project-updates create --project <uuid> --body-file /tmp/update.md --health onTrack --agent — Post a project update with markdown body
• linear-pp-cli project-updates create --project-name "My Project" --body "Sprint on track." --health onTrack --agent — Post update by project name
• linear-pp-cli project-updates create --project <uuid> --body-stdin --health atRisk --agent < /tmp/update.md — Post update from stdin

projects — Manage projects

• linear-pp-cli projects <id> — Get a single project
• linear-pp-cli projects list — List Linear projects
• linear-pp-cli projects search <query> — Search Linear projects by name
• linear-pp-cli projects resolve <name> — Resolve one Linear project name to its UUID

release-notes — Manage release-notes

• linear-pp-cli release-notes <id> — Get a single releasenote

release-pipelines — Manage release-pipelines

• linear-pp-cli release-pipelines — Get a single releasepipeline

release-stages — Manage release-stages

• linear-pp-cli release-stages <id> — Get a single releasestage

releases — Manage releases

• linear-pp-cli releases <id> — Get a single release

roadmap-to-projects — Manage roadmap-to-projects

• linear-pp-cli roadmap-to-projects <id> — Get a single roadmaptoproject

roadmaps — Manage roadmaps

• linear-pp-cli roadmaps <id> — Get a single roadmap

teams — Manage teams

• linear-pp-cli teams — Get a single team

templates — Manage templates

• linear-pp-cli templates — Get a single template

user-settingses — Manage user-settingses

• linear-pp-cli user-settingses — Get a single usersettings

users — Manage users

• linear-pp-cli users — Get a single user

workflow-states — List Linear workflow states (alias: states)

• linear-pp-cli workflow-states list --team ENG --agent --select id,name,type — List a team's states with the UUIDs issues edit --state needs