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:

Terminal

yarn add -D @graphql-hive/cli

We recommend installing Hive CLI as part of your project, under devDependencies, instead of using a global installation.

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

Usage

Publish a schema

🔑

This CLI command requires an active registry token with Read & Write permissions to the target.

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:

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

🔑

This CLI command requires an active registry token with Read permissions to the target.

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"

Further reading:

Delete a schema

🔑

This CLI command requires an active registry token with Read & Write permissions to the target and the project.

This action is only available for Schema-Stitching and Apollo Federation projects.

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

In case you want to delete 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

💡

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.

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 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.

If you need to change the way Git identifies your author property, you may use the following commands:

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

Fetch a schema from CDN

You can fetch the GraphQL schema from the CDN using the artifact:fetch command.

You can learn how to create a CDN access token in the High-Availability CDN documentation.

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

For more information please refer to the CLI readme (opens in a new tab).

CLI and GitHub Integration

If GitHub Integration is enabled for your organization, and a GitHub repository is linked to the Hive project is active, you may specify an additional --github flag to report the results back to GitHub as Check Suite (for schema:check and schema:publish commands):

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 (opens in a new tab)

Laboratory Hive Client