or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-system.mdcloud-authentication.mdconfiguration-management.mddevelopment-server.mdindex.mdplugin-management.mdproject-management.md
tile.json

tessl/npm-gatsby-cli

Command-line interface for creating, developing, building and managing Gatsby static sites

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gatsby-cli@5.14.x

To install, run

npx @tessl/cli install tessl/npm-gatsby-cli@5.14.0

index.mddocs/

Gatsby CLI

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.

Package Information

  • Package Name: gatsby-cli
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install -g gatsby-cli or npx gatsby

Core Imports

For 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");

Basic Usage

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 --help

Architecture

Gatsby CLI is built around several key components:

  • Command System: Yargs-based CLI with local and global commands
  • Local Command Resolution: Automatically resolves to project-specific Gatsby commands when in a Gatsby site
  • Reporter System: Comprehensive logging, progress tracking, and error handling
  • Project Scaffolding: Interactive project creation with starter templates and CMS integration
  • Cloud Integration: Optional Gatsby Cloud authentication and management
  • Plugin Management: Tools for installing and managing Gatsby plugins

Capabilities

Project Management

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 context

Project Management

Development Server

Development 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)
}

Development Server

Build System

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)
}

Build System

Plugin Management

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 plugins

Plugin Management

Cloud Authentication

Integration 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 user

Cloud Authentication

Configuration Management

CLI 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
}

Configuration Management

Global Options

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
}

Core Types

// 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;