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. 1. Get your API key from Linear: https://linear.app/settings/api

1. 2. Set credential with custom Authorization header:

Or use environment variable:
CODEBLOCK1

1. 3. Bind endpoint:

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. 1. Create an OAuth app in Linear: https://linear.app/settings/api

1. 2. Start OAuth login:

After approval, complete it with:
CODEBLOCK4

1. 3. Bind endpoint:

Core Workflow

1. 1. Use fixed link command by default:

1. 2. Discover operations:

1. 3. Inspect specific operation:

1. 4. Execute queries:

Available Operations

Queries

• - query/issues - List and filter issues
• INLINECODE19 - Get single issue
• INLINECODE20 - List teams
• INLINECODE21 - Get single team
• INLINECODE22 - List projects
• INLINECODE23 - List workflow states

Mutations

• - mutation/issueCreate - Create new issue
• INLINECODE25 - Update issue
• INLINECODE26 - Archive issue
• INLINECODE27 - Add comment

Usage Examples

List recent issues

Get issue by ID

List teams

Create issue

Troubleshooting

Authentication Errors

Error: "Bearer token" prefix rejected

• - Linear API does not accept INLINECODE28
• Ensure credential uses INLINECODE29
• Do not use INLINECODE30

Error: "Credential not found"

• - Check credential exists: INLINECODE31
• Verify binding: INLINECODE32
• Create binding if missing (see Authentication section)

OAuth login spans multiple agent turns

• - Prefer uxc auth oauth start ... and INLINECODE34
• Use uxc auth oauth login ... --flow authorization_code only when one process can wait for the pasted callback URL

Error: "No binding matched"

• - Check binding exists: INLINECODE36
• If missing, create binding with uxc auth binding add (see Authentication section)

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

Common Issues

Daemon issues after credential changes

• - Restart daemon: INLINECODE40
• Check status: INLINECODE41

Environment variable not found

• - Ensure variable is exported in daemon's environment
• Or use --secret for literal values (less secure)
• Or use --secret-op for 1Password (most secure)

Guardrails

• - Keep automation on JSON output envelope; do not use --text.
• Parse stable fields first: ok, kind, data, error.
• Prefer positional JSON for non-string and typed arguments (for example: linear-graphql-cli query/issues '{"first":10}' and linear-graphql-cli mutation/issueCreate '{"input":{"teamId":"TEAM_ID","title":"Test"}}').
• Use reserved GraphQL argument _select (string) when you need explicit return fields, e.g. {"_select":"nodes { identifier title }"}.
• Use linear-graphql-cli as the default command path.
• INLINECODE54 is equivalent to uxc https://api.linear.app/graphql <operation> ....
• Prefer read operations first (query/), then write operations (mutation/).
• For write operations, always confirm user intent before execution.
• If auth fails, check credential with uxc auth credential info linear-graphql.

References

• - Linear API Documentation: https://developers.linear.app
• GraphQL Schema: https://studio.apollographql.com/public/Linear-API
• Invocation patterns: INLINECODE57