Configuration

Configuration

Environment Variable

The simplest way to set a custom endpoint:

export GRAPHQL_URL=https://api.example.com/graphql
gqlcli queries

.gqlcli.json — Per-Directory Config

Create .gqlcli.json in your project directory to define named environments. This lets you switch between local, staging, prod, or any other environment without changing flags.

Schema

{
  "default": "local",
  "environments": {
    "ENV_NAME": {
      "url": "https://...",
      "headers": {
        "Header-Name": "value"
      }
    }
  },
  "operations": {
    "OPERATION_NAME": {
      "type": "query",
      "query": "{ ... }",
      "defaults": { "key": "value" }
    }
  }
}

The operations map is optional. See Command-Reference#op for managing named operations. Query and mutation operations can be saved with gqlcli op save; subscription operations can be stored manually with "type": "subscription" and "query" or "subscription" content for use with gqlcli subscribe --op NAME.

Full Example

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

Switching Environments

# Uses the default environment (local)
gqlcli queries

# Explicitly select an environment
gqlcli queries --env prod
gqlcli query --query "{ users { id } }" --env staging

# Override URL on top of a named env
gqlcli queries --env staging --url http://other-host/graphql

Multiple .gqlcli.json Files

Each directory can have its own .gqlcli.json. gqlcli looks for the config file only in the current working directory; it does not search parent directories or $HOME.

This means you typically choose one of:

• A single .gqlcli.json per project (recommended)
• A temporary ad‑hoc config in the directory where you are running gqlcli

Authentication

Authentication is done via HTTP headers in .gqlcli.json. Bearer token is the most common:

{
  "environments": {
    "prod": {
      "url": "https://api.example.com/graphql",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Any header can be added — API keys, custom auth schemes, tenant IDs:

{
  "headers": {
    "X-API-Key": "your-api-key",
    "X-Tenant-ID": "acme-corp"
  }
}

URL Resolution Priority

When multiple URL sources are provided, higher items win:

Priority	Source
4 (highest)	--url flag
3	GRAPHQL_URL environment variable
2	Named environment in .gqlcli.json
1 (lowest)	Default http://localhost:8080/graphql

HTTP Controls and Debug Mode

In addition to URL and headers, HTTP-backed commands accept transport controls:

gqlcli query '{ health }' --timeout 10 --retry 3 --retry-delay 500ms
gqlcli query --query-file ./ci-check.graphql --fail-on-graphql-errors
gqlcli queries --url https://localhost:8443/graphql --insecure

• --timeout SECONDS bounds the request.
• --retry N retries transient connection failures, HTTP 408/429, and 5xx responses.
• --retry-delay DURATION sets the delay between retries, for example 500ms or 2s.
• --fail-on-graphql-errors exits non-zero when the response has an errors array.
• --insecure skips TLS certificate verification for self-signed/internal endpoints.

Log all HTTP requests and responses:

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

This prints request headers, body, response status, and response body — useful for diagnosing auth or connectivity issues.