Router CLI Configuration Reference
This reference covers the command-line options for configuring an Apollo Router.
Command-line options
This reference lists and describes the options supported by the router binary via command-line options. Where indicated, some of these options can also be provided via an environment variable.
| Option / Environment Variable | Description |
|---|---|
| The supergraph schema of a router. Specified by absolute or relative path (-s / --supergraph <supergraph_path>, or APOLLO_ROUTER_SUPERGRAPH_PATH), or a comma-separated list of URLs (--supergraph-urls <urls>, or APOLLO_ROUTER_SUPERGRAPH_URLS).💡 Avoid embedding tokens inSetting this option disables polling from Apollo Uplink to fetch the latest supergraph schema. To learn how to compose your supergraph schema with the Rover CLI, see the Federation quickstart. Required if you are not using managed federation. If you are using managed federation, you may need to set this option when following advanced deployment workflows. |
| The absolute or relative path to the router's optional YAML configuration file. |
| The absolute or relative path to a file containing the Apollo graph API key for use with managed federation.⚠️ This is not available on Windows. |
| ⚠️ Do not set this option in production! If set, a router runs in dev mode to help with local development.Learn more about dev mode. |
| If set, the router watches for changes to its configuration file and any supergraph file passed with --supergraph and reloads them automatically without downtime. This setting only affects local files provided to the router. The supergraph and configuration provided from GraphOS via Launches (and delivered via Uplink) are always loaded automatically, regardless of this setting. |
| The log level, indicating the most severe log message type to include. In ascending order of verbosity, can be one of: off, error, warn, info, debug, or trace.The default value is info. |
| An offline GraphOS Enterprise license. Enables Enterprise router features when disconnected from GraphOS. An offline license is specified either as an absolute or relative path to a license file ( --license <license_path> or APOLLO_ROUTER_LICENSE_PATH), or as the stringified contents of a license (APOLLO_ROUTER_LICENSE).When not set, the router retrieves an Enterprise license from GraphOS via Apollo Uplink. For information about fetching an offline license and configuring the router, see Offline Enterprise license. |
| If using managed federation, the Apollo Uplink URL(s) that the router should poll to fetch its latest configuration. Almost all managed router instances should omit this option to use the default set of Uplink URLs. If you specify multiple URLs, separate them with commas (no whitespace). For default behavior and possible values, see Apollo Uplink. |
| The request timeout for each poll sent to Apollo Uplink.The default value is 30s (thirty seconds). |
| If set, disables sending anonymous usage information to Apollo. |
| If set, the listen address of the router. |
| If set, the router prints its version number, then exits. |
Development mode
The router can be run in development mode by using the --dev command-line option.
The --dev option is equivalent to running the router with the --hot-reload option the following configuration options:
1sandbox:
2 enabled: true
3homepage:
4 enabled: false
5supergraph:
6 introspection: true
7include_subgraph_errors:
8 all: true
9plugins:
10 # Enable with the header, Apollo-Expose-Query-Plan: true
11 experimental.expose_query_plan: true--dev option in production. If you want to replicate any specific dev mode functionality in production, set the corresponding option in your YAML config file.Configuration schema for IDE validation
The router can generate a JSON schema for config validation in your text editor. This schema helps you format the YAML file correctly and also provides content assistance.
Generate the schema with the following command:
1./router config schema > configuration_schema.jsonAfter you generate the schema, configure your text editor. Here are the instructions for some commonly used editors:
Upgrading your router configuration
New releases of the router might introduce breaking changes to the YAML config file's expected format, usually to extend existing functionality or improve usability.
If you run a new version of your router with a configuration file that it no longer supports, it emits a warning on startup and terminates.
If you encounter this warning, you can use the router config upgrade command to see the new expected format for your existing configuration file:
1./router config upgrade <path_to_config.yaml>You can also view a diff of exactly which changes are necessary to upgrade your existing configuration file:
1./router config upgrade --diff <path_to_config.yaml>Validating your router configuration
The router can be used to validate an existing configuration file. This can be useful if you want to have a validate step as part of your CI pipeline.
1./router config validate <path-to-config-file.yaml>This command takes a config file and validates it against the router's full supported configuration format.