lineark-sdk

Typed, async-first Rust SDK for the Linear GraphQL API.

Part of the lineark project — an unofficial Linear ecosystem for Rust.

Install

cargo add lineark-sdk

Quick start

use lineark_sdk::Client;

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

    let me = client.whoami().await?;
    println!("Logged in as: {}", me.name.as_deref().unwrap_or("?"));

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

    Ok(())
}

Authentication

Create a Linear API token and provide it via any of these methods (in priority order):

Queries

Collection queries use a builder pattern with optional pagination and filtering:

// Paginate with first/last/after/before
let issues = client.issues().first(25).send().await?;
let page2 = client.issues().first(25).after(issues.page_info.end_cursor.unwrap()).send().await?;

// Search with extra filters
let results = client.search_issues("bug")
    .first(10)
    .team_id("team-uuid")
    .include_comments(true)
    .send()
    .await?;

All collection queries support .first(n), .last(n), .after(cursor), .before(cursor), and .include_archived(bool).

Mutations

use lineark_sdk::generated::inputs::IssueCreateInput;

let payload = client.issue_create(IssueCreateInput {
    title: Some("Fix the bug".to_string()),
    team_id: Some("team-uuid".to_string()),
    priority: Some(2),
    ..Default::default()
}).await?;

File upload and download

The SDK provides high-level helpers for Linear's file operations:

// Upload a file (two-step: get signed URL from Linear, then PUT to GCS)
let bytes = std::fs::read("screenshot.png")?;
let result = client.upload_file("screenshot.png", "image/png", bytes, false).await?;
println!("Asset URL: {}", result.asset_url);

// Download a file from Linear's CDN
let result = client.download_url("https://uploads.linear.app/...").await?;
std::fs::write("output.png", &result.bytes)?;

Blocking (synchronous) API

For non-async contexts, enable the blocking feature:

[dependencies]
lineark-sdk = { version = "...", features = ["blocking"] }

The blocking client mirrors the async API exactly:

use lineark_sdk::blocking_client::Client;

let client = Client::auto()?;

let me = client.whoami()?;
println!("Logged in as: {:?}", me.name);

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

// Mutations work the same way
let payload = client.document_create(input)?;

// File operations too
let result = client.upload_file("file.txt", "text/plain", bytes, false)?;
let downloaded = client.download_url(&result.asset_url)?;

Error handling

All methods return Result<T, LinearError>. Error variants:

• Authentication — invalid or expired token
• Forbidden — insufficient permissions
• RateLimited — API rate limit hit (includes retry_after)
• InvalidInput — bad request parameters
• GraphQL — errors returned in the GraphQL response
• Network — connection/transport failures
• HttpError — non-200 responses not covered above
• MissingData — expected data path not found in response
• AuthConfig — auth configuration error (no token found)
• Internal — internal error (e.g. runtime creation failure)

Codegen

All types, enums, inputs, and query functions are generated from Linear's official GraphQL schema. The generated code lives in src/generated/ and is checked in for reproducible builds.

License

MIT