Linear Issues

A read-only Linear issue browser for your editor or terminal. Both clients live in this repository and share the same paginated Linear data layer, issue model, and Team → Project → Status categorization.

Both clients use @linear/sdk, fetch every issue accessible to the authenticated user across every team, and load issue descriptions, activity, and comments on demand.

Terminal client

Node.js 22.13 or newer is required.

npm install --global linear-issues
linear-issues

The UI uses a side-by-side issue tree and detail pane at 96 columns or wider. Narrow terminals automatically switch to a top-and-bottom layout. The minimum usable size is 34 columns by 14 rows.

Authentication

For a temporary or unattended session, provide a personal API key without storing it:

LINEAR_API_KEY=lin_api_... linear-issues

For normal interactive use, log in once:

linear-issues auth login --api-key

The CLI prefers the operating system credential manager. If one is unavailable—for example, in some minimal WSL environments—it asks before using a private 0600 credential file. You can approve that fallback up front with --allow-file-storage.

OAuth with PKCE is also supported when you have a Linear OAuth application. Configure http://127.0.0.1:43817/oauth/callback as an allowed callback URL, then run:

linear-issues auth login --oauth --client-id YOUR_CLIENT_ID

Use LINEAR_OAUTH_CLIENT_ID to provide the default client ID. OAuth requests read-only access, refreshes expiring tokens, and attempts to revoke the refresh token during logout.

linear-issues auth status
linear-issues auth logout

Controls

Press ? in the app for the complete shortcut overlay.

Automatic refresh defaults to 30 minutes. The tree is fully paginated, so large workspaces are not truncated. Search and filters operate locally after the current workspace snapshot is loaded.

Descriptions and comments render common Markdown. Images use ink-picture only when the terminal advertises Kitty, iTerm2, or Sixel graphics; otherwise the UI shows an “image unavailable” message and does not attempt an inline fallback.

Persistent settings

The CLI remembers the selected My/All view, completed-item toggle, expanded groups, last selected issue, refresh interval, team/project filters, and current workspace profile. Inspect the active configuration and its path with:

linear-issues config show

Settings can also be scripted:

linear-issues config set view all
linear-issues config set hide-completed false
linear-issues config set refresh-interval 30
linear-issues config reset-ui

Set the refresh interval to 0 to disable automatic refresh.

VS Code extension

The extension requires Linear Connect for authentication. Open the Linear Issues activity-bar view to browse All Issues and My Issues, grouped by team, project, and status. Selecting an issue opens its Markdown description, activity, comments, and supported Linear-hosted images in the details view.

The title-bar actions refresh either tree and toggle whether completed issues are shown.

Repository structure

linear-issues/
├── src/                 VS Code extension
├── resources/           VS Code icons
├── packages/
│   ├── core/            Shared Linear SDK, domain, pagination, and grouping logic
│   └── cli/             Ink terminal application published as linear-issues
└── .github/workflows/   CI and independent release pipelines

Install all workspaces from the repository root:

npm ci
npm run check

Useful focused commands:

npm run dev --workspace packages/cli
npm run check:cli
npm run check:core
npm run check:extension
npm test                 # VS Code extension-host tests
npm run package:vscode
npm run package:cli

Release tags and the independent Marketplace/npm pipelines are documented in docs/RELEASING.md.