GitHub - flipbit03/lineark: Unofficial Linear CLI, for humans and coding agents

Unofficial Linear CLI and Rust SDK, for humans and coding agents.

Why lineark?

I was using the Linear MCP server for agentic coding and found it ate ~13,000 tokens just to describe its tools, before doing anything useful.

So I built a CLI for Linear. The agent calls it via its shell tool, and when it needs to know what commands exist, it runs lineark usage and gets the full command reference in under 1,000 tokens.

A nice side effect is that I now have a proper Linear CLI for personal scripts and quick lookups.

It's also a standalone Rust SDK (lineark-sdk) if you want to build your own Linear integrations.

Quick start

Install

curl -fsSL https://raw.githubusercontent.com/flipbit03/lineark/main/install.sh | sh

Or via cargo: cargo install lineark

To update to the latest version: lineark self update

Set up your AI agent

Add these lines to your agent's context file (CLAUDE.md, .cursorrules, system prompt, etc.):

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

Your agent discovers all commands at runtime via lineark usage — no tool schemas, no function definitions, no context bloat.

Authenticate

Create a Linear Personal API key and save it:

echo "lin_api_..." > ~/.linear_api_token

For multiple workspaces, use named profiles (~/.linear_api_token_{name}) and switch with --profile:

echo "lin_api_..." > ~/.linear_api_token_work
lineark --profile work whoami

That's it! Your agent is ready to use lineark.

What it can do

Every command supports --help for full details. Most flags accept human-readable names — --team ENG, --assignee "Jane Doe", --labels "Bug,P0" — no UUIDs required.

Run lineark usage for the complete command reference.

SDK: lineark-sdk

Use lineark-sdk as a library in your own Rust projects:

use lineark_sdk::Client;
use lineark_sdk::generated::types::{User, Team, IssueSearchResult};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;

    let me = client.whoami::<User>().await?;
    println!("{:?}", me);

    let teams = client.teams::<Team>().first(10).send().await?;
    for team in &teams.nodes {
        println!("{}: {}", team.key.as_deref().unwrap_or("?"), team.name.as_deref().unwrap_or("?"));
    }

    let results = client.search_issues::<IssueSearchResult>("bug").first(5).send().await?;
    println!("Found {} issues", results.nodes.len());

    Ok(())
}

All query methods are generic over T: DeserializeOwned + GraphQLFields — define custom lean structs with #[derive(GraphQLFields)] to fetch only the fields you need.

Architecture

lineark is four crates:

• lineark-codegen — reads Linear's GraphQL schema and generates typed Rust code
• lineark-sdk — generated types + hand-written core (client, auth, pagination)
• lineark-derive — #[derive(GraphQLFields)] for custom lean types with zero overfetching
• lineark — the CLI, a pure SDK consumer with no raw GraphQL

See docs/ARCHITECTURE.md for diagrams and detailed walkthrough.

License

Licensed under the MIT License. See LICENSE for details.