Getting started¶

Install¶

uv add linear-python-client
# or
pip install linear-python-client

Or, working inside a clone of the repository:

uv sync

The package requires Python 3.14+ and depends on httpx and pydantic.

Get a token¶

You can authenticate in two ways:

Personal API key — create one in Linear under Settings → Security & access → Personal API keys. Best for scripts and internal tooling.
OAuth 2.0 access token — for applications acting on behalf of other users. See the Linear OAuth docs.

Create a client¶

API keyOAuth tokenFrom the environment

from linear_python_client import LinearClient

client = LinearClient(api_key="lin_api_...")

from linear_python_client import LinearClient

client = LinearClient(access_token="...")

# Reads LINEAR_API_KEY from the environment.
from linear_python_client import LinearClient

client = LinearClient()

Prefer the context-manager form so the underlying HTTP connection is closed for you:

with LinearClient() as client:
    print(client.viewer().viewer.name)

Make your first call¶

Every method takes a typed *Request and returns a typed *Response. viewer() takes no input, so it's the simplest call — its response exposes .viewer:

with LinearClient() as client:
    me = client.viewer().viewer
    print(me.id, me.name, me.email)

If the credentials are wrong you'll get a LinearAuthenticationError. See Error handling for the full list.

Next: the Usage guide.