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:
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:
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:
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:
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)