linctl: A Powerful CLI Tool for Linear API Management

Introduction

linctl is a comprehensive command-line interface for interacting with Linear's API. Developed in Go with the Cobra framework, it's designed to be highly efficient and versatile, making it suitable for both developer workflows and automated scripting. It provides a rich set of commands for managing issues, projects, teams, users, and comments directly from your terminal.

Key features include secure authentication via personal API keys, detailed issue management with sub-issue hierarchies and Git branch integration, comprehensive project tracking, and flexible output formats like table, plaintext, and JSON. linctl also emphasizes performance with time-based filtering and sorting options, ensuring a smooth experience even with large Linear workspaces.

Installation

Getting started with linctl is straightforward. Choose the method that best suits your environment:

Homebrew (macOS/Linux)

brew tap dorkitude/linctl
brew install linctl
linctl docs      # Render the README.md

From Source

git clone https://github.com/dorkitude/linctl.git
cd linctl
make deps        # Install dependencies
make build       # Build the binary
make install     # Install to /usr/local/bin (requires sudo)
linctl docs      # Render the README.md

Examples

linctl offers a wide range of commands to manage your Linear workspace. Here are a few examples to get you started:

Authentication and User Info

# Interactive authentication
linctl auth

# Check authentication status
linctl auth status

# Show current user
linctl whoami

Issue Management

# List all issues (defaults to last 6 months)
linctl issue list

# List issues assigned to you, sorted by update date
linctl issue list --assignee me --sort updated

# Search issues using Linear's full-text index
linctl issue search "login bug" --team ENG

# Get issue details (includes git branch, cycle, project, attachments, comments)
linctl issue get LIN-123

# Create a new issue and assign it to yourself
linctl issue create --title "Bug fix" --team ENG --assign-me

# Update issue fields
linctl issue update LIN-123 --title "New title" --state "In Progress" --priority 1

Project and Team Management

# List all projects, including older ones
linctl project list --newer-than all_time

# Get project details by ID
linctl project get 65a77a62-ec5e-491e-b1d9-84aebee01b33

# List all teams with issue counts
linctl team list

# List team members for a specific team
linctl team members ENG

Scripting with JSON Output

#!/bin/bash

# Get all urgent issues in JSON format and parse with jq
urgent_issues=$(linctl issue list --priority 1 --json)
echo "$urgent_issues" | jq '.[] | select(.assignee == "me") | .id'

# Get issue count for different time periods
echo "Last week: $(linctl issue list --newer-than 1_week_ago --json | jq '. | length')"

Why Use It

linctl stands out as an essential tool for anyone working with Linear, especially those looking to enhance productivity and automation. Its agent-first design, combined with human-friendly features, makes it incredibly versatile. You can streamline daily tasks, automate complex workflows, and integrate Linear data into custom scripts and reports with ease. The tool's focus on performance, flexible output formats (table, plaintext, JSON), and comprehensive filtering capabilities ensures that you can quickly access and manipulate the exact information you need, without being overwhelmed by data. Whether you're a developer, project manager, or an automated system, linctl provides the granular control and efficiency required to manage your Linear workspace effectively.