Skip to content

FAQ

Jump to bottom
Wallace Ricardo edited this page May 29, 2026 · 2 revisions

FAQ

Answers to common questions about gqlcli.

Installation

Q: What is the fastest way to install gqlcli?

One-liner that auto-detects OS and architecture:

curl -fsSL https://raw.githubusercontent.com/wricardo/gqlcli/main/install.sh | bash

Installs to /usr/local/bin/gqlcli. Override with INSTALL_DIR=~/.local/bin. See Installation for all options.

Q: Can I install without downloading a binary?

Yes, via Go:

go install github.com/wricardo/gqlcli/cmd/gqlcli@latest

Configuration

Q: What is the default GraphQL endpoint?

http://localhost:8080/graphql. Override in priority order (highest wins):

  1. --url flag
  2. GRAPHQL_URL env var
  3. .gqlcli.json environment URL
  4. Built-in default

See Configuration for the full precedence rules.

Q: How do I set up multiple environments (local, staging, prod)?

Create .gqlcli.json in your project directory:

{
  "default": "local",
  "environments": {
    "local": {
      "url": "http://localhost:8080/graphql",
      "headers": { "Authorization": "Bearer dev-token" }
    },
    "prod": {
      "url": "https://api.example.com/graphql",
      "headers": { "Authorization": "Bearer prod-token" }
    }
  }
}

Then use --env to switch:

gqlcli queries --env prod

See Configuration.

Q: How do I add custom HTTP headers?

Add them to .gqlcli.json under the environment's headers object. There is no -H flag — headers are config-only. See Configuration.

Q: Can I use gqlcli with Bearer token auth?

Yes. Either set the header directly in .gqlcli.json:

"headers": { "Authorization": "Bearer <token>" }

Or use the login command to fetch and store a token automatically:

gqlcli login --env prod \
  --mutation 'mutation Login($email: String!, $password: String!) { login(email: $email, password: $password) { token } }' \
  --variables '{"email":"you@example.com","password":"secret"}' \
  --token-path login.token

This writes Authorization: Bearer <token> into .gqlcli.json for the environment. See Authentication.

Q: How do I clear a saved auth token?

gqlcli logout --env prod

See Authentication.

Queries & Mutations

Q: How do I discover what queries are available?

gqlcli queries           # list all
gqlcli queries --desc    # with descriptions
gqlcli queries --args    # with argument types
gqlcli queries --filter user   # filter by name

See CLI-Usage.

Q: How do I pass variables to a query?

Inline JSON:

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

From file:

gqlcli query --query-file ./queries/getUser.graphql --variables-file ./vars.json

See CLI-Usage.

Q: What is --input vs --variables on the mutation command?

--input auto-wraps the JSON as {"input": {...}}, matching the common (input: SomeInput!) pattern. --variables passes the raw variables map directly — use it when your mutation takes multiple top-level arguments.

See Command-Reference.

Q: How do I read a query from a file?

gqlcli query --query-file ./queries/getUser.graphql
gqlcli mutation --mutation-file ./mutations/createUser.graphql

Q: How do I run a named operation from a file with multiple operations?

gqlcli query --query-file ./operations.graphql --operation GetUser

See Command-Reference.

Output Formats

Q: What output formats are available?

Format Description
toon Token-optimized (default, ~40-60% smaller)
json Compact JSON
json-pretty Indented JSON
table Aligned columns for terminal viewing
compact Single-line JSON, strips nulls
llm Markdown-friendly for LLM consumption

Switch with -f:

gqlcli queries -f json-pretty

See Output-Formats.

Q: What is TOON format?

Token-Optimized Object Notation — a compact encoding that preserves all data but uses significantly fewer tokens than JSON. It is the default format because gqlcli is commonly used with LLM agents. Use -f json-pretty for standard JSON. See Output-Formats.

Q: How do I save output to a file?

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

Schema Exploration

Q: How do I inspect a specific type?

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

See CLI-Usage.

Q: How do I list all types?

gqlcli types
gqlcli types --filter User
gqlcli types --kind INPUT_OBJECT

See CLI-Usage.

Q: What are schema hints?

When a query fails validation, gqlcli enriches the error with a compact SDL definition of the relevant type so you can see what fields actually exist — without a separate describe call. Works in both HTTP and inline modes. See Error-Handling.

Named Operations

Q: How do I save a query so I don't have to repeat it every time?

Use op save:

gqlcli op save --name get-user \
  --query 'query GetUser($id: ID!) { user(id: $id) { id name email } }' \
  --defaults '{"id":"default-123"}'

Then execute by name:

gqlcli query --op get-user
gqlcli query --op get-user --variables '{"id":"456"}'   # overrides default

Operations are stored in .gqlcli.json under "operations". See Command-Reference.

Q: Can I save mutations too?

Yes:

gqlcli op save --name create-user \
  --mutation 'mutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { id } }'

gqlcli mutation --op create-user --input '{"name":"Alice"}'

Q: How do I manage saved operations?

gqlcli op list                    # all saved ops
gqlcli op show --name get-user   # full details + defaults
gqlcli op delete --name get-user # remove

Q: What happens if I use --op with a wrong command type?

Error. Using a saved mutation with query (or vice versa) returns:

operation "create-user" is a mutation, not a query; use the mutation command

Batch Operations

Q: What is the batch command for?

Running multiple GraphQL operations in a single HTTP request — useful for pipelines, bulk mutations, and AI agent workflows. See Batch-Operations.

Q: What is the difference between --ndjson and --array in batch mode?

Transport Format When to use
NDJSON (default) One JSON object per line, application/x-ndjson Streaming, large payloads
JSON array (--array) Single JSON array, application/json Standard batch-compatible servers

See Batch-Operations.

Q: How do I use server-side jq filtering in batch?

Add a "jq" field to each operation line:

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

See Batch-Operations.

Q: How do I apply jq to all batch responses on the client side?

printf '{"query":"{ users { id name } }"}\n' \
  | gqlcli batch --jq '.data.users[].name'

See Batch-Operations.

Q: Can I pipe query results into batch mutations?

Yes — a common pattern:

gqlcli query -q '{ users { id status } }' -f json \
  | jq -c '.data.users[] | select(.status == "inactive") | {query: "mutation($id:ID!){archive(id:$id){ok}}", variables: {id: .id}}' \
  | gqlcli batch

See Batch-Operations.

Library Usage

Q: What is the difference between HTTP mode and inline mode?

HTTP Mode Inline Mode
Execution Calls external GraphQL server over HTTP Runs operations in-process via gqlgen
Use case API client, testing, scripting Embedding a GraphQL-backed CLI in your Go app
Auth Headers in .gqlcli.json TokenStore + WithContextEnricher
Extra commands — login, logout, whoami

See Library-HTTP-Mode and Library-Inline-Mode.

Q: I get "anonymous" responses when hitting prod — what is wrong?

The bearer token in .gqlcli.json is expired. Refresh it:

gqlcli login --env prod --variables '{"email":"you@example.com","password":"secret"}'

Requires the login mutation and token-path to have been set up at least once before. See Authentication.

Q: How do I enable debug logging to see raw HTTP requests?

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

Errors

Q: I see "GraphQL validation failed" — how do I fix it?

Check the schema hint included in the error output. It shows the SDL of the relevant type with the actual field names. If there is no hint, run gqlcli describe <TypeName> to inspect the type manually. See Error-Handling.

Miscellaneous

Q: Where is the --env flag relative to the subcommand?

--env is a subcommand flag, not a global flag:

# correct
gqlcli query --env prod '...'

# wrong
gqlcli --env prod query '...'

See Command-Reference.

Q: Does gqlcli support Windows?

Yes. Download gqlcli_windows_amd64.zip from the Releases page and add gqlcli.exe to your PATH. See Installation.

Q: Where should I report bugs or request features?

GitHub Issues.

Clone this wiki locally