Gazania CLI

The CLI provides commands for schema type generation and static query extraction.

Installation

The CLI is included with the gazania package:

npm install gazania

Usage

gazania <command> [options]

Commands

generate

Generate TypeScript type definitions from a GraphQL schema.

gazania generate [options]

Options

Option	Alias	Type	Description
--schema <source>	-s	string	Schema source: URL or file path (overrides config)
--output <path>	-o	string	Output file path (overrides config)
--config <path>	-c	string	Path to config file
--silent		boolean	Suppress output
--help	-h		Show help

Examples

From a GraphQL URL:

npx gazania generate --schema https://api.example.com/graphql --output src/schema.ts

From a local GraphQL file:

npx gazania generate --schema schema.graphql --output src/schema.ts

From an introspection JSON file:

npx gazania generate --schema introspection.json --output src/schema.ts

Using a config file:

npx gazania generate

Using a specific config file:

npx gazania generate --config gazania.config.a.ts

Override config values:

npx gazania generate --schema https://other-api.com/graphql
npx gazania generate --output src/other-schema.ts

Global Options

Option	Alias	Description
--help	-h	Show help
--version	-v	Show version

---

extract

Extract all Gazania GraphQL operations and produce a persisted query manifest.

gazania extract [options]

The command scans your source files, finds all Gazania builder chains that produce a DocumentNode using type-aware detection, evaluates them at analysis time, and outputs a JSON manifest with each operation's body and SHA-256 hash. Vue (.vue) and Svelte (.svelte) single-file components are supported — each <script> block is extracted and processed independently.

Gazania uses type-aware detection to identify builder identifiers by type, supporting re-exported, aliased, and factory-created builders. The TypeScript config defaults to tsconfig.json in the config file's directory (or current directory).

Options

Option	Alias	Type	Default	Description
--dir <path>	-d	string	src	Directory to scan
--output <path>	-o	string	stdout	Output file path. Use - for explicit stdout
--include <glob>		string	**/*.{ts,tsx,js,jsx,vue,svelte}	File pattern to include
--algorithm <alg>		string	sha256	Hash algorithm
--config <path>	-c	string		Path to config file
--tsconfig <path>		string	tsconfig.json	Path to TypeScript config file (default: tsconfig.json)
--silent		boolean	false	Suppress progress output (errors still shown)
--ignore-unresolved		boolean	false	Skip unresolved reference errors
--ignore-analysis		boolean	false	Skip analysis failure errors
--ignore-circular		boolean	false	Skip circular reference errors
--ignore-all		boolean	false	Skip all extraction errors
--no-emit		boolean	false	Suppress manifest output (useful for validation)
--schema <path>	-s	string		Schema for query validation (file path, URL, or SDL string)
--strict		boolean	false	Treat validation warnings (deprecated fields) as errors
--help	-h			Show help

Examples

Basic usage (stdout):

npx gazania extract

Write to a file:

npx gazania extract --output dist/persisted-queries.json

Scan a custom directory:

npx gazania extract --dir app

Explicit stdout:

npx gazania extract --output -

Use SHA-512 hashes:

npx gazania extract --algorithm sha512

Ignore unresolved references:

npx gazania extract --ignore-unresolved

Ignore all extraction errors:

npx gazania extract --ignore-all

Validation only (no output):

npx gazania extract --no-emit

Validate queries against a schema:

npx gazania extract --schema schema.graphql --no-emit

Strict validation (deprecated fields cause errors):

npx gazania extract --schema schema.graphql --strict --no-emit

Manifest format

{
  "operations": {
    "FetchAnime": {
      "body": "query FetchAnime($id: Int = 127549) { ... }",
      "hash": "sha256:a1b2c3d4...",
      "schemaHash": "sha256:7e7fb6abcc9a9c11e539e685ca95af09cca0b764a4e50c9a0ecedc020115dd56",
      "locs": [
        {
          "file": "src/queries/FetchAnime.ts",
          "start": { "line": 10, "column": 1, "offset": 245 },
          "end": { "line": 15, "column": 2, "offset": 412 }
        }
      ]
    }
  },
  "fragments": {
    "UserFields": {
      "body": "fragment UserFields on User { id name email }",
      "hash": "sha256:e5f6a7b8...",
      "schemaHash": "sha256:7e7fb6abcc9a9c11e539e685ca95af09cca0b764a4e50c9a0ecedc020115dd56",
      "locs": [
        {
          "file": "src/fragments/UserFields.ts",
          "fragmentMode": "fragment",
          "start": { "line": 3, "column": 14, "offset": 88 },
          "end": { "line": 3, "column": 52, "offset": 126 }
        }
      ]
    }
  }
}

File paths in locs are relative to the current working directory. When the same operation or fragment is defined in multiple places with an identical body, all locations are collected in locs. See Persisted Queries for a full guide on using this manifest with your GraphQL server.

Schema sources

The --schema option accepts:

Source Type	Example
HTTP/HTTPS URL	https://api.example.com/graphql
Local .graphql file	schema.graphql or ./path/to/schema.gql
Local .json file	introspection.json

For more advanced schema sources (custom headers, inline SDL, getter functions), use a config file.

Config file discovery

When no --config is specified, the CLI looks for config files in the current directory:

1. gazania.config.ts
2. gazania.config.js

TypeScript config

TypeScript config files (.ts) need Node.js 22.6+ with native TypeScript support. On older versions, use gazania.config.js, or pass --experimental-strip-types on Node.js 22.6--23.5.

Priority

When both config file values and CLI flags are provided:

1. CLI flags override config file values for --schema, --output, and extract options
2. If both --schema and --output are provided via CLI, no config file is loaded for generate
3. If only one is provided via CLI, a config file is still required for the missing value
4. For generate, --schema and --output flags cannot override a config file that defines multiple schemas in schemas. Run gazania generate without overrides, or pass both flags for each schema individually
5. For extract, when no --schema flag is given, operations are validated against schemas defined in the config file (matched by schemaHash)