Nitro GraphQL CLI

Nitro GraphQL comes with a standalone CLI tool. With this tool you can:

• Create new projects from ready-made templates
• Generate GraphQL types
• Validate your schemas
• Use shell tab completion

Installation

Project Installation

pnpm add -D nitro-graphql

npm install -D nitro-graphql

yarn add -D nitro-graphql

bun add -D nitro-graphql

Global Installation

Global installation is recommended to use shell completion everywhere:

pnpm add -g nitro-graphql

npm install -g nitro-graphql

yarn global add nitro-graphql

bun add -g nitro-graphql

Commands

init - Create Project

Creates a new Nitro GraphQL project.

Basic Usage (Empty Project)

nitro-graphql init

This command creates basic files in the current directory:

• nitro-graphql.config.ts - Configuration file
• tsconfig.json - TypeScript settings
• server/graphql/schema.graphql - Sample schema
• server/graphql/hello.resolver.ts - Sample resolver
• graphql/hello.graphql - Sample client query

Create Project from Template

To create a project from ready-made templates:

# Show template list
nitro-graphql init --list
nitro-graphql init -l

# Create new project with template
nitro-graphql init my-app --template drizzle-orm
nitro-graphql init my-app -t vite-react

Available Templates

Custom Template Usage

You can download templates from GitHub, GitLab or other sources:

# GitHub shorthand
nitro-graphql init my-app -t gh:user/repo

# GitHub full path
nitro-graphql init my-app -t github:user/repo/subdirectory

# GitLab
nitro-graphql init my-app -t gitlab:user/repo

Options

generate - Type Generation

Generates TypeScript types from GraphQL schemas.

# Generate all types (server + client)
nitro-graphql generate
nitro-graphql gen
nitro-graphql g

# Generate only server types
nitro-graphql generate:server
nitro-graphql gen:server

# Generate only client types
nitro-graphql generate:client
nitro-graphql gen:client

# Run in watch mode
nitro-graphql generate --watch
nitro-graphql g -w

Options

validate - Schema Validation

Validates your GraphQL schemas and reports errors.

nitro-graphql validate
nitro-graphql v

Shell Tab Completion

The CLI provides shell tab completion support. With this feature, you can complete commands and options using the TAB key.

Supported Shells

• zsh (macOS default)
• bash
• fish
• PowerShell

Setup

# 1. Save completion script to file
nitro-graphql complete zsh > ~/.nitro-graphql-completion.zsh

# 2. Add to ~/.zshrc
echo 'source ~/.nitro-graphql-completion.zsh' >> ~/.zshrc

# 3. Reload shell
source ~/.zshrc

# 1. Save completion script to file
nitro-graphql complete bash > ~/.nitro-graphql-completion.bash

# 2. Add to ~/.bashrc
echo 'source ~/.nitro-graphql-completion.bash' >> ~/.bashrc

# 3. Reload shell
source ~/.bashrc

# Save to completions folder
nitro-graphql complete fish > ~/.config/fish/completions/nitro-graphql.fish

# Add to profile
nitro-graphql complete powershell >> $PROFILE

Temporary Usage

To test completion without permanent installation:

source <(nitro-graphql complete zsh)

source <(nitro-graphql complete bash)

Usage Examples

After setup, you can use TAB key for completion:

# Command completion
nitro-graphql <TAB>
# → generate, gen, g, init, validate, v, complete

# Subcommand completion
nitro-graphql gen<TAB>
# → generate, generate:server, generate:client

# Template completion
nitro-graphql init -t <TAB>
# → nitro, drizzle-orm, vite, vite-react, vite-vue, better-auth, gh:, github:, gitlab:

# Option completion
nitro-graphql init -<TAB>
# → -t, -l, -f, --template, --list, --force, --cwd

Configuration File

The CLI reads settings from nitro-graphql.config.ts:

import { defineConfig } from 'nitro-graphql/cli'

export default defineConfig({
  // GraphQL framework: 'graphql-yoga' | 'apollo-server'
  framework: 'graphql-yoga',

  // Server-side GraphQL files
  serverDir: './server/graphql',

  // Client-side GraphQL files
  clientDir: './graphql',

  // Build output directory
  buildDir: './.nitro-graphql',

  // Type files directory
  typesDir: './.nitro-graphql/types',

  // Patterns to ignore
  ignore: ['**/node_modules/**', '**/dist/**'],
})

FAQ

Is global installation required?

No, project installation is sufficient. However, if you want to use shell completion everywhere, global installation is recommended.

Where are templates downloaded from?

Templates are downloaded from the examples/ folder of the productdevbook/nitro-graphql repo on GitHub.

How do I create a custom template?

You can use any GitHub repo as a template:

nitro-graphql init my-app -t github:username/my-template

Your template should have at least these files:

• package.json
• GraphQL schema files
• Resolver files

Completion isn't working, what should I do?

1. Make sure CLI is installed globally
2. Regenerate the completion script
3. Restart your shell

pnpm add -g nitro-graphql
nitro-graphql complete zsh > ~/.nitro-graphql-completion.zsh
source ~/.zshrc

npm install -g nitro-graphql
nitro-graphql complete zsh > ~/.nitro-graphql-completion.zsh
source ~/.zshrc

bun add -g nitro-graphql
nitro-graphql complete zsh > ~/.nitro-graphql-completion.zsh
source ~/.zshrc