LinearSDK

LinearSDK is an Elixir SDK for Linear with a thin provider-facing client and a generated full-schema API reference published as module docs.

The repo is intentionally thin:

• committed upstream schema and reference artifacts live in priv/upstream/
• provider configuration lives in codegen/
• provider-facing handwritten code stays focused on Linear defaults and ergonomics
• generated internal support code and API reference docs are committed source

What this repo owns

• Linear-specific base URL defaults
• provider-local auth shortcuts for personal API keys and OAuth access tokens
• committed upstream schema artifacts
• full generated API reference docs for the upstream graph
• a small curated document set used for internal generation coverage
• local generation and verification tasks

Install

def deps do
  [
    {:linear_sdk, "~> 0.1.0"}
  ]
end

mix deps.get

For active local development beside sibling checkouts, linear_sdk can also be consumed from a relative path:

{:linear_sdk, path: "../linear_sdk"}

Inside this repo, the shared prismatic dependencies resolve by one stable policy:

• prefer sibling-relative paths when local checkouts exist
• otherwise use Hex prismatic ~> 0.1.0 plus GitHub subdir: dependencies for prismatic_codegen and prismatic_provider_testkit

That keeps local development, packaging, and downstream dependency behavior aligned without requiring a committed vendored deps/ tree.

Real Linear Onboarding

The current upstream linear/linear repo and Linear's live docs both point to the same operating model:

• personal API keys are created in Linear under Settings -> Security & access -> Personal API keys
• OAuth is supported, but the app registration and token exchange flow are your responsibility
• SDKs expect you to bring a token; they do not acquire, store, rotate, or refresh credentials for you

LinearSDK makes those two auth modes explicit:

# Personal API key from Linear settings
client =
  LinearSDK.Client.new!(
    api_key: System.fetch_env!("LINEAR_API_KEY")
  )

# OAuth access token that you obtained elsewhere
oauth_client =
  LinearSDK.Client.new!(
    access_token: System.fetch_env!("LINEAR_OAUTH_ACCESS_TOKEN")
  )

For a step-by-step setup walkthrough, including how to find your project slug, issue reference, and target workflow states, see guides/real-linear-usage.md.

First Live Query

client =
  LinearSDK.Client.new!(
    api_key: System.fetch_env!("LINEAR_API_KEY")
  )

{:ok, response} =
  LinearSDK.execute_document(
    client,
    """
    query Viewer {
      viewer {
        id
        name
        email
      }
    }
    """
  )

Live Examples

All example scripts under examples/ are real Linear connections only. They do not use mocks or fake transports.

export LINEAR_API_KEY=lin_api_...
examples/run_all.sh

That default suite is read-only and auto-discovers a project slug and issue when your workspace has accessible data. If there is no accessible project slug, the polling example falls back to a workspace-scoped issue query so the suite still runs. Mutation examples are available too, but they intentionally require LINEAR_CONFIRM_WRITE=1 before they will comment on or transition a real issue. See examples/README.md for the full list.

Docs Map

• Getting Started: install, client creation, and first document execution
• Client Configuration: base URL, auth modes, transport overrides, and telemetry
• Real Linear Usage: user-friendly onboarding for personal API keys, OAuth notes, and Symphony-oriented workflows
• Executing GraphQL Documents: ad hoc GraphQL document execution against the Linear API
• Generation and Verification: local generation and freshness checks
• Upstream Artifacts: copied schema inputs, curated documents, and official reference manifests
• Examples: runnable live examples for common Linear and Symphony-style flows

API reference is published under the Modules tab in HexDocs:

• LinearSDK.Queries
• LinearSDK.Mutations
• LinearSDK.Subscriptions
• LinearSDK.Objects
• LinearSDK.Inputs
• LinearSDK.Interfaces
• LinearSDK.Unions
• LinearSDK.Enums
• LinearSDK.Scalars

Generation Tasks

mix linear.ir
mix linear.generate
mix linear.verify

Generation consumes the committed upstream schema files:

• priv/upstream/schema/schema.json
• priv/upstream/schema/schema.graphql

Quality Bar

mix ci

That runs:

• format check
• warnings-as-errors compile
• tests
• Credo
• Dialyzer
• docs