linear

Linear CLI

Offline-capable, agent-native Linear CLI with SQLite-backed sync, FTS5 search, cross-cycle comparison, project burndown projection, and a pp_created fixture-lifecycle contract that lets agents mutate real workspaces safely.

Pulls your workspace into a local SQLite store with FTS5 search and runs compound queries that no live API call can answer in one round-trip — today view, bottleneck detection, project burndown, cycle comparison. Ships a thin linear_search + linear_execute MCP orchestration pair (with named multi-step intents for triage, standup, sprint plan, weekly update, and grooming) so agents reach the full surface in ~1K tokens instead of enumerating 60+ endpoint mirrors.

Created by @mvanhorn (Matt Van Horn).

Contributors: @ericlitman (Eric Litman), @tmchow (Trevin Chow), @rob-coco (Rob Coco).

Install

The recommended path installs both the linear-pp-cli binary and the pp-linear agent skill (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other agents supported by the upstream skills CLI) in one shot:

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

For CLI only (no skill):

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

For skill only — installs the skill into the same agents as the default command above, but skips the CLI binary (use this to update or reinstall just the skill):

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

To constrain the skill install to one or more specific agents (repeatable — agent names match the skills CLI):

npx -y @mvanhorn/printing-press-library install linear --agent claude-code
npx -y @mvanhorn/printing-press-library install linear --agent claude-code --agent codex

Without Node (Go fallback)

If npx isn't available (no Node, offline), install the CLI directly via Go (requires Go 1.26.6 or newer):

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

This installs the CLI only — no skill.

Pre-built binary

Download a pre-built binary for your platform from the latest release. On macOS, clear the Gatekeeper quarantine: xattr -d com.apple.quarantine <binary>. On Unix, mark it executable: chmod +x <binary>.

Install for Hermes

Install the CLI binary first. The installer writes binaries to a per-user managed bin directory by default: $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows.

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

Then install the focused Hermes skill.

From the Hermes CLI:

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-linear --force

Inside a Hermes chat session:

/skills install mvanhorn/printing-press-library/cli-skills/pp-linear --force

Restart the Hermes session or gateway if the newly installed skill is not visible immediately.

Install for OpenClaw

Install both the CLI binary and the focused OpenClaw skill. The installer defaults binaries to a per-user bin directory ($HOME/.local/bin on macOS/Linux, %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows):

npx -y @mvanhorn/printing-press-library install linear --agent openclaw

Restart the OpenClaw session or gateway if the newly installed skill is not visible immediately.

Use with Claude Desktop

This CLI ships an MCPB bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).

To install:

1. Download the .mcpb for your platform from the latest release.
2. Double-click the .mcpb file. Claude Desktop opens and walks you through the install.
3. Fill in LINEAR_API_KEY when Claude Desktop prompts you.

Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (darwin-arm64) and Windows (amd64, arm64); for other platforms, use the manual config below.

Manual JSON config (advanced)

If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.

Install the MCP binary from this CLI's published public-library entry or pre-built release.

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "linear": {
      "command": "linear-pp-mcp",
      "env": {
        "LINEAR_API_KEY": "<your-key>"
      }
    }
  }
}

Authentication

Linear personal API keys go in the Authorization header verbatim — no Bearer prefix. Run linear-pp-cli auth set-token lin_api_yourkeyhere to save your key (no Bearer prefix needed for Linear personal API keys), or export LINEAR_API_KEY=lin_api_.... Personal API keys are workspace-scoped; the doctor command validates auth, API connectivity, and store health in one shot.

Quick Start

# Save your Linear personal API key (or export LINEAR_API_KEY)
linear-pp-cli auth set-token <your-key>

# Burn your workspace into the local SQLite store for offline + transcendent queries
linear-pp-cli sync --full

# Your ranked work queue for today across every team
linear-pp-cli today --json

# Pre-sprint-planning overload + blocked-count signal for one team
linear-pp-cli bottleneck --team ENG

# Project landing date from regressed velocity, not the static target someone typed in
linear-pp-cli projects burndown PROJ_ID --weeks 8

# Archive only the test issues this CLI created in this session
linear-pp-cli pp-cleanup

Unique Features

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 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. 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, before creating or editing issues.

  Reach for this before passing label UUIDs to issues create or issues edit; Linear rejects labels owned by another team, and the CLI now preflights label 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

• 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 comments add --issue ENG-123 --body-file /tmp/comment.md --media /tmp/screenshot.png --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

  documents create requires exactly one parent (--issue, --project, --team, --initiative, --cycle, --release, or --folder); --team accepts a key such as ENG or a UUID.

• Current issue reads and comments — Read full issue bodies and discussion from live Linear when freshness matters.

  linear-pp-cli issues ENG-123 --agent --data-source live --select identifier,title,description,state.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 --issue ENG-123 --agent

  Comma-separated issue reads preserve caller order, de-duplicate identifiers, and fail the whole request when any member cannot be read. A single identifier keeps the existing object-shaped results; multiple identifiers return an array.

  Canonical forms remain issues <ID>, documents <ref>, and comments add. For compatibility with common agent phrasing, the CLI also accepts issues get|view|show <ID>, documents get|view <ref>, and comments create with the same flags and behavior. documents show is intentionally unsupported.

Usage

Run linear-pp-cli --help for the full command reference and flag list.

Commands

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

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

Output Formats

# Human-readable table (default in terminal, JSON when piped)
linear-pp-cli attachments mock-value

# JSON for scripting and agents
linear-pp-cli attachments mock-value --json

# Filter to specific fields
linear-pp-cli attachments mock-value --json --select id,name,status

# Dry run — show the request without sending
linear-pp-cli attachments mock-value --dry-run

# Agent mode — JSON + compact + no prompts in one flag
linear-pp-cli attachments mock-value --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Explicit retries - add --idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
• Confirmable - --yes for explicit confirmation of destructive actions
• Piped input - write commands can accept structured input when their help lists --stdin
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Agent recipes:

# Full current issue body; compact output strips descriptions unless selected
linear-pp-cli issues ENG-123 --agent --data-source live --select identifier,title,description,state.name,url

# Several current issue bodies in caller order
linear-pp-cli issues ENG-123,ENG-124 --agent --data-source live --select identifier,title,description,state.name,url

# Safe multiline writes; body files preserve shell snippets literally
linear-pp-cli comments add --issue ENG-123 --body-file /tmp/comment.md --agent

Health Check

linear-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/linear-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
LINEAR_API_KEY	per_call	Yes	Set to your API credential.

Freshness and Data Sources

Read commands fall into three categories with different data-source semantics. The persistent flags --data-source auto|live|local and --max-age <duration> control where reads come from and when to warn about stale local data.

Category	Commands	Default	Override
Live-first with local fallback	attachments, projects get, teams, initiatives get, issues, issues list (the v4 refactor)	--data-source auto: live API → write-through → fall back to local on network error	--data-source live (no fallback), --data-source local (no API)
Freshness-coordinated local search	issues search	Local FTS over synced issues. If issue data is stale or empty, the command refreshes teams, workflow states, labels, and issues behind a cross-process lock before searching; if refresh fails, it returns a typed error. Agent/JSON output is a provenance envelope with freshness metadata; refreshed means local issue data changed during the invocation, and refreshed_by identifies whether this process, a peer, or an external sync did it.	--data-source local explicitly allows stale/offline local results; --max-age 0 disables the freshness gate and marks freshness_gate_disabled. Empty local stores are marked with unsynced.
Snapshot-computational	today, bottleneck, blocking, similar, velocity, slipped, cycles compare, projects burndown, initiatives health, milestones at-risk	Local store only — no live equivalent exists. Must sync first.	None (flag ignored)
Label discovery	labels list --team ENG	--data-source auto: reads live by default; --data-source local reads the synced issue_labels table	--data-source live, --data-source local
Live collaboration reads	comments list, documents, documents list	Always live; comments and working-session docs are collaboration surfaces where stale local state is misleading	n/a
Mutations	issues create, issues edit, comments add, comments edit, documents create, documents edit, pp-cleanup	Always live; on success, the HTTP cache is invalidated AND issue mutations are written back to the local store	n/a

Promoted Linear GraphQL read commands such as teams and projects get use POST /graphql internally. They should not be reimplemented with shell-level GET calls; Linear rejects GET /graphql with CSRF/preflight errors.

--max-age (default 30 minutes):

When a store-backed read returns data older than --max-age, a stderr hint suggests running sync. Set --max-age 6h for archival workflows or --max-age 0 to disable the warning entirely. JSON output stays clean — the hint is stderr-only.

Cold-start hint: Running today, issues list, bottleneck, etc. before any sync prints (no issues in local store — run 'linear-pp-cli sync' to populate) to stderr.

Budget-conscious agent pattern (Linear meters ~1500 complexity points/hour on personal keys):

# Hydrate once at session start
linear-pp-cli sync

# Read freely from local — zero API budget
linear-pp-cli today --data-source local
linear-pp-cli bottleneck --team ENG --data-source local
linear-pp-cli issues list --assignee me --data-source local

# Mutate — write-back keeps the store fresh, no re-sync needed
linear-pp-cli issues create --title "..." --team ENG --pp-session "$SESSION"

# Verify from local
linear-pp-cli issues list --data-source local --pp-session "$SESSION"

# Refresh every ~30 minutes for long sessions
linear-pp-cli sync

Troubleshooting

Authentication errors (exit code 4)

• Run linear-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $LINEAR_API_KEY Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• Authentication failed / 401 from Linear — Run linear-pp-cli doctor — it checks key validity, header shape (no Bearer prefix), and rate-limit headroom in one shot.
• Rate limit error / complexity budget exceeded — Lower concurrency on sync and prefer offline reads — Linear meters by complexity points (~1500/hr for personal API keys), mutations cost more than queries.
• sync --full is slow or paginates indefinitely — Run linear-pp-cli sync after the first full sync — it cursors on updatedAt and only fetches changed rows.
• FTS5 search returns no rows for a term you know exists — Run linear-pp-cli sync to refresh the FTS index, or linear-pp-cli doctor to confirm the FTS triggers fired on the latest sync.
• Agent accidentally mutated an issue it did not create — Set LINEAR_PP_CLI_TRUST_MODE=strict in the environment — strict mode refuses any mutation on an issue ID not in the local pp_created ledger.

---

Sources & Inspiration

This CLI was built by studying these projects and resources:

• Finesssee/linear-cli — Rust
• schpet/linear-cli — Ruby
• czottmann/linearis — TypeScript
• dorkitude/linctl — Go
• evangodon/linear-cli — Go
• linear-mcp — TypeScript

Generated by CLI Printing Press