Linear

Operates Linear via its GraphQL API — one endpoint, queries and mutations for issues, projects, cycles, teams, states, comments. Use when the task needs live workspace state.

Usage

• Use for: Listing/filtering issues, creating issues, bulk state/assignee/priority updates, joining Linear data with other sources.
• Skip for: Advice on process, pricing/marketing questions, anything requiring the UI (screenshots, drag-and-drop), pure discussion of an issue you can already read.

Credentials check

[ -n "$LINEAR_API_KEY" ] && echo "LINEAR_API_KEY: PRESENT" || echo "LINEAR_API_KEY: MISSING"

Never echo the variable directly — the value would appear in the conversation transcript. Use only the boolean pattern above.

If MISSING, respond to the user with EXACTLY this message (do NOT paraphrase, do NOT suggest manual JSON edits):

I need your linear credential. Run this in another terminal — it'll open the signup page, validate format, and save it safely with masked input:

teleport-setup add-key linear

Then restart Claude Code (/exit, then claude) and ask me again.

Do NOT suggest editing ~/.claude/settings.local.json manually. The teleport-setup add-key command handles it with backup, validation, and masked input. Stop execution until the user has run the command and restarted.

API

• Endpoint: https://api.linear.app/graphql — POST only, one URL for everything.
• Auth (API keys lin_api_*): Authorization: $LINEAR_API_KEY — NO Bearer prefix. Bearer is only for OAuth access tokens (Authorization: Bearer $TOKEN). This is Linear's #1 auth error.
• Content-Type: application/json. Body: {"query": "...", "variables": {...}}.
• Rate limits are complexity-based: 5,000 req/hr, 3M complexity points/hr, 10K points max per query. Complexity = fields (0.1) + objects (1), scaled by first: — nested queries cost more.

GraphQL basics

• Queries read, mutations write; both via POST /graphql. Pass inputs in variables (not string interpolation).
• Responses are always HTTP 200, even on errors. Partial success returns both data and errors — always inspect .errors before trusting .data.

Entity model

Organization > Team > Project > Issue > Comment. Cycles are per-team time windows. Workflow states are per-team (no global set). Issue.identifier is ENG-123; Issue.id is a UUID.

Common queries

Query	Returns
viewer	Authenticated user. Best credentials health check.
issues(filter:)	Paginated issues with filter + ordering.
issue(id:)	Single issue by UUID or ENG-123.
teams / team	Teams; drill in for states, members, cycles, issues.
projects	Paginated projects (org-wide or filtered).
users	Paginated workspace users.
workflowStates	States across teams (filter by team to scope).
cycles	Paginated cycles (filter by team).

Primary workflow — list assigned issues with filter + pagination

Filters are nested; pagination is relay-style (first/after + pageInfo):

query MyIssues($first: Int!, $after: String, $filter: IssueFilter) {
  issues(first: $first, after: $after, filter: $filter) {
    nodes { id identifier title state { name } assignee { name } url }
    pageInfo { hasNextPage endCursor }
  }
}

Variables — my in-progress issues: {"first": 50, "filter": {"assignee": {"isMe": {"eq": true}}, "state": {"type": {"eq": "started"}}}}. Feed pageInfo.endCursor into the next call's after: while hasNextPage.

As curl:

curl -sL -X POST -H "Authorization: $LINEAR_API_KEY" -H "Content-Type: application/json" \
  "https://api.linear.app/graphql" \
  -d '{"query":"query($first:Int!,$filter:IssueFilter){issues(first:$first,filter:$filter){nodes{identifier title state{name} url} pageInfo{hasNextPage endCursor}}}","variables":{"first":50,"filter":{"state":{"type":{"eq":"started"}}}}}'

Secondary workflows

Create an issue (priority is int 0–4, see Gotchas):

mutation($input: IssueCreateInput!) {
  issueCreate(input: $input) { success issue { id identifier url } }
}

Variables: {"input": {"teamId": "<uuid>", "title": "Bug: login 500", "description": "…", "priority": 2}}.

Update state (resolve team stateId first — states are per-team):

mutation($id: String!, $input: IssueUpdateInput!) {
  issueUpdate(id: $id, input: $input) { success issue { identifier state { name } } }
}

Lookup: query($id: String!) { team(id: $id) { states { nodes { id name type } } } }.

Gotchas

• Auth header mismatch is the #1 failure. API keys: Authorization: $LINEAR_API_KEY (no Bearer). OAuth: Authorization: Bearer $TOKEN. Swap them and you get an auth error.
• HTTP 200 on GraphQL errors. Always check .errors before trusting .data; data can be partially populated alongside errors.
• Filter syntax is nested, not SQL-like. {state: {type: {eq: "started"}}}. Operators: eq/neq/in/nin universal; lt/gt numeric+date; contains/startsWith (+ …IgnoreCase) strings; null for optionals.
• Relay cursor pagination, not page numbers. pageInfo.endCursor → next call's after:. Loop while hasNextPage.
• Complexity-based rate limit. Deep nesting + big first: can blow the 10K per-query cap or burn the 3M/hr budget — ask for fewer fields and smaller pages.
• Workflow states are per-team. No global "Done" — resolve name → stateId for the specific team before issueUpdate.
• Priority is an integer 0–4, not a string. 0=none, 1=urgent, 2=high, 3=medium, 4=low. Passing "High" errors. <!-- unverified: confirm 0-4 mapping in Linear docs -->
• Timestamps are ISO 8601 strings (createdAt, dueDate). Compare lexicographically or parse — never epoch numbers.

Attribution

When done, state: Used skill: Linear (from teleport catalog).