Hive Gateway CLI Reference

An overview of all the CLI arguments and environment variables for the hive-gateway CLI. Get started with the CLI.

Usage

You can get help with using the CLI by appending the --help argument:


hive-gateway --help

which will print out the following:


Usage: hive-gateway [options] [command]

Federated GraphQL Gateway

Options:
  --fork <count>                                  count of workers to spawn. uses "12" (available parallelism) workers when NODE_ENV is "production", otherwise "1" (the main) worker (default: 1 (env: FORK)
  -c, --config-path <path>                        path to the configuration file. defaults to the following files respectively in the current working directory: gateway.ts, gateway.mts, gateway.cts, gateway.js, gateway.mjs, gateway.cjs (env: CONFIG_PATH)
  -h, --host <hostname>                           host to use for serving (default: "0.0.0.0" (default: "0.0.0.0")
  -p, --port <number>                             port to use for serving (default: 4000 (env: PORT)
  --polling <duration>                            schema polling interval in human readable duration (default: "10s") (env: POLLING)
  --no-masked-errors                              don't mask unexpected errors in responses
  --masked-errors                                 mask unexpected errors in responses (default: true)
  --hive-registry-token <token>                   Hive registry token for usage metrics reporting (env: HIVE_REGISTRY_TOKEN)
  --hive-persisted-documents-endpoint <endpoint>  [EXPERIMENTAL] Hive CDN endpoint for fetching the persisted documents. requires the "--hive-persisted-documents-token <token>" option
  --hive-persisted-documents-token <token>        [EXPERIMENTAL] Hive persisted documents CDN endpoint token. requires the "--hive-persisted-documents-endpoint <endpoint>" option
  --hive-cdn-endpoint <endpoint>                  Hive CDN endpoint for fetching the schema (env: HIVE_CDN_ENDPOINT)
  --hive-cdn-key <key>                            Hive CDN API key for fetching the schema. implies that the "schemaPathOrUrl" argument is a url (env: HIVE_CDN_KEY)
  --apollo-graph-ref <graphRef>                   Apollo graph ref of the managed federation graph (<YOUR_GRAPH_ID>@<VARIANT>) (env: APOLLO_GRAPH_REF)
  --apollo-key <apiKey>                           Apollo API key to use to authenticate with the managed federation up link (env: APOLLO_KEY)
  --disable-websockets                            Disable WebSockets support
  --jit                                           Enable Just-In-Time compilation of GraphQL documents (env: JIT)
  -V, --version                                   output the version number
  --help                                          display help for command

Commands:
  supergraph [options] [schemaPathOrUrl]          serve a Federation supergraph provided by a compliant composition tool such as Mesh Compose or Apollo Rover
  subgraph [schemaPathOrUrl]                      serve a Federation subgraph that can be used with any Federation compatible router like Apollo Router/Gateway
  proxy [options] [endpoint]                      serve a proxy to a GraphQL API and add additional features such as monitoring/tracing, caching, rate limiting, security, and more
  help [command]                                  display help for command

All arguments can also be configured in the config file.

Environment Variables

In addition to the env vars showcased in the CLI usage, more are available.

These are usually used for easier usage with these two schema registry services. You don’t need any configuration file if you provide these environment variables.

Hive Registry

HIVE_CDN_ENDPOINT: The endpoint of the Hive Registry CDN
HIVE_CDN_KEY: The API key provided by Hive Registry to fetch the schema
HIVE_REGISTRY_TOKEN: The token to push the metrics to Hive Registry

Learn more about Hive Registry integration here

Apollo GraphOS

APOLLO_KEY: The API key provided by Apollo GraphOS to fetch the supergraph.
APOLLO_GRAPH_REF: The API key provided by Apollo GraphOS to fetch the supergraph.
APOLLO_SCHEMA_CONFIG_DELIVERY_ENDPOINT: The URL of the managed federation up link. By default, it uses the first uplink in the list.

Learn more about GraphOS integration here