CLI Usage

CLI Usage

gqlcli is a command-line client for any GraphQL API. It connects over HTTP/WebSocket and lets you discover operations, execute queries and mutations, stream subscriptions, and explore the schema.

Connecting to a Server

By default, gqlcli connects to http://localhost:8080/graphql.

# Use the default URL
gqlcli queries

# Override URL with a flag
gqlcli queries --url https://api.example.com/graphql

# Override URL with an env var
export GRAPHQL_URL=https://api.example.com/graphql
gqlcli queries

For managing multiple environments, see Configuration.

Per-Request Headers and HTTP Controls

Most HTTP-backed commands support curl-style transport flags:

# One-off headers; CLI headers override headers from .gqlcli.json
gqlcli query '{ viewer { id } }' --env prod \
  -H 'Authorization=Bearer temporary-token' \
  -H 'X-Tenant=acme'

# Timeout and retry controls for scripts/CI
gqlcli query '{ health }' --timeout 10 --retry 3 --retry-delay 500ms

# Fail non-zero if the GraphQL response contains an errors array
gqlcli query --query-file ./checks.graphql --fail-on-graphql-errors

# Internal/self-signed TLS endpoints
gqlcli queries --url https://localhost:8443/graphql --insecure

To inspect response metadata without changing the GraphQL request:

gqlcli query '{ viewer { id } }' --include-headers
gqlcli query '{ viewer { id } }' --dump-headers headers.txt -f json
gqlcli query '{ viewer { id } }' --metadata status-code --metadata header:X-Request-Id

Discovering Operations

Before running queries, use the discovery commands to understand what the schema offers:

# List all Query fields
gqlcli queries

# List with field descriptions
gqlcli queries --desc

# List with argument types
gqlcli queries --args

# Filter by name (case-insensitive substring match)
gqlcli queries --filter user
gqlcli mutations --filter campaign

# Expand referenced non-scalar arg/return types too (one command instead of a
# queries/mutations + describe round-trip)
gqlcli queries --filter user --args --depth 1
gqlcli mutations --filter campaign --args --depth 1

These commands show the schema's root Query and Mutation fields without needing to know the schema upfront. --depth follows only the filtered fields' referenced types, same recursion rules as describe --depth (0 = none, N = N levels deep).

Executing Queries

Inline Query

gqlcli query --query "{ users { id name email } }"

# Shorthand flag
gqlcli query -q "{ users { id name } }"

Query from File

gqlcli query --query-file ./queries/getUser.graphql

With Variables

gqlcli query \
  --query "query GetUser(\$id: ID!) { user(id: \$id) { id name } }" \
  --variables '{"id":"123"}'

# Variables from file
gqlcli query \
  --query-file ./queries/getUser.graphql \
  --variables-file ./variables.json

Named Operations

When a file contains multiple operations:

gqlcli query \
  --query-file ./queries/operations.graphql \
  --operation "GetUser"

Save Output to File

gqlcli query --query "{ users { id } }" --output results.json

Built-in jq Filtering

--jq applies a jq expression (no external jq binary needed) to the full response envelope, so start expressions from .data. It only runs when the operation succeeds — on a GraphQL or transport error, the raw error output is shown untouched by jq, so a jq expression written for the success shape never hides a failure.

gqlcli query "{ users { id name } }" --jq '.data.users[].name'
gqlcli query "{ users { id } }" --jq '.data.users | length'

Executing Mutations

Basic Mutation

gqlcli mutation \
  --mutation "mutation { createUser(name: \"Alice\") { id } }"

With Auto-Wrapped Input

The --input flag automatically wraps its value as {"input": {...}}:

gqlcli mutation \
  --mutation "mutation CreateUser(\$input: CreateUserInput!) { createUser(input: \$input) { id } }" \
  --input '{"name":"Alice","email":"alice@example.com"}'

With Explicit Variables

gqlcli mutation \
  --mutation-file ./mutations/createUser.graphql \
  --variables '{"input":{"name":"Alice"}}'

Built-in jq Filtering

Same --jq support as query — skipped on error so the raw error stays visible:

gqlcli mutation --mutation-file ./mutations/createUser.graphql \
  --input '{"name":"Alice"}' --jq '.data.createUser.id'

Subscriptions

Use subscribe to stream GraphQL subscription events over the graphql-transport-ws WebSocket protocol. See Subscriptions for the full guide.

# Inline subscription
gqlcli subscribe 'subscription { messageAdded { id text } }'

# Subscription from file with variables
gqlcli subscribe \
  --subscription-file ./subscriptions/messages.graphql \
  --variables-file ./variables.json

# Named operation in a multi-operation document
gqlcli subscribe \
  --subscription 'subscription WatchRoom($room: ID!) { messageAdded(room: $room) { id text } }' \
  --variables '{"room":"general"}' \
  --operation WatchRoom

Output is NDJSON: each line is a next, error, or complete envelope. Press Ctrl-C to cancel cleanly.

Batch Operations

Execute multiple operations in a single request. See Batch-Operations for the full guide.

# Pipe NDJSON from stdin
printf '{"query":"{ users { id } }"}\n{"query":"{ posts { id } }"}\n' \
  | gqlcli batch

# With jq filtering per operation
printf '{"query":"{ users { id status } }","jq":".data.users[] | select(.status == \"active\")"}\n' \
  | gqlcli batch

# From a file
gqlcli batch --file operations.ndjson

Schema Exploration

List All Types

gqlcli types

# Filter by name
gqlcli types --filter User

# Filter by kind
gqlcli types --kind OBJECT
gqlcli types --kind ENUM
gqlcli types --kind INPUT_OBJECT
gqlcli types --kind INTERFACE
gqlcli types --kind UNION
gqlcli types --kind SCALAR

Describe a Type

Prints the SDL definition of a type:

gqlcli describe User
gqlcli describe CreateUserInput --args
gqlcli describe User --args --descriptions

Output Formats

Most commands that print GraphQL results (for example query, mutation, queries, mutations, and types) support the -f / --format flag. See Output-Formats for details.

gqlcli queries -f json-pretty    # Pretty JSON
gqlcli queries -f table          # Aligned columns
gqlcli queries -f toon           # Token-optimized (default)
gqlcli queries -f llm            # Markdown for LLMs
gqlcli queries -f compact        # Minimal JSON

Debug Mode

Print request and response details for troubleshooting:

gqlcli query --query "{ users { id } }" --debug
gqlcli mutation --mutation "..." --debug

Use Cases

API Development & Testing

# Discover what's available
gqlcli queries
gqlcli mutations

# Test a mutation
gqlcli mutation \
  --mutation-file ./test/mutations/createUser.graphql \
  --variables-file ./test/variables.json

CI/CD Schema Drift Detection

# Capture types and compare
gqlcli types --format json > current-types.json
git diff previous-types.json current-types.json

AI / LLM Integration

# Get schema for LLM context
gqlcli queries --desc --format toon
gqlcli mutations --desc --args --format toon

# Inspect a type before writing a query
gqlcli describe User --args
gqlcli types --kind INPUT_OBJECT

For complete flag details, see Command-Reference.