CLI Commands

The commands below can be used with the Grafbase CLI.

You use the init command to initialize a new graph, or existing graph.

cd my-graph
npx grafbase init

The init command will create the new directory grafbase that contains your schema, environment variables, and more.

You can use the following flags when invoking init:

• --template — The name or GitHub URL of the template to use for the new graph.

npx grafbase init --template blog

You use the dev command to start the local Grafbase server.

npx grafbase dev

You can then visit the following URLs to access:

• Playground — http://localhost:4000
• API — http://localhost:4000/graphql

You can override the default behaviour of dev by passing various flags.

• -p, --port <PORT> — Set a different port the server runs on. Defaults to 4000.
• -s, --search — If a given port is unavailable, search for another.
• --log-level-functions <LOG_LEVEL> — Log level for function invocations. Defaults to log-level.
• --log-level-graphql-operations <LOG_LEVEL> — Log level for GraphQL operations. Defaults to log-level.
• --log-level-fetch-requests <LOG_LEVEL> — Log level for fetch requests. Defaults to log-level.
• --log-level <LOG_LEVEL> — Log level for fetch requests.
• -v, --verbose — A shortcut to enable detailed logging.
• --disable-watch — Disable restarting the server when a change to your schema is detected.
• -h, --help — Print help.

You should use the login command to authenticate with your Grafbase account so you can create and deploy graphs without leaving the CLI.

npx grafbase login

You will be redirected to the Grafbase Dashboard to verify linking your account.

You should configure the environment variable GRAFBASE_ACCESS_TOKEN for use inside of CI/CD, such as GitHub Actions.

You should use the create command to create a new Grafbase graph.

Your graph will be deployed automatically once created.

npx grafbase create

You can pass the following flags with the create command:

• -n, --name <NAME> — The name for the new graph.
• -a, --account <SLUG> — The slug of the account in which the new graph should be created.
• -e, --env [<ENVIRONMENT_VARIABLES>] — A repeated list of environment variables to the graph (NAME=VALUE).
• -h, --help — Print help

You must pass all arguments if you opt out of the interactive prompt.

You should use the deploy command to redeploy an existing graph.

npx grafbase deploy

You can pass the following flags with the deploy command:

• -g, --graph-ref <GRAPH_REF> — Graph reference following the format account/graph@branch. If omitted, the graph must be linked first with the grafbase link command.
• -b, --branch <BRANCH> — The branch to deploy into, if running from a linked graph.
• -h, --help — Print help

You can use the reset command to reset your graph data:

npx grafbase reset

This does the same as deleting the .grafbase directory.

You can use the branch subcommands to view and modify graph branches:

npx grafbase branch

Branch creation works from the deploy command.

Lists all branches for the currently linked graph.

npx grafbase branch list

You can delete a branch with the branch remove command.

npx grafbase branch remove account/graph@branch

The production branch is protected, and cannot be removed using the branch remove command.

You can use the environment subcommands to view and modify graph environment variables:

npx grafbase environment

You can all environment variables with the environment list command.

npx grafbase environment list

• -g, --graph-ref <GRAPH_REF> — Graph reference following the format account/graph. If omitted, the graph must be linked first with the grafbase link command.
• -h, --help — Print help

You can create or update an environment variable with the environment create command.

npx grafbase environment create -e production NAME value

• -g, --graph-ref <GRAPH_REF> — Graph reference following the format account/graph. If omitted, the graph must be linked first with the grafbase link command.
• -e, --environment <ENVIRONMENT> — The environment where the variable is available. Possible values: all, production, preview.
• -h, --help — Print help

You can remove an environment variable with the environment remove command.

npx grafbase environment remove -e production NAME

• -g, --graph-ref <GRAPH_REF> — Graph reference following the format account/graph. If omitted, the graph must be linked first with the grafbase link command.
• -e, --environment <ENVIRONMENT> — The environment where the variable is available. Possible values: all, production, preview.
• -h, --help — Print help

You can use the help command to list the available commands and options, as well as the installed version details.

npx grafbase help