If you are running hive command line in a directory that has a Git repository configured (.git),
the CLI will automatically extract the values for the author and commit for the certain commands
(e.g. schema publish and schema check.
You may override these values by explicitly passing the --author and --commit flags to the CLI.
If your project does not have a Git repository configured with a user name and email, you are
required to pass the --author and --commit flags to the CLI.
If you need to change the way Git identifies your author property, you may use the following
commands:
If GitHub Integration is enabled for your organization, and the GitHub integration has access to the
GitHub repository, you may specify an additional --github flag to report the results back to
GitHub as Check Suite when running the Hive CLI from within a GitHub action.
You can attach metadata to your schema publication. Metadata files published to Hive must be valid
JSON and are limited to 25MB. This metadata is not exposed in the Hive UI, but it can be useful
for storing JSON configuration files for services, such as for
GraphQL Mesh.
To attach metadata to your published schema, you can use --metadata flag when publishing.
Hive Console creates a new schema version in the destination target using the exact same composed supergraph from the source target and updates the CDN state automatically.
Specifc Schema Version
Roll back a target to a previously published schema version:
This creates a new schema version from the specified historical version and updates the target CDN state accordingly.
The schema version ID can be obtained from the Hive Console schema history view.
Check a Schema
Checking a GraphQL schema is the form of checking the compatibility of an upcoming schema, compared
to the latest published version.
This process of checking a schema needs to be done before publishing a new schema version. This
is usually done as part of a CI/CD pipeline, and as part of Pull Request flow.
Hive CLI will give you a list of all changes, sorted by criticality level (Breaking, Dangerous,
Safe) and fail the check once breaking change is detected.
If you want to be able to leverage breaking change approvals, you must provide the --contextId
parameter. Using --contextId is optional when using GitHub repositories and actions with the
--github flag.
If GitHub Integration is enabled for your organization, and the GitHub integration has access to the
GitHub repository, you may specify an additional --github flag to report the results back to
GitHub as Check Suite when running the Hive CLI from within a GitHub action.
When developing subgraphs locally, you might want to compose a supergraph with your local subgraph
changes. Hive Console CLI helps you to do that with the hive dev command.
Remote mode
This mode enables you to replace the subgraph(s) available in the Registry with your local
subgraph(s) and compose a Supergraph.
Rather than uploading your local schema to the registry and retrieving the supergraph from the CDN,
you can integrate your local modifications directly into the supergraph.
The result of executing this command is a file containing the Supergraph SDL, which can be feed into
the gateway.
# Introspect the SDL of the local servicehive dev \ --registry.accessToken "<YOUR_ACCESS_TOKEN>" \ --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \ --remote \ --service reviews \ --url http://localhost:3001/graphql# Watch modehive dev \ --registry.accessToken "<YOUR_ACCESS_TOKEN>" \ --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \ --remote \ --watch \ --service reviews \ --url http://localhost:3001/graphql# Provide the SDL of the local servicehive dev \ --registry.accessToken "<YOUR_ACCESS_TOKEN>" \ --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \ --remote \ --service reviews \ --url http://localhost:3001/graphql \ --schema reviews.graphql# or with multiple serviceshive dev \ --registry.accessToken "<YOUR_ACCESS_TOKEN>" \ --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \ --remote \ --service reviews --url http://localhost:3001/graphql \ --service products --url http://localhost:3002/graphql --schema products.graphql# Custom output file (default: supergraph.graphql)hive dev \ --registry.accessToken "<YOUR_ACCESS_TOKEN>" \ --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \ --remote \ --service reviews \ --url http://localhost:3001/graphql \ --write local-supergraph.graphql
Usage example
Let’s say you have two subgraphs, reviews and products, and you want to test the reviews
service.
First, you need to start the reviews service locally and then run the following command:
This command will fetch subgraph’s schema from the provided URL, replace the original reviews
subgraph from the Registry with the local one, and compose a supergraph. The outcome will be saved
in the supergraph.graphql file.
The products subgraph will stay untouched, meaning that the gateway will route requests to its
remote endpoint.
The --watch flag will keep the process running and update the supergraph whenever the local
schema changes.
Now you’re ready to use the supergraph.graphql file in your gateway and execute queries.
This mode enables you to compose a Supergraph with your local subgraph(s).
Rather than uploading your local schema to the registry and retrieving the supergraph from the CDN,
you can integrate your local modifications directly into the supergraph.
The result of executing this command is a file containing the Supergraph SDL, which can be feed into
the gateway.
# Introspect the SDL of the local servicehive dev \ --registry.accessToken "<YOUR_ACCESS_TOKEN>" \ --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \ --service reviews \ --url http://localhost:3001/graphql# Watch modehive dev \ --registry.accessToken "<YOUR_ACCESS_TOKEN>" \ --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \ --service reviews \ --url http://localhost:3001/graphql# Provide the SDL of the local servicehive dev \ --registry.accessToken "<YOUR_ACCESS_TOKEN>" \ --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \ --service reviews \ --url http://localhost:3001/graphql \ --schema reviews.graphql# or with multiple serviceshive dev \ --registry.accessToken "<YOUR_ACCESS_TOKEN>" \ --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \ --service reviews --url http://localhost:3001/graphql \ --service products --url http://localhost:3002/graphql --schema products.graphql# Custom output file (default: supergraph.graphql)hive dev \ --registry.accessToken "<YOUR_ACCESS_TOKEN>" \ --target "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>" \ --service reviews \ --url http://localhost:3001/graphql \ --write local-supergraph.graphql
Usage example
Let’s say you have two subgraphs, reviews and products, and you want to test the reviews
service.
First, you need to start the reviews service locally and then run the following command:
This command will fetch subgraph’s schema from the provided URL and compose a supergraph. The
outcome will be saved in the supergraph.graphql file.
The products subgraph will be omitted from the supergraph.
The --watch flag will keep the process running and update the supergraph whenever the local
schema changes.
Now you’re ready to use the supergraph.graphql file in your gateway and execute queries.
Fetch a Schema from the Registry
Sometimes it is useful to fetch a schema (SDL or Supergraph) from Hive, for example, to use it in a
local development. This can be done using the schema:fetch command.
You can fetch either the latest schema or a schema by the action id (commit sha) that was used for
publishing the schema version. The --write option can be used for writing the schema to a file.