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"
      }
    }
  }
}

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

Debug Mode

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.