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], and is printed to stderr. The codes are grouped by command: 1xx Generic, 2xx Schema check, 3xx Schema publish, 4xx App create, 5xx Artifact fetch, 6xx Dev and 7xx Operations check. Set HIVE_NO_ERROR_TIP=1 to hide the link to this page in the CLI output. The process exits with one of these codes:
| Exit code | Name | Meaning |
|---|---|---|
| 0 | SUCCESS | The command succeeded. |
| 1 | ERROR | The command ran, but the operation failed. |
| 2 | TIMED_OUT | A request timed out. The operation may still have completed on the server. |
| 3 | BAD_INIT | The command could not start because of invalid input or setup, such as arguments, flags, files or configuration. |
100 Invalid configuration file
Example: hive schema:fetch
Suggested fix: Fix the reported problem in hive.json (or the file set with HIVE_CONFIG). Supported keys are registry.endpoint, registry.accessToken, registry.headers, cdn.endpoint and cdn.accessToken. When HIVE_SPACE is set, the file must contain a top-level key with that name.
101 Unknown command
Example: hive badcommand
Suggested fix: Run hive help to list the available commands and check the spelling.
102 Missing required argument
Example: hive schema:publish
Suggested fix: Provide the listed arguments or flags. Organization access tokens always require the --target flag.
103 Missing registry access token
Example: HIVE_TOKEN='' hive schema:fetch
Suggested fix: Pass --registry.accessToken, set HIVE_TOKEN, or set registry.accessToken in hive.json.
104 Missing CDN access token
Example: hive artifact:fetch --artifact sdl
Suggested fix: Pass --cdn.accessToken, set HIVE_CDN_ACCESS_TOKEN, or set cdn.accessToken in hive.json.
105 Missing registry endpoint
Example: HIVE_REGISTRY='' hive schema:fetch
Suggested fix: Pass --registry.endpoint, set HIVE_REGISTRY, or set registry.endpoint in hive.json. Make sure HIVE_REGISTRY is not set to an empty string.
106 Invalid registry access token
Example: HIVE_TOKEN=badtoken hive schema:fetch
Suggested fix: Create a new access token, and check that the access token and the registry endpoint belong to the same Hive instance.
107 Invalid CDN access token
Example: hive artifact:fetch --artifact sdl --cdn.accessToken badtoken
Suggested fix: Create a new CDN access token for the target, and check that it belongs to the same target as the CDN endpoint.
108 Missing CDN endpoint
Example: HIVE_CDN_ENDPOINT='' hive artifact:fetch --artifact sdl
Suggested fix: Pass --cdn.endpoint, set HIVE_CDN_ENDPOINT, or set cdn.endpoint in hive.json.
109 Missing environment variable
Example: GITHUB_REPOSITORY='' hive schema:publish schema.graphql --github
Suggested fix: Set the listed environment variables. With --github, run the command in GitHub Actions or set GITHUB_REPOSITORY.
110 Missing commit
Example: hive schema:check schema.graphql --github
Suggested fix: Pass --commit (or set HIVE_COMMIT for schema:publish), or run the command inside a git repository.
111 Missing GitHub repository
Example: hive schema:check schema.graphql --github --commit abc123
Suggested fix: Run the command in GitHub Actions, where GITHUB_REPOSITORY is set, or in a CI environment that exposes the repository.
112 Missing author
Example: hive schema:publish schema.graphql --commit abc123
Suggested fix: Pass --author (or set HIVE_AUTHOR for schema:publish), or run the command inside a git repository with a configured user.
113 HTTP error response
Example: hive schema:fetch
Suggested fix: A 4xx status usually means a wrong endpoint or a rejected request: check the endpoint URL and credentials. A 5xx status means the server failed: retry later.
114 Network error
Example: hive schema:fetch
Suggested fix: The request did not complete. Check the network connection, DNS, proxy and TLS settings, and the endpoint URL, then retry.
115 API error
Example: hive schema:check --service reviews schema.graphql
Suggested fix: Read the message returned by the Hive API. Include the request ID when contacting support.
116 Introspection failed
Example: hive dev --remote --service reviews --url http://localhost:3001/graphql
Suggested fix: Make sure the service is running, reachable and allows introspection, or pass the schema file instead of the URL.
117 Unsupported file extension
Example: hive introspect http://localhost:4000/graphql --write schema.foo
Suggested fix: Use one of the supported file extensions listed in the message.
118 File not found
Example: hive app:create --name ios --version 1.0.0 operations.json
Suggested fix: Check that the path or glob matches at least one readable file.
119 Invalid file contents
Example: hive app:create --name ios --version 1.0.0 operations.json
Suggested fix: Make sure the file is readable and contains valid content in the expected format.
120 Invalid target
Example: hive schema:push --target staging --revision abc123 schema.graphql
Suggested fix: Pass the target as a slug in the form organization/project/target, or as a target UUID.
121 Not a Federation subgraph
Example: hive dev --remote --service reviews --url http://localhost:3001/graphql
Suggested fix: Point the URL at a Federation subgraph that exposes Query._service.sdl, or pass the schema file instead.
122 Invalid schema version ID
Example: hive schema:promote --to my-org/my-project/production --version 1.0.0
Suggested fix: Pass the ID of a schema version from the same project as the target.
123 Conflicting options
Example: hive schema:promote --to my-org/my-project/production --from my-org/my-project/staging --version c8164307-0b42-473e-a8c5-2860bb4beff6
Suggested fix: Provide only one of the listed options.
124 Access denied
Example: hive schema:publish --target my-org/my-project/production schema.graphql
Suggested fix: Grant the named permission to the access token, check that --target points at an existing target the token can access, or use an organization access token.
125 Unsupported Hive server version
Example: hive schema:push --registry.endpoint https://hive.example.com/graphql --revision abc123 schema.graphql
Suggested fix: Upgrade the Hive server to a version that supports this CLI version, or use an older CLI version that matches the server. Nothing was executed on the server.
126 Request timed out
Example: hive schema:publish schema.graphql
Suggested fix: The operation may have completed on the server. Check its result, for example in Hive Console or with hive schema:fetch, before retrying.
127 Invalid command input
Example: hive schema:check schema.graphql --unknown
Suggested fix: Check the arguments and flags with hive help <command>.
128 Invalid header
Example: hive schema:fetch --registry.header "x-team: platform"
Suggested fix: Use the Name=Value format for --registry.header and the Name:Value format for --header.
199 Unexpected error
Example: hive schema:fetch
Suggested fix: Re-run the command with DEBUG=* for more details, and report the output if the problem persists.
200 Schema not found
Example: hive schema:check schema.graphql
Suggested fix: Check the file path, glob or URL. For a URL, make sure the service is reachable.
201 No type definitions found
Example: hive schema:check schema.graphql
Suggested fix: Make sure the schema contains GraphQL type definitions. In code files, the definitions must be in a template literal tagged with gql or graphql, or marked with a /* GraphQL */ comment.
202 Schema check failed
Example: hive schema:check schema.graphql
Suggested fix: Review the errors and breaking changes in the output or the linked report. Fix them, approve expected breaking changes in Hive Console, or use --forceSafe.
203 Schema check approval failed
Example: hive schema:check --target my-org/my-project/production --forceSafe schema.graphql
Suggested fix: Make sure the access token has the schemaCheck:approve permission and that the failed schema check was stored by the registry.
300 Schema publish failed
Example: hive schema:publish schema.graphql
Suggested fix: The schema was rejected and nothing was stored. Fix the reported errors and publish again.
301 Invalid SDL
Example: hive schema:publish schema.graphql
Suggested fix: Fix the GraphQL syntax error at the reported location.
302 Missing service name
Example: hive schema:publish schema.graphql --url http://localhost:3001/graphql
Suggested fix: Pass --service <name>. Federation and schema stitching projects require a service name.
303 Missing service URL
Example: hive schema:publish schema.graphql --service reviews
Suggested fix: Pass --url <url>. A service needs a URL the first time it is published, and the URL must be valid.
400 Malformed persisted documents
Example: hive app:create --name ios --version 1.0.0 operations.json
Suggested fix: Use a GraphQL Code Generator, Relay or Apollo persisted query manifest, a directory of .graphql files, or a glob that matches .graphql files containing operations.
401 Invalid operations
Suggested fix: Fix the listed operations so they comply with the requirements.
500 Schema not found in the registry
Example: hive schema:fetch abc123
Suggested fix: Publish a schema to the target first, or check the target, the commit and the --type value.
501 Schema version is not valid
Example: hive schema:fetch abc123
Suggested fix: The requested schema version is not valid. Use a different commit, or fix and publish the schema again.
600 Service and URL count mismatch
Example: hive dev \
--service reviews --url http://localhost:3001/graphql \
--service products
Suggested fix: Pass exactly one --url for every --service.
601 Local composition failed
Example: hive dev \
--service reviews --url http://localhost:3001/graphql \
--service products --url http://localhost:3002/graphql
Suggested fix: Fix the composition errors in the listed subgraphs.
602 Remote composition failed
Example: hive dev --remote \
--service reviews --url http://localhost:3001/graphql \
--service products --url http://localhost:3002/graphql
Suggested fix: Fix the composition errors in the listed subgraphs.
603 Invalid composition result
Example: hive dev --remote \
--service reviews --url http://localhost:3001/graphql \
--service products --url http://localhost:3002/graphql
Suggested fix: The composed supergraph is invalid. Report the output as a bug.
700 Invalid operations
Example: hive operations:check 'operations/*.graphql'
Suggested fix: Fix the listed operations so that they are valid against the schema.