Authentication

Authentication

gqlcli supports authentication in both HTTP mode (the standalone CLI) and inline mode (when embedded as a library).

This page focuses on HTTP mode and .gqlcli.json environments. For inline authentication with InlineCommandSet, see Library-Inline-Mode.

HTTP Environments and Headers

The primary way to configure auth for the CLI is via .gqlcli.json environments. Each environment can specify a url and arbitrary HTTP headers:

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

At runtime you select an environment with --env:

# Use the default env (from .gqlcli.json)
gqlcli queries

# Explicitly target prod
gqlcli queries --env prod

For more on .gqlcli.json, see Configuration.

gqlcli login — HTTP Login Flow

The login command runs a GraphQL mutation against an environment, extracts a token from the response, and writes it into that environment's headers in .gqlcli.json.

One-Time Setup

You provide:

• A login mutation (as a GraphQL string)
• A variables JSON object (e.g. email/password)
• A token path describing where the token lives in the data payload

Example:

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 will:

1. POST the Login mutation to the prod environment URL
2. Parse the response and walk data.login.token
3. Store the token in .gqlcli.json under environments.prod.headers.Authorization as Bearer <token>
4. Remember the mutation + token path under environments.prod.login

Afterwards, any gqlcli command that uses --env prod will automatically send the Authorization header.

Subsequent Logins

Once environments.<name>.login is populated, you can omit --mutation and --token-path and just pass new variables:

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

gqlcli will reuse the saved mutation and token path.

Custom Header Name or Prefix

By default, login writes Authorization: Bearer <token>. You can customize this:

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 \
  --header X-Auth-Token \
  --prefix ''

This writes X-Auth-Token: <token> instead of Bearer auth.

gqlcli logout — Clear an Environment Token

To remove a saved auth header from an environment:

gqlcli logout --env prod

This deletes the header (by default Authorization) from environments.prod.headers. You can also specify a different header:

gqlcli logout --env prod --header X-Auth-Token

If the header is not present, logout is a no-op.

Environment Variables and --url

Auth configured via .gqlcli.json headers works alongside URL selection:

• --env selects an environment: URL + headers
• GRAPHQL_URL or --url can override just the URL

Precedence for URL selection (highest wins):

1. --url
2. GRAPHQL_URL env var
3. .gqlcli.json environment URL
4. Built-in default (http://localhost:8080/graphql)

Headers always come from .gqlcli.json for the selected environment, regardless of how the URL is chosen.

Inline Mode Authentication (Library)

When embedding gqlcli via InlineCommandSet, you can:

• Use TokenStore to persist a JWT at ~/.{appName}/token
• Add login, logout, and whoami commands via WithLogin
• Use WithContextEnricher on the InlineExecutor to inject the token into the GraphQL context

See Library-Inline-Mode for a complete example of wiring inline auth.