@enrichlayer/el-linear weekly downloads statistics

<p align="center"> <img src="public/logo-256.png" alt="el-linear logo" width="160" height="160" /> </p> <h1 align="center">el-linear</h1>

A pragmatic CLI for Linear.app — deterministic team / label / member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch for everything that isn't a first-class command.

Note on naming. This package was briefly published as @enrichlayer/linctl with binary linctl, but reverted to @enrichlayer/el-linear (binary el-linear) because of an npm name collision with dorkitude/linctl. See CHANGELOG.md for the migration recipe.

Install

Published on npm as @enrichlayer/el-linear.

pnpm add -g @enrichlayer/el-linear
# or
npm install -g @enrichlayer/el-linear

Requires Node.js ≥ 22.

Quickstart

# Run the interactive setup wizard. Only the API token is required;
# every other step is skippable and revisitable later.
el-linear init

# Sanity-check
el-linear teams list

# Create your first issue
el-linear issues create "Investigate flaky deploy" \
  --team ENG --assignee alice --project "Reliability" \
  --description "..."

el-linear init walks you through the API token, default team, member aliases, and other defaults. Each step is also a stand-alone sub-command (el-linear init token, el-linear init aliases --import users.csv, etc.) so you can revisit individual sections later. Skip is the default at every prompt — running the wizard twice with no input is a no-op.

If you'd rather skip the wizard entirely, the configuration schema is fully documented in docs/configuration.md so any LLM or script can write ~/.config/el-linear/config.json directly.

Output is JSON by default. Pipe through jq for ad-hoc queries, or use the built-in --jq / --fields / --raw flags.

Why el-linear

The Linear API + SDK are excellent. el-linear adds the layer above them that every team ends up writing themselves:

Concern	What el-linear gives you
Name resolution	Map team keys, member aliases, and label names to UUIDs from one config file. No fuzzy matching, no API roundtrips per call.
Issue hygiene	Required labels, required assignee, required project, type-label-to-verb conventions — all configurable. Warn or hard-fail.
Term enforcement	Catch misspellings of brand and project names in issue titles and descriptions ("EnrichLayer" → "Enrich Layer").
Status defaults	"No project? → Triage. Has assignee+project? → Todo." Per-workspace, configurable.
Auto-link & relate	When you write EMW-258 in a description, el-linear wraps it as a markdown link and creates the corresponding sidebar relation. Prose like "blocked by EMW-258" infers the relation type.
Agent delegation	Use Linear's native delegate field for agent work while keeping the human assignee responsible. issues start moves work to the team's first started status.
GraphQL escape hatch	Anything not covered by built-in commands: el-linear graphql '{ viewer { id } }'. Schema introspection included.
Bundled Claude skill	The published tarball includes a claude-skills/linear-operations/ directory you can symlink into your project's .claude/skills/.

Authentication

el-linear supports either OAuth or a personal Linear API token. OAuth is configured with:

el-linear init oauth

By default, that command walks you through registering your own Linear OAuth app. Teams can make the flow a single browser authorization step by writing a local, untracked app-defaults file at ~/.config/el-linear/team-oauth.json or pointing EL_LINEAR_OAUTH_CONFIG at one:

{
  "linearOAuth": {
    "actor": "user",
    "clientId": "your-linear-oauth-client-id",
    "redirectPort": 8765,
    "scopes": ["read", "write", "issues:create", "comments:create"],
    "passwordManagerPath": "op://vault/item/client_id"
  }
}

passwordManagerPath is optional metadata for humans/scripts; el-linear does not execute password-manager commands from it. Do not put a client_secret in this shared file. The OAuth flow uses PKCE.

For agent/service-account OAuth, authorize the app actor:

el-linear init oauth --actor app

App actor tokens can request app:assignable and app:mentionable, but not admin. The authorized app user ID is stored in oauth.json as viewerId.

OAuth apps that have Linear's client-credentials grant enabled can obtain an app-user token without a browser. Keep the secret out of argv and source it through an environment variable:

export LINEAR_OAUTH_CLIENT_SECRET="..."
el-linear init oauth --client-credentials --actor app \
  --client-id your-linear-oauth-client-id

Use --client-secret-env NAME to read a differently named variable and --scopes read,write,issues:create,comments:create to override the configured scope set. The 0600 profile state stores the secret so el-linear can acquire a new token before expiry and once after an HTTP 401; client-credentials tokens do not have refresh tokens. Keep the scope set stable: Linear revokes an app's existing client-credentials tokens when a new token requests different scopes. This flow is opt-in. Remote automation can keep using LINEAR_API_TOKEN, which remains higher precedence than profile OAuth.

At runtime, credentials are resolved in this order:…