Hive CLI (Command Line Interface)
For more information please refer to the CLI readme.
API Reference
List of all available CLI commands and their options can be found here
Errors
You can perform schema-registry actions on your Hive targets schemas using the Hive CLI.
Installation
You can install the Hive CLI as a binary, docker container or a npm package for Node.js.
Download the prebuilt binary of Hive CLI using the following command:
We publish a docker image for the CLI to the GitHub container registry.
If you are running a JavaScript/Node.js project, you can install Hive CLI from the npm.
Specific Version
You can also use a specific version of the CLI. A list of all available versions is available on the GitHub releases page.
Basics
Git Integration
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:
Usage
Push a Schema Revision
Use hive schema:push to upload an immutable schema revision without publishing it. Push the
revision during your merge or release flow, then publish that revision when the
corresponding service is deployed.
Use an immutable identifier, such as the Git commit SHA, as the revision:
For Apollo Federation and Schema Stitching projects, include the service name:
Revision names are immutable for a service within a project. Pushing different schema SDL with an existing revision name fails. Pushing does not add a published schema version or update the schema served through the Hive CDN.
Further reading:
Publish a Schema
You can use the CLI for publishing schema or services/subgraphs to the schema registry.
To publish a schema that was uploaded earlier with hive schema:push, omit the schema file and pass
its revision:
The revision must already exist for the target’s project and, for a distributed schema, the specified service. Hive publishes the exact SDL stored for that immutable revision.
You can also publish SDL directly from a file:
Further reading:
If you have a single file for your GraphQL schema:
Or, multiple files using a glob expression:
Further reading:
Fail on Federation Composition Errors
By default, Hive records an invalid schema version when a Federation subgraph causes a supergraph or contract composition error. The Hive CDN continues serving the latest valid supergraph.
Pass --fail-on-composition-error to reject the publication instead:
If the proposed subgraph causes the supergraph or any configured contract to fail composition, the command exits with an error and Hive does not create a schema version. This option only applies to Federation projects.
GitHub Integration
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.
Further reading:
Metadata
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.
You can load the metadata from a file:
Or, use an inline JSON passed as a string:
Further reading:
Promote a Schema
You can use the CLI to promote an existing schema version between targets or roll back a target to a previously published schema version.
Targets
Promote the latest schema version from one target to another:
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.
Or, multiple files using a glob expression:
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.
For distributed schemas (Federated or Stitching), you are able to view changes to subgraph URLs by
providing the --url parameter.
Further reading:
- Checking a schema with the Schema Registry
- Conditional Breaking Changes
- Approving breaking schema changes
GitHub Integration
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.
Delete a Subgraph
In case you want to compose a schema (or a subgraph in case of Federation), you can do so by using
the hive schema:delete command.
Further reading:
Dry Run
You can also use --dryRun flag first to see what effect the command will have on the registry.
In case you want to confirm deletion of the service without typing anything in the terminal, use
--confirm flag.
Local Subgraph Development
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.
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
--watchflag 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.
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
--watchflag 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.
For projects with a supergraph it is also possible to fetch the supergraph.
It is also possible to print a list of subgraph details in an ascii table.
For more information please refer to the CLI readme.
Fetch a Schema from CDN
You can fetch the GraphQL schema from the CDN using the artifact:fetch command.