linear

Linear API Emulator

Stateful Linear GraphQL API emulation with organizations, users, teams, workflow states, issues, comments, labels, projects, cycles, OAuth apps, tokens, webhooks, and basic agent sessions.

Start

Local listeners bind to 127.0.0.1 by default. For access from containers or other machines, pass --host 0.0.0.0 to the CLI or hostname: '0.0.0.0' to createEmulator. Configure --base-url or baseUrl for advertised URLs reachable by those clients.

# Linear only
npx emulate --service linear

Default URL: http://localhost:4012 when all services are started, or http://localhost:4000 when Linear is the only service.

URL Mapping

Real Linear URL	Emulator URL
https://api.linear.app/graphql	$LINEAR_EMULATOR_URL/graphql
https://linear.app/oauth/authorize	$LINEAR_EMULATOR_URL/oauth/authorize
https://api.linear.app/oauth/token	$LINEAR_EMULATOR_URL/oauth/token
https://api.linear.app/oauth/revoke	$LINEAR_EMULATOR_URL/oauth/revoke

Auth

GraphQL accepts a bearer token or bare personal API key:

curl "$LINEAR_EMULATOR_URL/graphql" \
  -H "Authorization: Bearer lin_test_admin" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ viewer { id email } }"}'

Scope checks are relaxed by default. Set linear.strict_scopes: true in seed config to require supported operation scopes such as read, write, issues:create, comments:create, and admin.

Seed Config

linear:
  organization:
    name: Acme
    url_key: acme
  users:
    - email: [email protected]
      name: Admin User
      admin: true
    - email: [email protected]
      name: Developer
  teams:
    - key: ENG
      name: Engineering
  issues:
    - team: ENG
      title: Fix local checkout test
      state: Todo
      assignee: [email protected]
  oauth_apps:
    - client_id: lin_example_client_id
      client_secret: example_client_secret
      name: My Linear App
      redirect_uris:
        - http://localhost:3000/api/auth/callback/linear
      scopes: [read, write, issues:create, comments:create]
  tokens:
    - token: lin_test_admin
      user: [email protected]
      scopes: [read, write, issues:create, comments:create, admin]
  strict_scopes: false