Using the Grafbase CLI

This topic describes how to use the Grafbase command-line interface (CLI) to develop locally.

You can use the CLI for local development without installing it by using npx:

npx grafbase dev

Once the command completes, the local development environment:

  • Serves a GraphQL API on http://localhost:4000/graphql.
  • Makes the GraphQL Playground available on http://localhost:4000. You can specify a different port with the --port *PORT* option, where PORT is an open port on your computer. If you aren't sure which port to use, use the --search option to the dev command to list the open ports on your computer.
  • Uses the .grafbase folder to store assets and a local version of the database.

Install the CLI using npm, yarn, or cargo:

  • npm i -g grafbase
  • yarn global add grafbase
  • cargo install grafbase

You can also install the CLI using one of the platform-specific binaries from our Releases page in GitHub.

Use the grafbase init command to either set up an existing project or create a new project.

To create a new project, call the grafbase init NAME command, where NAME is the name of the new project. The command:

  • Creates the directory NAME
  • Creates the sub-directory grafbase within the NAME directory
  • Creates the file schema.graphql within the grafbase sub-directory

The grafbase init NAME command fails if the NAME directory exists.

To create a new project within the existing directory NAME, navigate to the NAME directory and call the grafbase init command. The command:

  • If the sub-directory grafbase does not exist, the command creates it
  • Creates the file schema.graphql within the grafbase sub-directory

The grafbase init command fails if the schema.graphql file exists in the grafbase sub-directory.

Use the grafbase -h (or grafbase --help) command to see the available CLI commands and options. It returns the following information, where VERSION is the version of the CLI:

grafbase *VERSION*
The Grafbase command line interface

USAGE:
    grafbase 

OPTIONS:
    -h, --help     Print help information
    -V, --version  Print version information

SUBCOMMANDS:
    completions    Output completions for the chosen shell
                   To use, write the output to the appropriate location for your shell
    dev            Run your grafbase project locally
    help           Print this message or the help of the given subcommand(s)
    init           Sets up the current or a new project for Grafbase
    reset          Resets the local data for the current project by removing the .grafbase directory

The CLI supports invoking a local development environment with the following command:

grafbase dev

Once the command completes, the local development environment:

  • Serves a GraphQL API on http://localhost:4000/graphql.
  • Makes the GraphQL Playground available on http://localhost:4000. You can specify a different port with the --port *PORT* option, where PORT is an open port on your computer. If you aren't sure which port to use, use the --search option to the dev command to list the open ports on your computer. By default the CLI reloads the development server when it detects schema changes. If you do not want the CLI to watch for changes, use the --disable-watch option to disable this feature.
  • Uses the .grafbase folder to store assets and a local version of the database.

Use the grafbase completions *shell* command to generate a script that you can use to enable CLI command completions for one of the following shells:

  • bash
  • Elvish (elvish)
  • fish
  • Windows PowerShell (powershell)
  • zsh

The command prints the script to the screen, so you should redirect it to a file and use that file to enable command completion on your computer.

For example, in bash:

  1. grafbase completions bash > ~/MyBashFile.sh
  2. chmod +x ~/MyBashFile.sh

Then source MyBashFile.sh in your .bash_profile file:

. ./MyBashFile.sh

NOTE: On Windows you might have to add a shebang to the top of MyBashFile.sh:

#!/bin/sh
...