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
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.
If Hive Gateway serves your supergraph, it can also compose it directly from the subgraphs running
on your machine with its dev supergraph source, without a separate hive dev process. See
Local Subgraphs (Dev).
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.
Errors
Every error the CLI prints ends with its error code in square brackets, for example[103]. The codes are grouped by command: 1xx apply to every command,2xx to schema:check, 3xx to schema:publish,4xx to app:create, 5xx to schema:fetch,6xx to dev, and 7xx to operations:check. The process exits with 1 for a failed command, 2 for a timeout, and3 when the input was invalid before the command ran. SetHIVE_NO_ERROR_TIP=1 to hide the link to this page in the CLI output.
100 Invalid Config Error
Example: hive schema:fetch
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
Suggested fix: Use "hive help" for a list of available commands.
102 Missing Arguments Error
Example: hive schema:delete
Suggested fix: Use "hive help [command]" for usage details.
103 Missing Registry Token Error
Example: HIVE_TOKEN='' hive schema:fetch
Suggested fix: A registry token can be set using the environment variable "HIVE_TOKEN", the argument "--registry.accessToken", or the 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
Suggested fix: A CDN key can be set using the argument "--cdn.accessToken" or the 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
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 the argument "--registry.endpoint".
106 Invalid Registry Token Error
Example: HIVE_TOKEN=badtoken hive schema:fetch
Suggested fix: A registry token can be set using the environment variable "HIVE_TOKEN", the argument "--registry.accessToken", or the 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
Suggested fix: A CDN key can be set using the argument "--cdn.accessToken" or the 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
Suggested fix: A CDN 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 the environment variable "HIVE_CDN_ENDPOINT".
109 Missing Environment Error
Example: GITHUB_REPOSITORY='' hive schema:publish --author=username --commit=sha
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 to be set manually. For more information about the GitHub integration, see https://the-guild.dev/graphql/hive/docs/other-integrations/ci-cd
110 Commit Required Error
Example: hive schema:check FILE --github
Suggested fix: Make sure the command is called within a valid git repository directory or the '--commit' parameter is provided with a non-empty value.
111 Github Repository Required Error
Example: hive schema:check FILE --github
Suggested fix: Make sure the command is called within a valid git repository directory. See https://the-guild.dev/graphql/hive/docs/management/organizations#github for more details about this integration.
112 Author Required Error
Example: hive schema:check FILE --github
Suggested fix: Make sure the command is called within a valid git repository directory or the '--author' parameter is provided with a non-empty value.
113 HTTPError
Example: hive schema:fetch
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 at https://status.graphql-hive.com/ and if the issue persists then contact The Guild support.
114 Network Error
Example: hive schema:fetch
Suggested fix: Check your network connection and verify the value if using a custom CDN or registry endpoint. Confirm that your network settings allow outbound traffic to Hive's domain.
115 APIError
Example: hive schema:check --service foo schema.graphql
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
Suggested fix: Schema contents are required to perform composition. Either the URL provided must respond to the request "query { _service { sdl } }" to provide its schema, or the SDL can be provided locally using the "--schema" argument.
117 Unsupported File Extension Error
Example: hive introspect LOCATION --write schema.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
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
Suggested fix: The file specified may not be valid JSON. Check that the file specified is correct and valid.
120 Invalid Target Error
Example: hive schema:push --target staging schema.graphql
Suggested fix: Pass the full target slug, "organization/project/target", or the target's UUID. Both are shown on the target's settings page in Hive Console. The option is "--to" or "--from" for "schema:promote".
121 Invalid Federation Subgraph Error
Example: hive dev --remote --service reviews --url http://localhost:3001/graphql
Suggested fix: The server at the URL is not a Federation subgraph: it does not answer "query { _service { sdl } }". Check that the URL is correct and that the server implements the Federation subgraph specification, or pass the SDL locally with "--schema".
121 Invalid Version Id Error
Example: hive schema:promote --to my-org/my-project/production --version 1.0.0
Suggested fix: "--version" takes the ID of a schema version, which is a UUID such as "c8164307-0b42-473e-a8c5-2860bb4beff6". Copy it from the version's page in Hive Console, or promote the latest version of another target with "--from" instead.
121 Conflicting Options Error
Example: hive schema:promote --to my-org/my-project/production --from my-org/my-project/staging --version c8164307-0b42-473e-a8c5-2860bb4beff6
Suggested fix: The listed options cannot be combined. "schema:promote" takes either "--from", to promote the latest version of another target, or "--version", to promote one specific schema version. Remove one of them and run the command again.
199 Unexpected Error
Example: hive schema:fetch --registry.accessToken=*** 12345
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
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
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
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
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
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
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
Suggested fix: The file could not be parsed as a persisted operations manifest. Check the JSON for syntax errors, and make sure it uses one of the supported formats: the GraphQL Code Generator persisted documents output, a Relay persisted queries file, or an Apollo persisted query manifest.
500 Schema Not Found Error
Example: hive schema:fetch --registry.accessToken=*** 12345
Suggested fix: The action ID 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
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
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
Suggested fix: The provided schemas are not composable. This means that there are conflicting types between the 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
Suggested fix: The provided schemas are not composable. This means that there are conflicting types between the 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
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
Suggested fix: Operations must be valid GraphQL. Address the operation syntax errors and then try again.