Linear Native Node

Direct Linear workspace helper using Linear's GraphQL API from native Node.js. Use when creating, listing, updating, commenting on, summarizing, or looking up Linear issues, projects, teams, workflow states, priorities, standup notes, or branch names. Can write to Linear via create/comment/status/priority/project-create commands. Reads LINEAR_API_KEY from the process environment only; no OAuth gateway, bash, Python, npm dependencies, or third-party service.

Use scripts/linear.mjs to talk directly to Linear's GraphQL API at https://api.linear.app/graphql.

Native Node 18+. Zero npm dependencies. Windows, macOS, and Linux friendly. No bash, Python, OAuth gateway, browser login, or third-party proxy.

Security behavior

• Reads LINEAR_API_KEY and optional LINEAR_DEFAULT_TEAM from the process environment only.
• Does not read credential files or ~/.openclaw/.env.
• Sends GraphQL requests only to https://api.linear.app/graphql.
• Does not write files, log secrets, or print the API key.
• Write commands are explicit commands (create, comment, status, priority, project-create) and are fail-closed by default: the script exits unless --execute is present after explicit user approval. Read-only commands are the default usage pattern.

Why this skill

This is the private/direct version of common Linear helper workflows:

• Keeps API access between this machine and Linear only.
• Uses LINEAR_API_KEY from the process environment only; never print the key.
• Avoids bash-oriented helpers that break on Windows.
• Avoids third-party OAuth/gateway tools; there is no Maton-style intermediary.
• Keeps a tight auditable scope: viewer/org/team lookup, issue list/read/create/update/comment, practical personal summaries, and branch names.

Setup

Create a Linear API key at:

https://linear.app/settings/api

PowerShell session-only setup:

$env:LINEAR_API_KEY = "<your-linear-key>"
$env:LINEAR_DEFAULT_TEAM = "TEAM"

macOS/Linux shell session-only setup:

export LINEAR_API_KEY="<your-linear-key>"
export LINEAR_DEFAULT_TEAM="TEAM"

LINEAR_DEFAULT_TEAM is optional. Examples below use TEAM and TEAM-123 as placeholders; replace them with your Linear team key and issue identifiers.

Run

From PowerShell, bash, zsh, or any shell with Node on PATH:

node "<skill-dir>/scripts/linear.mjs" help
node "<skill-dir>/scripts/linear.mjs" viewer
node "<skill-dir>/scripts/linear.mjs" issues --team TEAM --mine --limit 10

From OpenClaw, use the bundled script directly:

Run: node <skill-dir>/scripts/linear.mjs my-issues --team TEAM
Run only after explicit approval: node <skill-dir>/scripts/linear.mjs create TEAM "Fix login error" "Users see an error after submitting credentials." --priority high --execute

Add --json to commands when structured output is useful.

Commands

Read-only:

help
viewer
organization
teams
projects [--team TEAM] [--limit N]
states <TEAM_KEY>
issues [--team TEAM] [--mine] [--state STATE] [--limit N]
my-issues [--team TEAM] [--state STATE] [--limit N]
my-todos [--team TEAM] [--limit N]
urgent [--team TEAM] [--mine] [--limit N]
standup [--team TEAM] [--limit N]
issue <IDENTIFIER>
branch <IDENTIFIER>

Writes to Linear require explicit approval and --execute:

project-create [TEAM_KEY] "Name" ["Description"] --execute
create [TEAM_KEY] "Title" ["Description"] [--priority urgent|high|medium|low|none] --execute
comment <IDENTIFIER> "Comment" --execute
status <IDENTIFIER> <state-name> --execute
priority <IDENTIFIER> <urgent|high|medium|low|none> --execute

For agent use, perform write commands only when the user clearly requested the Linear change or explicitly approved it. Without --execute, write commands fail before contacting Linear.

Examples

List teams, projects, and states:

node "<skill-dir>/scripts/linear.mjs" teams
node "<skill-dir>/scripts/linear.mjs" projects --team TEAM --limit 20
node "<skill-dir>/scripts/linear.mjs" states TEAM

Create a project:

node "<skill-dir>/scripts/linear.mjs" project-create TEAM "Release Planning" "Track launch scope and milestones." --execute

List issues:

node "<skill-dir>/scripts/linear.mjs" issues --team TEAM --limit 20
node "<skill-dir>/scripts/linear.mjs" issues --team TEAM --mine --state "In Progress"
node "<skill-dir>/scripts/linear.mjs" my-issues --team TEAM
node "<skill-dir>/scripts/linear.mjs" my-todos --team TEAM
node "<skill-dir>/scripts/linear.mjs" urgent --team TEAM

Read and update an issue:

node "<skill-dir>/scripts/linear.mjs" issue TEAM-123
node "<skill-dir>/scripts/linear.mjs" comment TEAM-123 "Added reproduction notes." --execute
node "<skill-dir>/scripts/linear.mjs" status TEAM-123 "In Progress" --execute
node "<skill-dir>/scripts/linear.mjs" priority TEAM-123 urgent --execute

Create an issue:

node "<skill-dir>/scripts/linear.mjs" create TEAM "Fix notification delivery" "Notifications are delayed for some users." --priority high --execute

Generate a GitHub-friendly branch name from the Linear issue title:

node "<skill-dir>/scripts/linear.mjs" branch TEAM-123

Get machine-readable output:

node "<skill-dir>/scripts/linear.mjs" my-issues --team TEAM --json

Notes

• Prefer issue identifiers like TEAM-123; the script resolves them before updates that need Linear IDs.
• Priority values map to Linear's native values: urgent, high, medium, low, none.
• Missing keys, 401/403 responses, GraphQL errors, missing teams/states, and invalid priorities produce clear stderr errors with non-zero exit codes.
• standup summarizes assigned active and recently completed issues; it is intentionally lightweight, not a time tracker.

Changelog

• 1.0.6: Package-only cleanup: publish runtime files only (SKILL.md and scripts/linear.mjs) and keep the local test harness out of the public archive.
• 1.0.5: Fix GraphQL variable construction in issue list queries (issues, my-issues, my-todos, urgent, standup) so only actually used variables are declared and passed.