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: admin@example.com
      name: Admin User
      admin: true
    - email: dev@example.com
      name: Developer
  teams:
    - key: ENG
      name: Engineering
  issues:
    - team: ENG
      title: Fix local checkout test
      state: Todo
      assignee: dev@example.com
  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: admin@example.com
      scopes: [read, write, issues:create, comments:create, admin]
  strict_scopes: false

GraphQL Surface

Supported queries:

• viewer
• organization
• users, user
• teams, team
• workflowStates, workflowState
• issues, issue
• comments, comment
• issueLabels, issueLabel
• projects, project
• cycles, cycle
• webhooks, webhook
• agentSessions, agentSession

Supported mutations:

• issueCreate, issueUpdate, issueDelete, issueArchive, issueUnarchive
• commentCreate, commentUpdate, commentDelete
• issueLabelCreate, issueLabelUpdate, issueLabelDelete
• issueAddLabel, issueRemoveLabel
• webhookCreate, webhookDelete
• agentSessionCreateOnIssue, agentSessionCreateOnComment, agentSessionUpdate
• agentActivityCreate

Connections use Relay-style cursors with nodes, edges, and pageInfo.

Issue selections expose both numeric priority and Linear's derived priorityLabel values: No priority, Urgent, High, Medium, and Low.

OAuth

• GET /oauth/authorize - authorization endpoint with local user picker
• POST /oauth/authorize/callback - local user picker callback
• POST /oauth/token - authorization code, refresh token, and client credentials grants
• POST /oauth/revoke - revoke access or refresh tokens

OAuth apps can use actor: user or actor: app. The configured actor is authoritative. User actor apps use authorization code flows. App actor apps use the app install flow and can request client credentials tokens. App actor support is sufficient for local agent and service-account tests, but it is not full production Linear agent behavior.

Webhooks

Create local webhook subscriptions through webhookCreate or seed config. Supported writes dispatch Linear-shaped payloads with Linear-Delivery, Linear-Event, and Linear-Signature headers when a secret is configured.

Inspector

Open GET / in the Linear emulator to inspect issues, teams, users, projects, agent sessions, OAuth apps, tokens, webhook subscriptions, and webhook deliveries.

Current Limits

Full Linear schema coverage, exact production rate limiting, notification inbox behavior, rich document APIs, customer APIs, initiative APIs, exact search relevance, and full production agent behavior are not implemented.

Custom emulators alongside built-ins

Use npx emulate init --custom inventory to scaffold a third-party API emulator and test. Register it in emulate.config.ts with defineConfig from emulate, alongside built-in entries such as { emulator: "linear" }. Run npx emulate start --watch to reload imports and inspect custom state at the printed /_emulate URL. Successful reloads reset the run to seed. Existing flat seed configs still work; --config selects an explicit file. For authoring and testing third-party API emulators, see https://emulate.dev/docs/custom-emulators.