Gatsby CLI is the command-line interface for the Gatsby static site generator framework. It provides essential tools for creating, developing, building, and managing Gatsby projects with comprehensive commands for project lifecycle management, development server operations, production builds, and plugin management.
npm install -g gatsby-cli or npx gatsbyFor programmatic usage (advanced users):
import { createCli } from "gatsby-cli";
import reporter from "gatsby-cli/lib/reporter";For CommonJS:
const { createCli } = require("gatsby-cli");
const reporter = require("gatsby-cli/lib/reporter");The primary interface is the gatsby CLI command:
# Create a new Gatsby site
gatsby new my-site
# Start development server
gatsby develop
# Build for production
gatsby build
# Serve production build
gatsby serve
# Get help
gatsby --helpGatsby CLI is built around several key components:
Core commands for creating, building, and managing Gatsby projects throughout their lifecycle.
// CLI Commands (primary interface)
gatsby new [rootPath] [starter] // Create new project
gatsby develop // Start development server
gatsby build // Build for production
gatsby serve // Serve production build
gatsby clean // Clean cache and built assets
gatsby repl // Start Node.js REPL with Gatsby contextDevelopment server operations with hot reloading, HTTPS support, and debugging capabilities.
gatsby develop [options]
interface DevelopOptions {
host?: string; // -H, --host (default: localhost or env.GATSBY_HOST)
port?: string; // -p, --port (default: 8000 or env.PORT)
open?: boolean; // -o, --open
https?: boolean; // -S, --https
certFile?: string; // -c, --cert-file
keyFile?: string; // -k, --key-file
caFile?: string; // --ca-file
graphqlTracing?: boolean; // --graphql-tracing
openTracingConfigFile?: string; // --open-tracing-config-file
inspect?: number; // --inspect (default: 9229)
inspectBrk?: number; // --inspect-brk (default: 9229)
}Production build operations with optimization options, profiling, and tracing capabilities.
gatsby build [options]
interface BuildOptions {
prefixPaths?: boolean; // --prefix-paths (use pathPrefix from config)
noUglify?: boolean; // --no-uglify (disable JS minification)
profile?: boolean; // --profile (React profiling)
graphqlTracing?: boolean; // --graphql-tracing
openTracingConfigFile?: string; // --open-tracing-config-file
logPages?: boolean; // --log-pages (experimental, hidden)
writeToFile?: boolean; // --write-to-file (experimental, hidden)
functionsArch?: string; // --functions-arch (serverless functions)
functionsPlatform?: string; // --functions-platform (serverless functions)
}Tools for discovering, installing, and managing Gatsby plugins in projects.
gatsby plugin <cmd> [plugins...]
// Available plugin commands
gatsby plugin docs // Show plugin documentation links
gatsby plugin ls // List installed pluginsIntegration with Gatsby Cloud for authentication and user management (experimental feature).
// Cloud commands (requires GATSBY_EXPERIMENTAL_CLOUD_CLI)
gatsby login // Authenticate with Gatsby Cloud
gatsby logout // Sign out of Gatsby Cloud
gatsby whoami // Show current userCLI configuration and utility commands for environment information, settings management, and user feedback preferences.
gatsby info [options] // Environment information
gatsby options <cmd> [key] [value] // CLI configuration
gatsby telemetry [--enable|--disable] // Telemetry settings (deprecated)
gatsby feedback [--enable|--disable] // Feedback preferences
interface InfoOptions {
clipboard?: boolean; // -C, --clipboard
}
interface FeedbackOptions {
enable?: boolean; // --enable feedback requests
disable?: boolean; // --disable feedback requests
}All commands support these global options:
interface GlobalOptions {
verbose?: boolean; // --verbose (detailed output)
noColor?: boolean; // --no-color, --no-colors
json?: boolean; // --json (JSON logger)
help?: boolean; // -h, --help
version?: boolean; // -v, --version
}// Primary CLI interface
function createCli(argv: Array<string>): yargs.Arguments;
// Project creation and initialization
function initStarter(starter?: string, root?: string): Promise<void>;
// Package manager configuration
type PackageManager = "yarn" | "npm";
function getPackageManager(): PackageManager;
function setPackageManager(packageManager: PackageManager): void;
// Authentication token management
interface TokenInfo {
token: string | null;
expiration?: string;
}
function getToken(): Promise<string>;
function setToken(token: string, expiration?: string): void;
// Authentication commands
function login(): Promise<void>;
function logout(): Promise<void>;
function whoami(): Promise<void>;
// Plugin management
interface IGatsbyPluginCreateInput {
root: string;
name: string;
options?: Record<string, unknown>;
key: string;
}
interface IPackageCreateInput {
root: string;
name: string;
}
function addPlugins(
plugins: string[],
pluginOptions: Record<string, unknown>,
directory: string,
packages: string[]
): Promise<void>;
// Reporter system for logging and progress
interface Reporter {
log(message: string): void;
info(message: string): void;
warn(message: string): void;
error(message: string | Error): void;
panic(message: string, error?: Error): never;
verbose(message: string): void;
success(message: string): void;
setVerbose(verbose: boolean): void;
setNoColor(noColor: boolean): void;
activityTimer(message: string): ActivityTimer;
createProgress(message: string): Progress;
stripIndent(template: TemplateStringsArray): string;
}
interface ActivityTimer {
start(): void;
end(): void;
setStatus(status: string): void;
}
interface Progress {
start(): void;
tick(): void;
done(): void;
set(message: string): void;
}
// Site information interface
interface ISiteInfo {
directory: string;
browserslist: Array<string>;
sitePackageJson: any;
}
// Version utilities
function getLocalGatsbyVersion(): string | undefined;