UXC

One CLI for tools across protocols.

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

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

    After approval, complete it with:

    uxc auth oauth complete linear-graphql \
  --session-id <session_id> \
  --authorization-response 'http://127.0.0.1:8788/callback?code=...&state=...'

  3. Bind endpoint:

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

Core Workflow

  1. Use fixed link command by default:

    • command -v linear-graphql-cli
    • If the command exists, confirm it is the expected uxc link for this skill before using it.
    • If a command conflict is detected and cannot be safely reused, stop and ask skill maintainers for guidance instead of dynamically renaming the command.
    • If missing, create it: uxc link linear-graphql-cli https://api.linear.app/graphql
    • linear-graphql-cli -h

  2. Discover operations:

    • linear-graphql-cli -h
    • Returns hundreds of GraphQL operations

  3. Inspect specific operation:

    • linear-graphql-cli query/issues -h
    • linear-graphql-cli mutation/issueCreate -h

  4. Execute queries:

    # Query issues (simple)
linear-graphql-cli query/issues '{"first":10}'

# Query issues with explicit selection set for useful fields
linear-graphql-cli query/issues '{"first":10,"_select":"nodes { identifier title url state { name } assignee { name } }"}'

# Query teams
linear-graphql-cli query/teams '{"first":10}'

# Create issue (requires write scope)
linear-graphql-cli mutation/issueCreate '{
  "input": {
    "teamId": "TEAM_ID",
    "title": "New Issue Title",
    "description": "Issue description"
  }
}'

Available Operations

Queries

Mutations

Usage Examples

List recent issues

linear-graphql-cli query/issues '{"first":20,"_select":"nodes { identifier title url state { name } assignee { name } }"}'

Get issue by ID

linear-graphql-cli query/issue id=ISSUE_ID

List teams

linear-graphql-cli query/teams

Create issue

linear-graphql-cli mutation/issueCreate '{"input":{"teamId":"YOUR_TEAM_ID","title":"Fix bug"}}'

Troubleshooting

Authentication Errors

Error: "Bearer token" prefix rejected

Error: "Credential not found"

OAuth login spans multiple agent turns

Error: "No binding matched"

For detailed authentication troubleshooting, see uxc skill's references/auth-configuration.md.

Common Issues

Daemon issues after credential changes

Environment variable not found

Guardrails

References