Command Reference

Command Reference

Complete flag reference for all gqlcli commands.

Common Flags

Many commands share a common set of flags:

-u, --url VALUE       GraphQL endpoint URL
                      Default: http://localhost:8080/graphql
                      Env: GRAPHQL_URL

--env VALUE           Named environment from .gqlcli.json
                      Example: --env prod

-H, --header KEY=VALUE
                      Per-request HTTP header; repeatable. Overrides same-name env headers.

--timeout SECONDS     Request timeout in seconds (default: 30)
--retry N             Retry transient failures (connection errors, 408, 429, 5xx)
--retry-delay DURATION
                      Delay between retries, e.g. 500ms or 2s
--fail-on-graphql-errors
                      Exit non-zero when GraphQL response.errors is present
--insecure            Skip TLS certificate verification for self-signed/internal endpoints

--include-headers, -i Include response status line and headers before the body
--dump-headers FILE   Write response status line and headers to a file
--metadata SELECTOR   Print selected metadata after the response; repeatable.
                      Selectors: status, status-code, headers, header:Name

-f, --format VALUE    Output format
                      Options: json, json-pretty, table, compact, toon, llm
                      Default: toon

-p, --pretty          Pretty-print JSON output (equivalent to -f json-pretty when supported)

-h, --help            Show help for the command

HTTP-backed commands support the transport flags above unless noted. Metadata flags apply to single-response operation commands (query and mutation) where response metadata is available.

---

query

Execute a GraphQL query.

gqlcli query [flags] [QUERY]

Flag	Short	Description
--query STRING	-q	GraphQL query string
--query-file PATH		Read query from file
--variables JSON	-v	Query variables as JSON
--variables-file PATH		Read variables from file
--operation STRING	-o	Named operation to execute (for multi-op files)
--op NAME		Load saved operation from .gqlcli.json; merges its defaults with --variables
--format FORMAT	-f	Output format
--output FILE		Write response to file
--header KEY=VALUE	-H	Per-request HTTP header; repeatable
--include-headers	-i	Include response status line and headers before body
--dump-headers FILE		Write response status line and headers to file
--metadata SELECTOR		Print selected metadata (status, status-code, headers, header:Name); repeatable
--timeout SECONDS		Request timeout
--retry N		Retry transient failures
--retry-delay DURATION		Delay between retries
--fail-on-graphql-errors		Exit non-zero when response.errors is present
--insecure		Skip TLS certificate verification
--url URL	-u	GraphQL endpoint
--env VALUE		Environment from .gqlcli.json
--debug	-d	Enable HTTP debug logging

Examples:

gqlcli query -q "{ users { id name } }"
gqlcli query --query-file ./ops.graphql --operation GetUser
gqlcli query -q "query GetUser(\$id: ID!) { user(id: \$id) { id } }" -v '{"id":"1"}'
gqlcli query --op get-user
gqlcli query --op get-user -v '{"id":"456"}'

---

mutation

Execute a GraphQL mutation.

gqlcli mutation [flags]

Flag	Short	Description
--mutation STRING	-m	GraphQL mutation string
--mutation-file PATH		Read mutation from file
--input JSON		Input object, auto-wrapped as {"input":{...}}
--variables JSON	-v	Variables as JSON
--variables-file PATH		Read variables from file
--operation STRING	-o	Named operation
--op NAME		Load saved operation from .gqlcli.json; merges its defaults with --variables
--format FORMAT	-f	Output format
--pretty	-p	Pretty-print JSON output (shorthand for -f json-pretty)
--output FILE		Write response to file
--header KEY=VALUE	-H	Per-request HTTP header; repeatable
--include-headers	-i	Include response status line and headers before body
--dump-headers FILE		Write response status line and headers to file
--metadata SELECTOR		Print selected metadata (status, status-code, headers, header:Name); repeatable
--timeout SECONDS		Request timeout
--retry N		Retry transient failures
--retry-delay DURATION		Delay between retries
--fail-on-graphql-errors		Exit non-zero when response.errors is present
--insecure		Skip TLS certificate verification
--url URL	-u	GraphQL endpoint
--env VALUE		Environment from .gqlcli.json
--debug	-d	Enable HTTP debug logging

Examples:

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

---

subscribe

Execute a GraphQL subscription and stream events as NDJSON. Uses the graphql-transport-ws WebSocket protocol; HTTP(S) endpoint URLs are mapped to WS(S).

gqlcli subscribe [flags] [SUBSCRIPTION]

Flag	Short	Description
--subscription STRING	-s	GraphQL subscription string
--subscription-file PATH		Read subscription from file
--variables JSON	-v	Variables as JSON
--variables-file PATH		Read variables from file
--operation STRING	-o	Named operation to execute from a multi-operation document
--op NAME		Load saved subscription operation from .gqlcli.json
--header KEY=VALUE	-H	Per-request WebSocket/HTTP header; repeatable
--timeout SECONDS		Connection/read timeout
--insecure		Skip TLS certificate verification for wss:// endpoints
--url URL	-u	GraphQL endpoint; http:// → ws://, https:// → wss://
--env VALUE		Environment from .gqlcli.json
--debug	-d	Enable debug logging

Examples:

gqlcli subscribe 'subscription { messageAdded { id text } }'
gqlcli subscribe --subscription-file ./messages.graphql --variables-file vars.json
gqlcli subscribe \
  --subscription 'subscription Watch($room:ID!){ messageAdded(room:$room){ id text } }' \
  --variables '{"room":"general"}' \
  --operation Watch

Output is one JSON object per line: next, error, and complete. Press Ctrl-C to cancel cleanly.

---

batch

Execute multiple operations in a single request. Reads NDJSON (one JSON object per line) from stdin or a file.

gqlcli batch [flags]

Flag	Description
--ndjson	Use NDJSON transport — one operation per line (default)
--array	Use JSON array batch transport
--file PATH	Read operations from file instead of stdin
--jq EXPR	Apply jq expression to each response (client-side)
--header KEY=VALUE	Per-request HTTP header; repeatable
--timeout SECONDS	Request timeout
--retry N	Retry transient failures
--retry-delay DURATION	Delay between retries
--fail-on-graphql-errors	Exit non-zero when any response.errors is present
--insecure	Skip TLS certificate verification
--url URL	GraphQL endpoint
--env VALUE	Environment from .gqlcli.json
--debug	Enable HTTP debug logging

Each NDJSON line may include an optional "jq" field for per-operation server-side filtering.

Examples:

printf '{"query":"{ users { id } }"}\n{"query":"{ posts { id } }"}\n' | gqlcli batch
gqlcli batch --file ops.ndjson --jq '.data'

See Batch-Operations for detailed examples.

---

queries

Discover Query fields available on the connected schema.

gqlcli queries [flags]

Flag	Short	Description
--desc		Include field descriptions
--args		Include field arguments with types
--filter PATTERN		Filter by name (case-insensitive substring)
--format FORMAT	-f	Output format (default: toon)
--url URL	-u	GraphQL endpoint
--header KEY=VALUE	-H	Per-request HTTP header; repeatable
--timeout SECONDS		Request timeout
--retry N		Retry transient failures
--retry-delay DURATION		Delay between retries
--fail-on-graphql-errors		Exit non-zero when response.errors is present
--insecure		Skip TLS certificate verification
--env VALUE		Environment from .gqlcli.json
--debug	-d	Enable debug logging

Examples:

gqlcli queries
gqlcli queries --desc --args
gqlcli queries --filter user -f table

---

mutations

Discover Mutation fields available on the connected schema.

gqlcli mutations [flags]

Flag	Short	Description
--desc		Include field descriptions
--args		Include field arguments with types
--filter PATTERN		Filter by name (case-insensitive substring)
--format FORMAT	-f	Output format (default: toon)
--url URL	-u	GraphQL endpoint
--header KEY=VALUE	-H	Per-request HTTP header; repeatable
--timeout SECONDS		Request timeout
--retry N		Retry transient failures
--retry-delay DURATION		Delay between retries
--fail-on-graphql-errors		Exit non-zero when response.errors is present
--insecure		Skip TLS certificate verification
--env VALUE		Environment from .gqlcli.json
--debug	-d	Enable debug logging

Examples:

gqlcli mutations
gqlcli mutations --filter create --args

---

describe

Print the SDL definition of a named type.

gqlcli describe TYPE_NAME [flags]

Flag	Short	Description
TYPE_NAME		Name of the type to describe (required)
--args	-a	Expand field argument signatures
--descriptions		Include field and type descriptions
--url URL	-u	GraphQL endpoint
--header KEY=VALUE	-H	Per-request HTTP header; repeatable
--timeout SECONDS		Request timeout
--retry N		Retry transient failures
--retry-delay DURATION		Delay between retries
--fail-on-graphql-errors		Exit non-zero when response.errors is present
--insecure		Skip TLS certificate verification
--env VALUE		Environment from .gqlcli.json
--debug	-d	Enable debug logging

Examples:

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

---

types

List all types in the schema.

gqlcli types [flags]

Flag	Short	Description
--filter PATTERN		Filter by name (substring match)
--kind KIND		Filter by kind: OBJECT, ENUM, INPUT_OBJECT, SCALAR, INTERFACE, UNION
--format FORMAT	-f	Output format (default: toon)
--url URL	-u	GraphQL endpoint
--header KEY=VALUE	-H	Per-request HTTP header; repeatable
--timeout SECONDS		Request timeout
--retry N		Retry transient failures
--retry-delay DURATION		Delay between retries
--fail-on-graphql-errors		Exit non-zero when response.errors is present
--insecure		Skip TLS certificate verification
--env VALUE		Environment from .gqlcli.json
--debug	-d	Enable debug logging

Examples:

gqlcli types
gqlcli types --kind OBJECT
gqlcli types --filter User -f json-pretty
gqlcli types --kind INPUT_OBJECT --output inputs.json

---

op

Manage named GraphQL operations saved in .gqlcli.json. Use --op <name> on query, mutation, or subscribe to execute a saved operation without repeating the document.

op save

gqlcli op save --name NAME [--query STRING | --mutation STRING] [--defaults JSON]

Flag	Short	Description
--name NAME	-n	Operation name (required)
--query STRING		GraphQL query string (sets type=query)
--mutation STRING		GraphQL mutation string (sets type=mutation)
--defaults JSON		Default variables as JSON; merged with --variables at execution time

Exactly one of --query or --mutation must be provided. Subscription operations can be stored manually in .gqlcli.json with "type": "subscription" for gqlcli subscribe --op NAME.

op list

gqlcli op list

Lists all saved operations with name, type, and a truncated body.

op show

gqlcli op show --name NAME

Prints full details of a saved operation: type, full query/mutation string, and defaults.

op delete

gqlcli op delete --name NAME

Removes the named operation from .gqlcli.json.

Examples:

# Save
gqlcli op save --name get-user \
  --query 'query GetUser($id: ID!) { user(id: $id) { id name } }' \
  --defaults '{"id":"default-123"}'
gqlcli op save --name create-user \
  --mutation 'mutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { id } }'

# CRUD
gqlcli op list
gqlcli op show --name get-user
gqlcli op delete --name get-user

# Execute
gqlcli query --op get-user
gqlcli query --op get-user --variables '{"id":"456"}'   # overrides default
gqlcli mutation --op create-user --input '{"name":"Alice"}'

---

URL Resolution Priority

When multiple URL sources are provided, this is the priority order (lowest → highest):

1. Hardcoded default (http://localhost:8080/graphql)
2. Named environment in .gqlcli.json (resolved by --env)
3. GRAPHQL_URL environment variable
4. --url flag

Header Precedence

Headers from .gqlcli.json are loaded from the selected environment. Repeatable --header/-H KEY=VALUE flags are merged on top and override same-name environment headers.