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:

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 use an existing project, it must have the file schema.graphql in the grafbase directory from where you invoked the init command.

To create a new project, you must supply an argument to the init command, specifying the name of the new project. The command creates a directory using that argument, the directory grafbase within the new directory, and adds a placeholder schema.graphql file within the grafbase 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:

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

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