How to Use Linear for Developers

Linear is a fast, web‑based issue tracker that developers love because it blends clean design with powerful automation. This guide shows you how to set up Linear, link it with GitHub, use the CLI, and call the GraphQL API from code. Follow each step and you’ll have a fully integrated workflow in under an hour.

Table of contents

• 1. Create a Linear account and workspace
• 2. Connect Linear to GitHub
• 3. Install and use the Linear CLI
• 4. Call the Linear GraphQL API from JavaScript
• 5. Automate ticket transitions with webhooks
• 6. Linear vs. competing tools
• FAQ

1. Create a Linear account and workspace

Sign up

Go to linear.app and click “Start free”. Use your work email or a Google account. After confirming the link, you land on the onboarding screen.

Workspace basics

Linear calls a collection of projects a workspace. You can create up to ten projects on the free plan. Click the “+ New Workspace” button on the left sidebar, give it a name (e.g., “Acme Dev Team”), and select a default cycle length (usually two weeks).

2. Connect Linear to GitHub

Add the Linear GitHub app

Open your GitHub repository, go to Settings → Integrations → GitHub Apps, and click “Configure”. Search for “Linear” and install it on the repository.

Map repositories to projects

Back in Linear, open Settings → Integrations → GitHub. Choose the repository you just added and link it to a Linear project (e.g., “Backend API”). Enable “Sync pull request status”.

Result

When a PR references an issue (e.g., #123 in the PR title), Linear automatically changes the issue state to “In Review”. Merging the PR moves the issue to “Done”.

3. Install and use the Linear CLI

Installation

npm install -g @linear/cli
# or using Homebrew
brew install linear-cli

Authentication

Run linear login. A browser tab opens; sign in and grant the CLI token. The token is stored in ~/.linear/config.json.

Common commands

• linear list – shows open issues in the current workspace.
• linear create "Bug: API returns 500" – creates a new issue.
• linear assign 42 @john – assigns issue #42 to user John.
• linear comment 42 "Investigating root cause" – adds a comment.

Example workflow

# Create a new issue from the terminal
linear create "Feature: Add pagination to /orders endpoint"

# Assign to a teammate
linear assign 57 @alice

# List all issues in the “Backend API” project
linear list --project "Backend API"

4. Call the Linear GraphQL API from JavaScript

Get an API token

Open Linear → Settings → API → Personal API Key. Click “Generate new token”. Copy the value; treat it like a password.

Sample fetch request

const fetch = require('node-fetch');

const API_URL = 'https://api.linear.app/graphql';
const TOKEN = 'YOUR_PERSONAL_TOKEN';

async function getIssues() {
  const query = `
    query {
      issues(filter: {state: {name: {eq: "Todo"}}}) {
        nodes {
          id
          title
          createdAt
        }
      }
    }
  `;

  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: TOKEN,
    },
    body: JSON.stringify({ query })
  });

  const data = await response.json();
  console.log(data.data.issues.nodes);
}

getIssues();

This script returns all open “Todo” issues. You can change the filter to fetch by project, assignee, or custom fields.

5. Automate ticket transitions with webhooks

Set up a webhook endpoint

Linear can POST JSON to any HTTPS URL when an issue changes. Below is a minimal Express server that logs the payload.

const express = require('express');
const app = express();
app.use(express.json());

app.post('/linear-webhook', (req, res) => {
  console.log('Webhook received:', req.body);
  res.sendStatus(200);
});

app.listen(3000, () => console.log('Listening on port 3000'));

Register the webhook

In Linear, go to Settings → Integrations → Webhooks → Add Webhook. Paste your endpoint URL (e.g., https://example.com/linear-webhook) and select events: “Issue created”, “Issue updated”, “Issue completed”.

Use case: auto‑assign new bugs

When a bug is created, the payload contains the issue title. Your server can read the title, match keywords, and call the Linear API to assign the issue to the appropriate owner.

6. Linear vs. competing tools

Feature	Linear	Jira	GitHub Issues
UI speed (ms per page load)	120	250	180
Free tier projects	10	Unlimited (but limited fields)	Unlimited
Native GraphQL API	Yes	No (REST only)	No
CLI tool	Yes (linear)	No official	No
Automation rules	Built‑in + webhooks	Power‑ups + scripting	Limited (actions)
Pricing per user	$8/mo	$7/mo (Standard)	Free

Linear wins on speed, GraphQL support, and built‑in CLI. Jira offers more granular reporting for large enterprises. GitHub Issues is free but lacks advanced workflow features.

FAQ

What is Linear?

Linear is a modern issue‑tracking tool built for software teams. It combines project planning, issue management, and workflow automation in a clean UI.

Can Linear be used from the command line?

Yes. Linear offers a CLI called linear that lets you create, list, and update issues directly from your terminal.

How do I connect Linear to GitHub?

Add the Linear GitHub app in your repository settings, select the project you want to sync, and enable automatic status updates on pull requests.

Is there a free tier for developers?

Linear’s free tier includes unlimited members, 10 active projects, and basic integrations. Paid plans start at $8 per user per month.

What languages are supported by Linear’s API?

The API is GraphQL‑based, so any language that can make HTTP POST requests can use it. Official SDKs exist for JavaScript/TypeScript, Python, and Go.

Linear helps developers keep work visible, automate repetitive steps, and stay focused on code. Follow the steps above, customize the automation to your team’s needs, and you’ll see faster cycles and fewer manual updates.