go-linear

module
v2.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 20, 2026 License: Apache-2.0

README

go-linear

Go SDK, CLI, and MCP server for Linear.

Built for humans and AI agents who want to work with Linear without wrestling GraphQL.

Go Reference Go Report Card License

Architecture

Linear GraphQL API
       ↓
   Go SDK (pkg/linear)     ← Type-safe client, generated from schema
       ↓
   CLI (go-linear)         ← Semantic commands, smart defaults
       ↓
   MCP Server              ← Same binary, JSON-RPC mode (via ophis)

Each layer adds value:

Layer What it provides
SDK Type safety, retries, circuit breakers, metrics (for Go developers)
CLI Name resolution, field defaults, filtering, batching (for humans and agents)
MCP Exposes CLI as 100+ tools for AI agents

Installation

From Source
go install github.com/chainguard-sandbox/go-linear/v2/cmd/linear@latest

Note: go install names the binary linear. Examples below use go-linear (the name from make build).

Or:

git clone https://github.com/chainguard-sandbox/go-linear
cd go-linear && make build
Pre-built Binaries

Download from GitHub Releases.

Go SDK
go get github.com/chainguard-sandbox/go-linear/v2

Quick Start

MCP
claude mcp add --scope user --transport stdio go-linear \
  --env LINEAR_API_KEY=lin_api_xxx \
  -- /path/to/go-linear mcp start

Then ask Claude: "What are my urgent issues?" or "What did the team complete this week?"

See Claude Setup Guide for details.

CLI
export LINEAR_API_KEY=lin_api_xxx

go-linear issue list --assignee=me --priority=1
go-linear user completed --team=ENG --completed-after=7d
go-linear issue create --team=ENG --title="Fix bug" --priority=2
Common Tasks
I want to... Command
See my assigned issues issue list --assignee=me
Find urgent issues issue list --priority=1
Create a new issue issue create --team=ENG --title="Fix bug"
Update issue status issue update ENG-123 --state=Done
Add comment to issue comment create --issue=ENG-123 --body="Fixed"
Link PR to issue issue update ENG-123 --link-pr=owner/repo#123
Search issues issue search "authentication"
List team members team members --team=ENG
Bulk update issues issue batch-update --state=Triage --set-state=Backlog
Get completion stats user completed --team=ENG --completed-after=7d
Filter by multiple criteria issue list --team=ENG --priority=1 --state="In Progress"
List with AI suggestions issue list --has-suggested-teams

See CLI Quick Start for all commands and Filters Guide for filter options.

SDK (Go Developers)
client, _ := linear.NewClient("lin_api_xxx")
defer client.Close()

issues, _ := client.Issues(ctx, nil, nil)
for _, issue := range issues.Nodes {
    fmt.Printf("%s: %s\n", issue.Identifier, issue.Title)
}

See SDK Documentation for production configuration.

Design Philosophy

For AI agents, the CLI provides a semantic interface to Linear's GraphQL API, keeping context clean.

Working directly with GraphQL consumes an agent's attention budget on low-signal work:

  • Schema exploration
  • Query composition
  • Pagination management
  • Response parsing

This causes context rot - as tokens accumulate, accuracy degrades.

The CLI operates at the right altitude: high enough to hide GraphQL mechanics, specific enough to express precise intent:

go-linear issue list --team=ENG --priority=1

One command, one response. The agent's context stays high-signal:

What the CLI absorbs What the agent sees
UUID resolution --team=ENG
50+ field responses 8 default fields
Pagination Automatic, or --count for totals
Date parsing --created-after=7d

The CLI also ships with a Claude skill (~10 KB) - decision guides and workflows that provide just-in-time context for complex operations.

The MCP server is auto-generated from the CLI using ophis.

Documentation

Doc Audience
CLI Quick Start Terminal users
Claude Setup MCP/AI agent users
SDK Documentation Go developers
Skill Reference AI agents (loaded as context)
Filters Power users
Migration Upgrading from v1.x

Code Generation

The SDK is generated from Linear's GraphQL schema:

upstream/linear (git submodule)
       ↓
   schema.graphql
       ↓
   gqlgenc (code generator)
       ↓
   internal/graphql/models.go (~30k lines)
   internal/graphql/client.go
       ↓
   pkg/linear/ (public API)

To regenerate after schema updates:

make sync-upstream  # Fetch latest schema + regenerate

Project Info

Status: Stable. Semantic versioning.

Not official: This is a third-party client. Official Linear SDKs at https://github.com/linear

Security: mark.esler@chainguard.dev (72-hour acknowledgment). See SECURITY.md.

License: Apache 2.0

Built with:

  • gqlgenc - GraphQL code generation
  • ophis - Cobra to MCP server
  • clog - Structured logging
  • fido - Tiered caching (memory + filesystem)

Directories

Path Synopsis
cmd
linear command
Linear CLI - Command-line interface for Linear issue tracking.
 Linear CLI - Command-line interface for Linear issue tracking.
linear/commands
Package commands provides the Cobra command structure for the Linear CLI.
 Package commands provides the Cobra command structure for the Linear CLI.
linear/commands/attachment
Package attachment provides attachment commands for the Linear CLI.
 Package attachment provides attachment commands for the Linear CLI.
linear/commands/comment
Package comment provides comment-related commands for the Linear CLI.
 Package comment provides comment-related commands for the Linear CLI.
linear/commands/cycle
Package cycle provides cycle-related commands for the Linear CLI.
 Package cycle provides cycle-related commands for the Linear CLI.
linear/commands/document
Package document provides document commands for the Linear CLI.
 Package document provides document commands for the Linear CLI.
linear/commands/favorite
Package favorite provides favorite (star) commands for the Linear CLI.
 Package favorite provides favorite (star) commands for the Linear CLI.
linear/commands/initiative
Package initiative provides initiative commands for the Linear CLI.
 Package initiative provides initiative commands for the Linear CLI.
linear/commands/issue
Package issue provides issue-related commands for the Linear CLI.
 Package issue provides issue-related commands for the Linear CLI.
linear/commands/label
Package label provides label-related commands for the Linear CLI.
 Package label provides label-related commands for the Linear CLI.
linear/commands/notification
Package notification provides notification management commands for the Linear CLI.
 Package notification provides notification management commands for the Linear CLI.
linear/commands/organization
Package organization provides organization commands for the Linear CLI.
 Package organization provides organization commands for the Linear CLI.
linear/commands/project
Package project provides project-related commands for the Linear CLI.
 Package project provides project-related commands for the Linear CLI.
linear/commands/reaction
Package reaction provides emoji reaction commands for the Linear CLI.
 Package reaction provides emoji reaction commands for the Linear CLI.
linear/commands/roadmap
Package roadmap provides roadmap commands for the Linear CLI.
 Package roadmap provides roadmap commands for the Linear CLI.
linear/commands/state
Package state provides workflow state commands for the Linear CLI.
 Package state provides workflow state commands for the Linear CLI.
linear/commands/status
Package status provides the status command for viewing API rate limits.
 Package status provides the status command for viewing API rate limits.
linear/commands/team
Package team provides team-related commands for the Linear CLI.
 Package team provides team-related commands for the Linear CLI.
linear/commands/template
Package template provides template commands for the Linear CLI.
 Package template provides template commands for the Linear CLI.
linear/commands/user
Package user provides user-related commands for the Linear CLI.
 Package user provides user-related commands for the Linear CLI.
linear/commands/viewer
Package viewer provides commands for getting current user information.
 Package viewer provides commands for getting current user information.
examples
mcp-client command
Package main demonstrates how to interact with the linear-mcp server.
 Package main demonstrates how to interact with the linear-mcp server.
production command
Package main demonstrates production-ready usage of the go-linear client.
 Package main demonstrates production-ready usage of the go-linear client.
profiling command
Package main demonstrates performance profiling with go-linear.
 Package main demonstrates performance profiling with go-linear.
prometheus command
Package main demonstrates Prometheus metrics integration with go-linear.
 Package main demonstrates Prometheus metrics integration with go-linear.
tasks/add_comment command
Package main demonstrates how to add a comment to an issue.
 Package main demonstrates how to add a comment to an issue.
tasks/assign_label command
Package main demonstrates how to assign a label to an issue.
 Package main demonstrates how to assign a label to an issue.
tasks/attach_links command
Package main demonstrates how to attach external links to issues.
 Package main demonstrates how to attach external links to issues.
tasks/batch_operations command
Package main demonstrates efficient bulk operations.
 Package main demonstrates efficient bulk operations.
tasks/concurrent_requests command
Package main demonstrates safe concurrent API requests.
 Package main demonstrates safe concurrent API requests.
tasks/create_issue command
Package main demonstrates how to create an issue in Linear.
 Package main demonstrates how to create an issue in Linear.
tasks/create_label command
Package main demonstrates how to create a label in Linear.
 Package main demonstrates how to create a label in Linear.
tasks/credential_rotation command
Package main demonstrates dynamic credential rotation using CredentialProvider.
 Package main demonstrates dynamic credential rotation using CredentialProvider.
tasks/delete_issue command
Package main demonstrates how to delete an issue in Linear.
 Package main demonstrates how to delete an issue in Linear.
tasks/favorites command
Package main demonstrates how to star (favorite) issues and projects.
 Package main demonstrates how to star (favorite) issues and projects.
tasks/handle_auth_errors command
Package main demonstrates how to handle authentication errors.
 Package main demonstrates how to handle authentication errors.
tasks/handle_circuit_breaker command
Package main demonstrates how to use the circuit breaker pattern.
 Package main demonstrates how to use the circuit breaker pattern.
tasks/handle_rate_limits command
Package main demonstrates how to handle rate limit errors.
 Package main demonstrates how to handle rate limit errors.
tasks/issue_relations command
Package main demonstrates how to create relationships between issues.
 Package main demonstrates how to create relationships between issues.
tasks/list_comments command
Package main demonstrates how to list comments on an issue.
 Package main demonstrates how to list comments on an issue.
tasks/list_issues_iterator command
Package main demonstrates automatic pagination using IssueIterator.
 Package main demonstrates automatic pagination using IssueIterator.
tasks/list_issues_paginated command
Package main demonstrates manual pagination through issues.
 Package main demonstrates manual pagination through issues.
tasks/list_labels command
Package main demonstrates how to list all labels in a workspace.
 Package main demonstrates how to list all labels in a workspace.
tasks/manage_labels command
Package main demonstrates simplified label management with IssueAddLabel and IssueRemoveLabel.
 Package main demonstrates simplified label management with IssueAddLabel and IssueRemoveLabel.
tasks/notifications command
Package main demonstrates notification subscription management.
 Package main demonstrates notification subscription management.
tasks/project_milestones command
Package main demonstrates how to manage project milestones.
 Package main demonstrates how to manage project milestones.
tasks/reactions command
Package main demonstrates how to add emoji reactions to issues.
 Package main demonstrates how to add emoji reactions to issues.
tasks/search_issues command
Package main demonstrates how to search for issues in Linear.
 Package main demonstrates how to search for issues in Linear.
tasks/update_comment command
Package main demonstrates how to update an existing comment.
 Package main demonstrates how to update an existing comment.
tasks/update_issue command
Package main demonstrates how to update an existing issue in Linear.
 Package main demonstrates how to update an existing issue in Linear.
internal
cli
Package cli provides shared types and utilities for CLI commands.
 Package cli provides shared types and utilities for CLI commands.
config
Package config provides user configuration loading from ~/.config/linear/config.yaml
 Package config provides user configuration loading from ~/.config/linear/config.yaml
dateparser
Package dateparser provides date parsing utilities for the Linear CLI.
 Package dateparser provides date parsing utilities for the Linear CLI.
fieldfilter
Package fieldfilter provides default field sets for commands.
 Package fieldfilter provides default field sets for commands.
filter
Package filter provides utilities to build GraphQL filters from CLI flags.
 Package filter provides utilities to build GraphQL filters from CLI flags.
filter/attachment
Package attachment provides filtering for Linear attachments.
 Package attachment provides filtering for Linear attachments.
filter/comment
Package comment provides filtering for Linear comments.
 Package comment provides filtering for Linear comments.
filter/common
Package common provides shared filter implementations using Go generics.
 Package common provides shared filter implementations using Go generics.
filter/cycle
Package cycle provides filter building utilities for Linear cycles.
 Package cycle provides filter building utilities for Linear cycles.
filter/document
Package document provides filtering for Linear documents.
 Package document provides filtering for Linear documents.
filter/initiative
Package initiative provides filtering for Linear initiatives.
 Package initiative provides filtering for Linear initiatives.
filter/issue
Package issue provides filter implementations for Linear issues.
 Package issue provides filter implementations for Linear issues.
filter/label
Package label provides filtering for Linear issue labels.
 Package label provides filtering for Linear issue labels.
filter/project
Package project provides filtering for Linear projects.
 Package project provides filtering for Linear projects.
filter/state
Package state provides filtering for workflow states.
 Package state provides filtering for workflow states.
filter/team
Package team provides filtering for teams.
 Package team provides filtering for teams.
filter/user
Package user provides filtering for users.
 Package user provides filtering for users.
formatter
Package formatter provides output formatting utilities for the Linear CLI.
 Package formatter provides output formatting utilities for the Linear CLI.
graphql
mcptools
Package mcptools provides utilities for enhancing MCP tool definitions
 Package mcptools provides utilities for enhancing MCP tool definitions
resolver
Package resolver provides name-to-ID resolution for Linear resources.
 Package resolver provides name-to-ID resolution for Linear resources.
testutil
Package testutil provides shared test utilities for command tests.
 Package testutil provides shared test utilities for command tests.
pkg
linear
Package linear provides a Go client library for the Linear API.
 Package linear provides a Go client library for the Linear API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.