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

-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

See each command section below for which of these flags it supports.

---

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)
--format FORMAT	-f	Output format
--output FILE		Write response to file
--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"}'

---

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
--format FORMAT	-f	Output format
--pretty	-p	Pretty-print JSON output (shorthand for -f json-pretty)
--output FILE		Write response to file
--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"}'

---

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)
--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
--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
--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
--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
--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

---

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