linear-graphql-skill

Linear GraphQL Skill

Use this skill to run Linear GraphQL API operations through uxc.

Reuse the uxc skill guidance for discovery, schema inspection, auth lifecycle, and error recovery.

Prerequisites

• uxc is installed and available in PATH.
• Network access to https://api.linear.app/graphql.
• Linear API key or OAuth credentials available.

Authentication

Linear supports two authentication methods:

Option 1: Personal API Key (Recommended for development)

1. Get your API key from Linear: https://linear.app/settings/api

2. Set credential with custom Authorization header:

   uxc auth credential set linear-graphql \
     --auth-type api_key \
     --header "Authorization:{{secret}}" \
     --secret "lin_api_XXX"
   

   Or use environment variable:

   export LINEAR_API_KEY="lin_api_XXX"
   uxc auth credential set linear-graphql \
     --auth-type api_key \
     --header "Authorization:{{secret}}" \
     --secret-env LINEAR_API_KEY
   

3. Bind endpoint:

   uxc auth binding add \
     --id linear-graphql \
     --host api.linear.app \
     --path-prefix /graphql \
     --scheme https \
     --credential linear-graphql \
     --priority 100
   

Important (Personal API Key only): Linear API keys require Authorization: lin_api_XXX format (no Bearer prefix). The --header "Authorization:{{secret}}" configuration above is required for API key auth. For OAuth access tokens, use standard Authorization: Bearer <token> semantics (handled by the OAuth credential flow in uxc).

Credential/binding IDs in this skill use linear-graphql by convention; IDs are local aliases and can be changed if needed.

Option 2: OAuth 2.0 (For production/user-delegated access)

1. Create an OAuth app in Linear: https://linear.app/settings/api

2. Start OAuth login:

   uxc auth oauth start linear-graphql \
     --endpoint https://api.linear.app/graphql \
     --redirect-uri http://127.0.0.1:8788/callback \
     --scope read \
     --scope write