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