Use GRAPHQL API

Use GraphQL API

Discover, construct, execute, chain GraphQL operations from command line.

When Use

• Query or mutate data via GraphQL endpoint (GitHub, Hasura, Apollo, etc.)
• Automate GitHub operations needing GraphQL (Discussions, Projects v2)
• Build shell scripts fetching structured data from GraphQL APIs
• Chain multiple GraphQL calls where output of one feeds next

Inputs

• Required: GraphQL endpoint URL or service name (e.g., github)
• Required: Operation intent (what data to read or write)
• Optional: Auth token or method (default: gh CLI auth for GitHub)
• Optional: Output format preference (raw JSON, jq-filtered, variable assignment)

Steps

Step 1. Discover Schema

Determine available types, fields, queries, mutations.

For GitHub:

# List available query fields
gh api graphql -f query='{ __schema { queryType { fields { name description } } } }' \
  | jq '.data.__schema.queryType.fields[] | {name, description}'

# List available mutation fields
gh api graphql -f query='{ __schema { mutationType { fields { name description } } } }' \
  | jq '.data.__schema.mutationType.fields[] | {name, description}'

# Inspect a specific type
gh api graphql -f query='{
  __type(name: "Repository") {
    fields { name type { name kind ofType { name } } }
  }
}' | jq '.data.__type.fields[] | {name, type: .type.name // .type.ofType.name}'

For generic endpoints:

# Full introspection query via curl
curl -s -X POST https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query":"{ __schema { types { name kind fields { name } } } }"}' \
  | jq '.data.__schema.types[] | select(.kind == "OBJECT") | {name, fields: [.fields[].name]}'

Got: JSON output listing available types, fields, mutations. Schema response confirms endpoint reachable, auth token valid.

If fail:

• 401 Unauthorized — verify token. For GitHub, run gh auth status
• Cannot query field — endpoint may disable introspection. Consult docs instead
• Connection refused — verify endpoint URL, network access

Step 2. Identify Operation Type

Determine whether task needs query (read), mutation (write), or subscription (stream).

For GitHub-specific operations, consult GitHub GraphQL API docs.

# Quick check: does the mutation exist?
gh api graphql -f query='{ __schema { mutationType { fields { name } } } }' \
  | jq '.data.__schema.mutationType.fields[].name' | grep -i "discussion"

Got: Clear identification of whether query or mutation needed. Plus exact operation name (e.g., createDiscussion, repository).

If fail:

• Operation not found — search with broader terms or check API version
• Unclear whether query or mutation — action changes state? It's mutation

Step 3. Construct Operation

Build GraphQL query or mutation with fields, arguments, variables.

Query example — fetch repository's discussion categories:

gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      discussionCategories(first: 10) {
        nodes { id name }
      }
    }
  }
' -f owner="OWNER" -f repo="REPO" | jq '.data.repository.discussionCategories.nodes'

Mutation example — create GitHub Discussion:

gh api graphql -f query='
  mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
    createDiscussion(input: {
      repositoryId: $repoId,
      categoryId: $categoryId,
      title: $title,
      body: $body
    }) {
      discussion { url number }
    }
  }
' -f repoId="$REPO_ID" -f categoryId="$CAT_ID" \
  -f title="My Discussion" -f body="Discussion body here"

Key construction rules:

1. Always use variables ($var: Type!) instead of inline values for reusability
2. Request only fields needed to minimize response size
3. Use first: N with nodes for paginated connections
4. Add id to every object selection — needed for chaining

Got: Syntactically valid GraphQL operation with appropriate variables, field selections, pagination parameters.

If fail:

• Syntax errors — check bracket matching, trailing commas (GraphQL has no trailing commas)
• Type mismatch — verify variable types against schema (e.g., ID! vs String!)
• Missing required fields — add required input fields per schema

Step 4. Execute via CLI

Run operation. Capture response.

GitHub — using gh api graphql:

# Simple query
gh api graphql -f query='{ viewer { login } }'

# With variables
gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) { id name }
  }' \
  -f owner="octocat" -f repo="Hello-World"

# With jq post-processing
REPO_ID=$(gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) { id }
  }' \
  -f owner="OWNER" -f repo="REPO" \
  --jq '.data.repository.id')

Generic endpoint — using curl:

curl -s -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "$(jq -n \
    --arg query 'query { users { id name } }' \
    '{query: $query}'
  )"

Got: JSON response with data key containing requested fields, or errors array if operation failed.

If fail:

• errors array in response — read message. Common causes: missing permissions, invalid IDs, rate limits
• Empty data — query matched no records. Verify input values
• HTTP 403 — token lacks required scope. For GitHub, check gh auth status. Add scopes with gh auth refresh -s scope

Step 5. Parse Response

Extract data needed from JSON response.

# Extract a single value
gh api graphql -f query='{ viewer { login } }' --jq '.data.viewer.login'

# Extract from a list
gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      issues(first: 5, states: OPEN) {
        nodes { number title }
      }
    }
  }
' -f owner="OWNER" -f repo="REPO" \
  --jq '.data.repository.issues.nodes[] | "\(.number): \(.title)"'

# Assign to a variable for later use
CATEGORY_ID=$(gh api graphql -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      discussionCategories(first: 20) {
        nodes { id name }
      }
    }
  }
' -f owner="OWNER" -f repo="REPO" \
  --jq '.data.repository.discussionCategories.nodes[] | select(.name == "Show and Tell") | .id')

Got: Clean, extracted values ready for display or assignment to shell variables.

If fail:

• jq returns null — field path wrong. Pipe raw JSON to jq . first to inspect structure
• Multiple values when expecting one — add select() filter or | first
• Unicode issues — add -r to jq for raw string output

Step 6. Chain Operations

Use output from one operation as input to next.

# Step A: Get the repository ID
REPO_ID=$(gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) { id }
  }' \
  -f owner="$OWNER" -f repo="$REPO" \
  --jq '.data.repository.id')

# Step B: Get the discussion category ID
CAT_ID=$(gh api graphql \
  -f query='query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      discussionCategories(first: 20) {
        nodes { id name }
      }
    }
  }' \
  -f owner="$OWNER" -f repo="$REPO" \
  --jq '.data.repository.discussionCategories.nodes[]
    | select(.name == "Show and Tell") | .id')

# Step C: Create the discussion using both IDs
RESULT=$(gh api graphql \
  -f query='mutation($repoId: ID!, $catId: ID!, $title: String!, $body: String!) {
    createDiscussion(input: {
      repositoryId: $repoId,
      categoryId: $catId,
      title: $title,
      body: $body
    }) {
      discussion { url number }
    }
  }' \
  -f repoId="$REPO_ID" -f catId="$CAT_ID" \
  -f title="$TITLE" -f body="$BODY" \
  --jq '.data.createDiscussion.discussion')

echo "Created: $(echo "$RESULT" | jq -r '.url')"

Pattern: Always extract id fields in earlier queries so they pass as ID! variables to subsequent mutations.

Got: Multi-step workflow where each call succeeds. IDs flow correct between operations.

If fail:

• Variable empty — previous step failed silent. Add set -e. Check each intermediate value
• ID format wrong — GitHub node IDs are opaque strings (e.g., R_kgDO...). Never construct manually
• Rate limited — add sleep 1 between calls or batch queries using aliases

Checks

1. Introspection query returns schema data (Step 1 succeeds)
2. Constructed queries syntactically valid (no GraphQL parser errors)
3. Responses contain data keys without errors
4. Extracted values match expected types (IDs non-empty strings, counts numbers)
5. Chained operations complete end-to-end (mutation uses IDs from prior queries)

Pitfalls

See Also

• scaffold-nextjs-app — scaffold web apps consuming GraphQL APIs
• create-pull-request — GitHub workflow automation (REST-based counterpart)
• manage-git-branches — Git operations often paired with API automation
• serialize-data-formats — JSON parsing patterns used in response handling