Linearis: A Linear CLI Tool Built for Humans (and LLM Agents)

TL;DR: I built a CLI tool for Linear.app with JSON output, smart ID resolution, and optimized GraphQL queries; designed for LLM agents and humans who prefer structured data.

I use Linear daily, in all my projects. It just such a nice piece of thoughtful software. It’s fast, well-laid out, flexible without being overwhelming, and respectful of my time both as a planner and a dev. And it looks good.

It’s the anti-JIRA.

The last few months I’ve also been using Claude Code, sst/opencode, and charmbracelet/crush a lot. (Primarily CC.) And naturally, during that time, I wanted to be able to tell the agent to work on this ticket or update that ticket, so I used the official Linear MCP server. It worked great, no complaints.

The Problem(s)

Then one day I discovered the /context command in Claude, Code which gives a nice overview of what’s currently occupying its memory. Of the available 200k tokens, roughly 13k were taken up by the Linear MCP server alone – just by connecting and providing its tool definitions.

Now 13k tokens isn’t much if you’re working with models that have million-token context windows (hello, Gemini Pro). But when you’re dealing with 100k or 200k token limits, that’s a significant chunk of your available context – gone before you even start doing actual work.

Thinking about it, I realized that I am only using maybe three or four tools out of the 20+ that the Linear MCP server offers. Why spend tokens on project-management and workspace-setup features when I’m never going to use them? On top of that, I can’t use that MCP server in shell scripts.¹

My Solution: Linearis

I finally decided to scratch my own itch and build something focused on what I actually do with Linear on the command line and in agent prompts:

• Create and update tickets
• Add comments and labels
• Search and filter issues
• Manage ticket relationships

What I don’t do in these contexts is project management, workspace creation, or administrative setup. That stuff I handle manually in the UI when needed.

So I wrote Linearis, a CLI tool for Linear.app with JSON output, smart ID resolution, and optimized GraphQL queries. I designed it for LLM agents and humans who prefer structured data.

It’s a command-line tool that outputs JSON, resolves ticket IDs smartly, and sips keeps token usage light.

Installation

npm install -g --install-links czottmann/linearis

Once installed, authenticate yourself, and then you’re good to go.

Usage Examples

# Show usage
linearis

# Show *everything* the agent needs to know
linearis usage

# Create tickets with full context
linearis issues create "Fix login timeout" --team Backend \
  --assignee user123 --labels "Bug,Critical" --priority 1

# Create bare-bones sub-issues 
linearis issues create "Fix login timeout" --parent-ticket ABC-234

# Smart ID resolution - works with ABC-123 format
linearis issues read DEV-456
linearis issues update ABC-123 --state "In Review"

# JSON output plays nice with other tools, like jq
linearis issues list -l 5 | jq '.[] | .identifier + ": " + .title'

# Add comments to track progress
linearis comments create ABC-123 --body "Fixed in PR #456"

Using Linearis in a LLM agent

It’s agent-friendly by design. The key idea was making it dead simple for LLM agents to understand and use the tool:

linearis usage

This single command returns comprehensive yet concise usage information for all available tools. Agents can pipe this directly into their context and immediately understand everything the tool can do.

The flags and options are well-documented and consistently structured, so agents can easily call it through their Bash tools without any special integration.

So I put this in my CLAUDE.md:

We track our tickets and projects in Linear (https://linear.app), a project management tool. We use the linearis CLI tool for communicating with Linear. Use your Bash tool to call the linearis executable. Run linearis usage to see usage information.

The ticket numbers follow the format “ZCO-”. Always reference tickets by their number.

If you create a ticket, and it’s not clear which project to assign it to, prompt the user. When creating sub-issues, use the project of the parent ticket by default.

When the the status of a task in the ticket description has changed (task → task done), update the description accordingly. When updating a ticket with a progress report that is more than just a checkbox change, add that report as a ticket comment.

That’s probably overly verbose, I guess. 😉 Some examples for prompts I use daily:

• “we’re working on ABC-1234 now”
• later: “add a progress report to the ticket”
• “mark ABC-2345 as ‘in progress’"
• “make this a sub-issue of ABC-3456”
• “mark ABC-4567 as a bug”

The Result

I’ve been using Linearis for a while now, both manually and with my agentic tools. It does exactly what I need it to do without the overhead I don’t need. The agents can create tickets, update them, add comments, and manage labels efficiently. And when I need to do project setup or workspace management, I just use Linear’s web UI.

Sometimes the best tool is the one that doesn’t try to do everything – just the things you actually need, done well. Linearis solves my particular requirements, but I think it might be helpful to you, too.

Check it out on GitHub.