Hive CLI (Command Line Interface)

You can perform schema-registry actions on your Hive targets schemas using the Hive CLI.

Installation

NodeJS

If you are running a JavaScript/NodeJS project, you can install Hive CLI from the npm registry:

npm i -D @graphql-hive/cli

pnpm add -D @graphql-hive/cli

yarn add --dev @graphql-hive/cli

bun add --dev @graphql-hive/cli

Binary

If you are running a non-JavaScript project, you can download the prebuilt binary of Hive CLI using the following command:

curl -sSL https://graphql-hive.com/install.sh | sh

powershell -c "irm https://graphql-hive.com/install.ps1 | iex"

Specific version

You can also download a specific version of the binary:

curl -sSL https://graphql-hive.com/install.sh | sh -s "0.31.0"
# or
curl -sSL https://graphql-hive.com/install.sh | HIVE_CLI_VERSION="0.31.0" sh
# or
export HIVE_CLI_VERSION="0.31.0"
curl -sSL https://graphql-hive.com/install.sh | sh

$env:HIVE_CLI_VERSION="0.31.0"; powershell -c "irm https://graphql-hive.com/install.ps1 | iex"

Usage

Publish a schema

Start by setting your Hive token in hive.json file, or set it as HIVE_TOKEN environment variable.

Further reading:

• Publishing a schema to the Schema Registry

Single Schema Project

If you have a single file for your GraphQL schema:

hive schema:publish schema.graphql

Or, multiple files using a glob expression:

hive schema:publish "src/*.graphql"

Further reading:

• schema:publish API Reference

Apollo Federation / Schema-Stitching projects

hive schema:publish --service reviews --url http://my-service.com/graphql schema.graphql

Further reading:

• schema:publish API Reference
• Apollo Router integration
• Apollo-Server integration

Hive Metadata

If your GraphQL schema runtime requires any metadata to run, you can attach metadata to your schema publication. Hive metadata published to Hive must be a valid JSON, and limited to 25MB.

To attach metadata to your published schema, you can use --metadata flag when publishing.

You can load the metadata from a file:

hive schema:publish schema.graphql --metadata metadata.json

Or, use an inline JSON passed as a string:

hive schema:publish schema.graphql --metadata '{ "someData": true }'

Further reading:

• Fetching Hive Metadata from the CDN

Check a schema

Start by setting your Hive token in hive.json file, or set it as HIVE_TOKEN environment variable.

Checking a GraphQL schema is the form of checking the compatbility 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.

hive schema:check schema.graphql

Or, multiple files using a glob expression:

hive schema:check "src/*.graphql"

If you want to leverage from retaining approved breaking changes within the lifecyle of a pull/merge request or branch, you must provide the --contextId parameter. Using --contextId is optional when using GitHub repositories and actions with the --github flag.

hive schema:check --contextId "pr-123" "src/*.graphql"

Further reading:

• Publishing a schema to the Schema Registry
• Conditional Breaking Changes

Delete a schema

Start by setting your Hive token in hive.json file, or set it as HIVE_TOKEN environment variable.

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.

hive schema:delete SERVICE_NAME

Develop schema locally

When developing subgraphs locally, you might want to compose a supergraph with your local subgraph changes. GraphQL Hive helps you to do that with the hive dev command.

# Introspect the SDL of the local service
hive dev --remote --service reviews --url http://localhost:3001/graphql
 
# Watch mode
hive dev --remote --watch --service reviews --url http://localhost:3001/graphql
 
# Provide the SDL of the local service
hive dev --remote --service reviews --url http://localhost:3001/graphql --schema reviews.graphql
 
# or with multiple services
hive dev \
  --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 --remote --service reviews --url http://localhost:3001/graphql --write local-supergraph.graphql

hive dev --remote --watch --service reviews --url http://localhost:3001/graphql

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 service
hive dev --service reviews --url http://localhost:3001/graphql
 
# Watch mode
hive dev --watch --service reviews --url http://localhost:3001/graphql
 
# Provide the SDL of the local service
hive dev --service reviews --url http://localhost:3001/graphql --schema reviews.graphql
 
# or with multiple services
hive dev \
  --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 --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:

hive dev --watch --service reviews --url http://localhost:3001/graphql

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.

Git Metadata

If you are running hive command line in a directory that has a Git repository configured (.git), then Hive will be able to automatically detect and extract the values for --author and --commit, in order to tag schemas published using the schema:publish or schema:check command.

You may override these values by 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.

git config --global user.name "John Doe"
git config --global user.email "john@doe.org"

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.

hive schema:fetch --type sdl --write schema.graphql
hive schema:fetch --type sdl --write schema.graphql feb8aa9ec8932eb

For projects with a supergraph it is also possible to fetch the supergraph.

hive schema:fetch --type supergraph --write supergraph.graphql
hive schema:fetch --type supergraph --write supergraph.graphql feb8aa9ec8932eb

It is also possible to print a list of subgraph details in an ascii table.

hive schema:fetch --type subgraphs
hive schema:fetch --type subgraphs feb8aa9ec8932eb

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.

hive artifact:fetch --artifact sdl --cdn.endpoint VALUE --cdn.accessToken VALUE

For more information please refer to the CLI readme.

CLI and 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 (for schema:check and schema:publish commands) when running the Hive CLI from within a GitHub action:

hive schema:publish schema.graphql --github

hive schema:check schema.graphql --github

API Reference

List of all available CLI commands and their options can be found here

Errors

100 "Invalid Config Error"

Example: hive schema:fetch

The provided "hive.json" is invalid.

Suggested Fix

A configuration file was found but the format does not match what is expected. See https://github.com/graphql-hive/console/blob/main/packages/libraries/cli/README.md#config-file-hivejson for structure details and try updating to the latest version if contents appear valid.

101 "Invalid Command Error"

Example: hive badcommand

The command, "badcommand", does not exist.

Suggested Fix

Use "hive help" for a list of available commands.

102 "Missing Arguments Error"

Example: hive schema:delete

Missing 1 required argument:
SERVICE  name of the service

Suggested Fix

Use "hive help [command]" for usage details.

103 "Missing Registry Token Error"

Example: HIVE_TOKEN='' hive schema:fetch

A registry token is required to perform the action. For help generating an access token, see https://the-guild.dev/graphql/hive/docs/management/targets#registry-access-tokens

Suggested Fix

A registry token can be set using the environment variable "HIVE_TOKEN", argument "--registry.accessToken", or config file "hive.json". For help generating a token, see https://the-guild.dev/graphql/hive/docs/management/targets#registry-access-tokens

104 "Missing Cdn Key Error"

Example: hive artifact:fetch --artifact sdl

A CDN key is required to perform the action. For help generating a CDN key, see https://the-guild.dev/graphql/hive/docs/management/targets#cdn-access-tokens

Suggested Fix

A CDN key can be set using the argument "--cdn.accessToken" or config file "hive.json". For help generating a CDN key, see https://the-guild.dev/graphql/hive/docs/management/targets#cdn-access-tokens

105 "Missing Endpoint Error"

Example: hive schema:delete --registry.endpoint= foo-service

A registry endpoint is required to perform the action.

Suggested Fix

A registry endpoint is used when self hosting Hive, otherwise, use the default. The registry endpoint can be set using the environment variable "HIVE_REGISTRY", or argument "--registry.endpoint".

106 "Invalid Registry Token Error"

Example: HIVE_TOKEN=badtoken hive schema:fetch

A valid registry token is required to perform the action. The registry token used does not exist or has been revoked.

Suggested Fix

A registry token can be set using the environment variable "HIVE_TOKEN", argument "--registry.accessToken", or config file "hive.json". For help generating a token, see https://the-guild.dev/graphql/hive/docs/management/targets#registry-access-tokens

107 "Invalid Cdn Key Error"

Example: hive artifact:fetch --artifact sdl

A valid CDN key is required to perform the action. The CDN key used does not exist or has been revoked.

Suggested Fix

A CDN key can be set using the argument "--cdn.accessToken" or config file "hive.json". For help generating a CDN key, see https://the-guild.dev/graphql/hive/docs/management/targets#cdn-access-tokens

108 "Missing Cdn Endpoint Error"

Example: HIVE_CDN_ENDPOINT='' hive artifact:fetch

A CDN endpoint is required to perform the action.

Suggested Fix

A registry endpoint is used when self hosting Hive, otherwise, use the default. This error can happen if the CDN endpoint is set to an empty string. To set the CDN endpoint, use the argument "--cdn.endpoint" or environment variable "HIVE_CDN_ENDPOINT"

109 "Missing Environment Error"

Example: GITHUB_REPOSITORY='' hive schema:publish --author=username --commit=sha

Missing required environment variable:
GITHUB_REPOSITORY  Github repository full name, e.g. graphql-hive/console

Suggested Fix

If using the github integration, then a github repository must be set. This is provided by the default Github workflow and typically does not need manually set. For more information about the Github integration, see https://the-guild.dev/graphql/hive/docs/other-integrations/ci-cd

110 "Github Commit Required Error"

Example: hive schema:check FILE --github

Couldn't resolve commit sha required for GitHub Application.

Suggested Fix

Make sure the command is called within a valid git project. To use the Github integration, there must be at a commit in the history to reference. The commit sha is set as the schema version in the registry and is used for change approvals and other features. See https://the-guild.dev/graphql/hive/docs/management/organizations#github for more details about this integration.

111 "Github Repository Required Error"

Example: hive schema:check FILE --github

Couldn't resolve git repository required for GitHub Application.

Suggested Fix

Make sure the command is called within a valid git project. See https://the-guild.dev/graphql/hive/docs/management/organizations#github for more details about this integration.

112 "Github Author Required Error"

Example: hive schema:check FILE --github

Couldn't resolve commit author required for GitHub Application.

Suggested Fix

Make sure the command is called within a valid git project. See https://the-guild.dev/graphql/hive/docs/management/organizations#github for more details about this integration.

113 "HTTPError"

Example: hive schema:fetch

A server error occurred while performing the action. A call to "${endpoint}" failed with Status: 500, Text: Server Unavailable.

Suggested Fix

Check your network connection and verify the value if using a custom CDN or registry endpoint. If the error status is >= 500, then there may be an issue with the Hive servers. Check the Hive service status for available details https://status.graphql-hive.com/ and if the issue persists then contact The Guild support.

114 "Network Error"

Example: hive schema:fetch

A network error occurred while performing the action: "${cause instanceof Error ? `${cause.name}: ${cause.message}` : cause}"

Suggested Fix

Check your network connection and verify the value if using a custom CDN or registry endpoint.

115 "APIError"

Example: hive schema:check --service foo schema.graphql

Something went wrong. (Request ID: "12345678")

Suggested Fix

The operation was executed but an error response was returned from the API call. Follow the recommendation in the returned error message.

116 "Introspection Error"

Example: hive dev --remote --service reviews --url http://localhost:3001/graphql

Could not get introspection result from the service. Make sure introspection is enabled by the server.

Suggested Fix

Schema contents are required to perform composition. Either the URL provided must respond to to the request: "query { _service { sdl } }" to provide its schema, or a the SDL can be provided locally using the "--schema" argument.

117 "Unsupported File Extension Error"

Example: hive introspect LOCATION --write schema.foo

Got unsupported file extension: ".foo"

Suggested Fix

The file extension indicates the format to write. Try specifying one of the supported formats. Use "hive [command] help" for more information about the command's input.

118 "File Missing Error"

Example: hive app:create undefined

Failed to load file "undefined"

Suggested Fix

The file specified does not exist or cannot be read. Check that the path is correct.

119 "Invalid File Contents Error"

Example: hive app:create schema.json

File "schema.json" could not be parsed. Please make sure the file is readable and contains a valid [expectedFormat].

Suggested Fix

The file specified may not be valid JSON. Check that the file specified is correct and valid.

199 "Unexpected Error"

Example: hive schema:fetch --registry.accessToken=*** 12345

An unexpected error occurred: ${message}
> Enable DEBUG=* for more details.

Suggested Fix

An issue occurred during execution that was not expected. Enable DEBUG=* to view debug logs which may provide more insight into the cause.

200 "Schema File Not Found Error"

Example: hive schema:check FILE

Error reading the schema file "${fileName}"

Suggested Fix

Verify the file path is correct. For help generating a schema file, see your implemented GraphQL library's documentation.

201 "Schema File Empty Error"

Example: hive schema:check schema.graphql

The schema file "schema.graphql" is empty.

Suggested Fix

Verify the file path and file contents are correct. For help generating a schema file, see your implemented GraphQL library's documentation.

300 "Schema Publish Failed Error"

Example: hive schema:publish schema.graphql

Schema publish failed.

Suggested Fix

The schema failed checks during publish. If this is an older project, you may still be able to publish using the "--force" flag. "--force" is enabled by default for new projects. For more details about the schema registry behavior, see https://the-guild.dev/graphql/hive/docs/schema-registry

301 "Invalid SDLError"

Example: hive schema:publish schema.graphql

The SDL is not valid at line 0, column 1:
 Unexpected token '{'

Suggested Fix

There is a syntax error in the SDL. Correct the syntax error mentioned and try again. If there are multiple syntax errors, only one may be mentioned at a time.

302 "Schema Publish Missing Service Error"

Example: hive schema:publish schema.graphql --url https://foo.service

The schema failed to publish. Please use the "--service <name>" parameter.

Suggested Fix

A service name and url are required when publishing a subgraph schema.

303 "Schema Publish Missing Url Error"

Example: hive schema:publish schema.graphql --service foo

The schema failed to publish. Please use the "--url <url>" parameter.

Suggested Fix

A service name and url are required when publishing a subgraph schema.

400 "Persisted Operations Malformed Error"

Example: hive app:create --name ios --version 1.0.0 operations.json

Persisted Operations file "operations.json" is malformed.

Suggested Fix

The operations JSON could not be parsed and validated. Check for and address any syntax errors in this file.

500 "Schema Not Found Error"

Example: hive schema:fetch --registry.accessToken=*** 12345

No schema found.

Suggested Fix

The actionId does not have a schema associated with it. Verify the action ID or do not provide an action ID to fetch the latest version.

501 "Invalid Schema Error"

Example: hive schema:fetch --registry.accessToken=*** 12345

Schema is invalid.

Suggested Fix

The action ID is associated with an invalid schema. Try another action ID.

600 "Service And Url Length Mismatch"

Example: hive dev --service reviews --url http://localhost:3001/graphql --service products

Not every services has a matching url. Got 2 services and 1 url.

Suggested Fix

Composition requires a service and url pair per subgraph. Make sure both are provided for every subgraph using the "--service" and "--url" arguments.

601 "Local Composition Error"

Example: hive dev --service reviews --url http://localhost:3001/graphql --service products --url http://localhost:3002/graphql

Local composition failed:
[reason]

Suggested Fix

The provided schemas are not composable. This means that there are conflicting types between the two subgraphs. Review the provided reason to help determine the best path forward for the subgraph(s).

602 "Remote Composition Error"

Example: hive dev --remote --service reviews --url http://localhost:3001/graphql --service products --url http://localhost:3002/graphql

Remote composition failed:
Detected 1 error
- [reason]

Suggested Fix

The provided schemas are not composable. This means that there are conflicting types between the two subgraphs. Review the provided reason to help determine the best path forward for the subgraph(s).

603 "Invalid Composition Result Error"

Example: hive dev --remote --service reviews --url http://localhost:3001/graphql --service products --url http://localhost:3002/graphql

Composition resulted in an invalid supergraph: [supergraph]

Suggested Fix

Composition passed but the resulting supergraph SDL was invalid. If using an external schema composer, verify the logic and make sure the version of federation being used is supported by Hive.

700 "Invalid Documents Error"

Example: hive operations:check operations/*.gql

Invalid operation syntax:
 - [reason]

Suggested Fix

Operations must be valid graphql. Address the operation syntax errors and then try again.