Linear API SDK, Code Generation, and Import Tooling

Where the Linear API Toolchain Fits

The linear/linear repository addresses programmatic access to Linear rather than the issue-tracking interface itself. Its primary package, `@linear/sdk`, is a TypeScript client for Linear's GraphQL API. The monorepo also publishes `@linear/import` for uploading data from other systems and three code-generation packages: `@linear/codegen-doc`, `@linear/codegen-sdk`, and `@linear/codegen-test`.

This split serves two distinct audiences. An application developer normally consumes the generated SDK rather than editing the monorepo. A contributor who changes API coverage or generation behavior works across the GraphQL schema, plugins, generated documents, SDK models, and generated tests. The SDK is the relevant adoption point for most integrations. The generator packages are primarily repository infrastructure.

The root package is private and has the package name `linear`, so it should not be installed as though it were a finished end-user application. The README directs SDK and API users to `developers.linear.app/docs`. The GitHub package tree identifies what is published, while the external developer documentation is the stated source for API and SDK guidance.

For most application teams, the choice is between taking `@linear/sdk` as a package dependency and issuing Linear GraphQL requests directly. Importing the private root project would pull developers into the client-generation workspace without providing a separate end-user interface. The repository's package layout matters when deciding what belongs in an application and what exists only to maintain the SDK.

How Linear Generates Its Typed GraphQL Client

The SDK is generated rather than hand-maintained as a complete set of API models and operations. Custom GraphQL Code Generator plugins transform the production API representation into typed source files. Names beginning with `_generated` are explicitly marked as generated code that should not be edited manually.

The generation flow has three distinct stages. First, `codegen.doc.yml` invokes `@linear/codegen-doc` to create fragments and GraphQL documents. The resulting documents are written to `packages/sdk/src/_generated_documents.graphql`. Second, `codegen.sdk.yml` uses `@linear/codegen-sdk` to produce the typed client in `packages/sdk/src/_generated_sdk.ts`. Third, `codegen.test.yml` invokes `@linear/codegen-test` to create a typed Vitest test in `packages/sdk/src/_tests/_generated.test.ts`.

This architecture keeps the public TypeScript surface aligned with the API schema, but it also creates a strict maintenance boundary. A change to an operation or model may require the schema and generation stages to run before generated output is reviewed. Directly modifying `_generated` files conflicts with the source definitions that produce them.

The root build coordinates these stages through several scripts. `pnpm generate` runs clean, document, and SDK generation. Separate `generate:doc`, `generate:sdk`, and `generate:test` scripts allow a contributor to regenerate each artifact category. The full `pnpm build` command also builds the SDK and import package, generates tests, builds types, and processes documentation.

There is an important distinction between generation and schema acquisition. The `schema` command retrieves the current production API representation, while generation converts the repository's schema and documents into typed code. A contributor who needs to assess recent API changes must account for both steps rather than assuming that running the SDK generator alone refreshes the schema.

Building linear/linear from the Monorepo

The README requires Node 18 or later and pnpm. The root `package.json` also declares `"node": ">=18.x"`. The following tutorial is for contributors, not for an application that only needs `@linear/sdk`.

Run this from the repository root after Node 18 or later and pnpm are available:

pnpm install

This installs the pnpm workspace dependencies. After installation completes, build every package and its generated documentation:

pnpm build

The build script runs generation, SDK and import builds, test generation, type builds, and documentation processing. The README does not prescribe a success message, so build output alone should not be the only confirmation of a successful build.

Run the regular package tests with:

pnpm test

That executes `pnpm -r test`, so the command delegates testing to workspace packages. The root package also defines `pnpm test:e2e`, but it sets `E2E=true` and filters the SDK test command. The README does not document additional credentials or services required for that mode.

A first contributor pass should therefore use the documented dependency installation and full build before changing generated output. This creates the complete package graph and generation outputs required by the workspace. The repository's `lint` command is separate and is defined as `eslint --max-warnings 0 .`.

Updating the Linear API Schema

The repository includes a documented command for updating the schema from the production API:

pnpm schema

At the root, this command delegates to `pnpm run update:schema`. That script regenerates package schemas and creates a schema changeset. The generation process can then derive GraphQL documents, the TypeScript SDK, and typed tests from the updated representation.

This is not a routine command for a consumer of `@linear/sdk`. It is intended for maintainers working against the production API. The README does not document authentication requirements for `pnpm schema`, fallback behavior when the schema request fails, or the exact output to inspect.

Changesets are part of the release workflow. The README provides the following command for creating a changeset used to generate `CHANGELOG.md`:

pnpm changeset

This indicates that schema-driven SDK changes have an explicit release record instead of relying solely on direct commits to generated files. The root publishing script, `pnpm ci:publish`, publishes workspace packages recursively and then runs `changeset tag`.

The repository also defines narrower generation scripts. `generate:doc` builds and runs the document generator, `generate:sdk` builds and runs the SDK generator, and `generate:test` builds and runs the test generator. This separation is useful when reviewing one generated artifact, but the README presents the build command as the normal way to build all packages.

SDK Integration Versus Linear Import Tooling

The generated SDK is the practical choice when a TypeScript application wants Linear operations and models through a typed client instead of constructing GraphQL requests itself. Its value comes from generated type coverage across the API surface exposed by Linear. The repository describes `@linear/sdk` as the client for the Linear GraphQL API.

For migrations, `@linear/import` has a different role. It is described specifically as import tooling for uploading from other systems. A team moving records from an external tracker should inspect that package's README before assuming that the SDK's request interface includes the desired migration path. The top-level README does not specify supported source systems, mapping rules, conflict handling, or resumability.

Using the Linear GraphQL API directly is the real alternative to adopting `@linear/sdk`. Direct API access leaves request construction and client-side typing under the application's control, but it does not supply the repository's generated TypeScript operations and models. The SDK takes on more coupling to generated API code, while direct GraphQL makes each operation explicit in application code.

The README does not document package size, request latency, retry behavior, or error semantics for either approach. Those details should not be inferred from the existence of generated TypeScript. An application that values generated API types may prefer the SDK, while a codebase with its own GraphQL conventions may retain direct requests and use the repository mainly as a schema reference.

Generated Code, Releases, and Environment Boundaries

The primary operational boundary is that generated files must not become an editing surface. A developer should change the relevant schema, configuration, or code-generation input, regenerate the outputs, and inspect the resulting changes. The repository includes separate scripts for cleaning generated content, generating documents, generating the SDK, and generating tests.

Release maintenance is coordinated with Changesets. Recent published packages include `@linear/sdk` 97.2.0 on 2026-10-14 and `@linear/import` 4.0.2 on 2026-10-14. The repository's last push was on 2026-10-15, and the repository is not archived. Those facts document recent repository and package activity, but they do not establish compatibility with every application dependency graph.

The repository includes `.env.example` with the following declared value:

API_KEY=

The file confirms that an `API_KEY` setting exists in the repository environment template. It does not show how the value is consumed, which commands require it, or how an API key is created. The README directs application developers to the external Linear developer documentation for SDK and API guidance rather than presenting this empty environment field as an authentication tutorial.

This distinction also affects first-use verification. A contributor can build the workspace using the documented commands. An application developer still needs the authentication procedure documented by Linear before making authenticated API requests. The repository does not include a complete runnable application example for fetching a Linear issue, and the top-level README does not supply one.

MIT Licensing and Monorepo Upgrade Cost

The repository and its `package.json` identify the MIT license, and the README links to `LICENSE`. That designation applies to the open source content published from this repository, but using an SDK still requires review of the selected package's dependencies and the permissions required for the intended Linear API operations.

The monorepo uses pnpm workspaces. Its root scripts orchestrate several packages, including the SDK, import utility, and generation plugins. Contributors should use the repository commands rather than attempting to reproduce a partial workspace manually. Consumers should select the published package that matches their task instead of taking a dependency on the private root package.

Upgrade cost is tied to generated API changes when contributing to the client. Package releases and Changesets provide release artifacts and changelog records, while schema updates can alter operations and models used by downstream TypeScript code. The README does not state a deprecation window or compatibility policy, so those details cannot be inferred from the release numbers.

The package versions also show that `@linear/sdk` and `@linear/import` have separate release streams. Applications should avoid pinning either package to the root repository name and should review the selected package's release notes before upgrading. The repository layout favors coordinated SDK generation, but it leaves the integration decision with the consuming application.

Editorial conclusion

Application developers needing Linear's typed TypeScript client should assess `@linear/sdk` first, while contributors to the generated client need Node 18 or later and pnpm. Organizations pursuing a one-off data transfer should inspect `@linear/import` instead. Before adoption, verify the current API documentation, authentication requirements, generated API surface, and support for the source format being migrated.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. linear/linear on GitHub
4. README
5. Releases