Subscriptions

Subscriptions

gqlcli subscribe streams GraphQL subscription events from servers that support the standard GraphQL over WebSocket protocol (graphql-transport-ws).

HTTP and HTTPS endpoint URLs are automatically mapped to WebSocket URLs:

Endpoint URL	Subscription URL
http://api.example.com/graphql	ws://api.example.com/graphql
https://api.example.com/graphql	wss://api.example.com/graphql

Explicit ws:// and wss:// URLs are also accepted.

Basic Usage

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

Each event is printed as one JSON object per line (NDJSON):

{"type":"next","payload":{"data":{"messageAdded":{"id":"1","text":"hello"}}}}
{"type":"error","payload":[{"message":"..."}]}
{"type":"complete"}

Subscription Sources

Inline Subscription

gqlcli subscribe \
  --subscription 'subscription WatchRoom($room: ID!) { messageAdded(room: $room) { id text } }' \
  --variables '{"room":"general"}'

From a File

gqlcli subscribe \
  --subscription-file ./subscriptions/messages.graphql \
  --variables-file ./variables.json

Named Operation in a Multi-Operation Document

gqlcli subscribe \
  --subscription-file ./subscriptions/all.graphql \
  --operation WatchRoom \
  --variables '{"room":"general"}'

Saved Operation

subscribe supports --op NAME for saved operations in .gqlcli.json. Query and mutation operations can be saved with gqlcli op save; subscription operations can be stored manually:

{
  "operations": {
    "watch-room": {
      "type": "subscription",
      "query": "subscription WatchRoom($room: ID!) { messageAdded(room: $room) { id text } }",
      "defaults": { "room": "general" }
    }
  }
}

Run it with:

gqlcli subscribe --op watch-room
gqlcli subscribe --op watch-room --variables '{"room":"random"}'

Explicit --variables override defaults from the saved operation.

Headers and Authentication

Subscription connections send headers from the selected .gqlcli.json environment. Use --header/-H for one-off overrides:

gqlcli subscribe 'subscription { events { id } }' \
  --env prod \
  -H 'Authorization=Bearer temporary-token' \
  -H 'X-Tenant=acme'

CLI headers override environment headers with the same name.

Timeouts, TLS, and Cancellation

# Bound connection/read time
gqlcli subscribe 'subscription { events { id } }' --timeout 60

# Self-signed/internal TLS endpoint
gqlcli subscribe --url https://localhost:8443/graphql --insecure 'subscription { events { id } }'

Press Ctrl-C to cancel. gqlcli sends a WebSocket complete message and closes the connection cleanly.

Transport Coverage

Currently supported:

• graphql-transport-ws WebSocket protocol

Not implemented yet:

• Server-Sent Events (SSE)
• Legacy subscriptions-transport-ws

If your server only supports SSE, add an explicit future transport mode such as --transport sse rather than relying on automatic detection.