CLI Commands

Command-line interface for Turbo Gen providing three main commands for generator execution and workspace creation.

Capabilities

Run Command

Execute custom generators with optional configuration and arguments.

/**
 * Run custom generators
 * Command: npx @turbo/gen run [generator-name]
 * Alias: r
 */
run [generator-name] --config <config> --root <dir> --args <args...>

Options:

• [generator-name] - Optional name of the generator to run
• -c, --config <config> - Generator configuration file (default: turbo/generators/config.js)
• -r, --root <dir> - Repository root directory (default: directory with root turbo.json)
• -a, --args <args...> - Arguments passed directly to the generator

Usage Examples:

# Run with interactive generator selection
npx @turbo/gen run

# Run specific generator
npx @turbo/gen run my-component

# Run with custom config
npx @turbo/gen run --config ./custom-generators/config.js

# Run with arguments
npx @turbo/gen run my-generator --args name=Button type=component

Workspace Command

Create new packages or apps in your Turborepo monorepo.

/**
 * Add a new package or app to your project
 * Command: npx @turbo/gen workspace
 * Alias: w
 */
workspace --name <name> --type <type> --empty|--copy [source] --destination <dir>

Options:

• -n, --name <workspace-name> - Name for the new workspace
• -b, --empty - Generate an empty workspace (default: true, conflicts with --copy)
• -c, --copy [source] - Generate using existing workspace as template (conflicts with --empty)
• -d, --destination <dir> - Where the new workspace should be created
• -t, --type <type> - Workspace type (choices: "app", "package")
• -r, --root <dir> - Repository root directory
• -p, --example-path <path> - Path to example for GitHub URLs with slash in branch names
• --show-all-dependencies - Don't filter available dependencies by workspace type (default: false)

Usage Examples:

# Create empty package
npx @turbo/gen workspace --name my-package --type package --empty

# Copy existing workspace
npx @turbo/gen workspace --name new-app --type app --copy existing-app

# Copy from GitHub
npx @turbo/gen workspace --name ui-lib --copy https://github.com/vercel/turborepo/tree/main/examples/basic

# Copy with custom destination
npx @turbo/gen workspace --name shared-ui --type package --copy ui-components --destination packages/ui

Raw Command

Internal command for processing JSON arguments (hidden from help).

/**
 * Internal command for JSON arguments processing
 * Command: npx @turbo/gen raw <type>
 * Hidden command - not shown in help
 */
raw <type> --json <arguments>

Options:

• <type> - Required generator type
• --json <arguments> - Arguments as raw JSON string

Usage Examples:

# Internal usage - typically called by other tools
npx @turbo/gen raw workspace --json '{"name":"my-pkg","type":"package","empty":true}'

Interactive Prompts

When options are not provided via CLI flags, Turbo Gen provides interactive prompts:

Run Command Prompts

Generator Selection:

interface GeneratorPrompt {
  selectedGenerator: string;
}

Template Choice (for new generator setup):

interface TemplatePrompt {
  answer: "ts" | "js";
}

Workspace Command Prompts

Workspace Name:

interface NamePrompt {
  answer: string;
}

Workspace Type:

interface TypePrompt {
  answer: WorkspaceType; // "app" | "package"
}

Location Selection:

interface LocationPrompt {
  absolute: string;
  relative: string;
}

Source Workspace (for copying):

interface SourcePrompt {
  answer: Workspace;
}

Dependencies Selection:

interface DependencyGroups {
  dependencies: string[];
  devDependencies: string[];
  peerDependencies: string[];
}

Global Options

All commands support these global options:

• -v, --version - Output the current version
• -h, --help - Display help for command

Error Handling

CLI commands throw GeneratorError instances for known error conditions:

class GeneratorError extends Error {
  public type: GenerateErrorType;
  constructor(message: string, opts?: GeneratorErrorOptions);
}

type GenerateErrorType =
  | "plop_error_running_generator"
  | "plop_unable_to_load_config"
  | "plop_generator_not_found"
  | "plop_no_config"
  | "config_directory_already_exists"
  | "unknown";

Common error scenarios:

• Missing or invalid generator configuration
• Generator execution failures
• Invalid workspace names or destinations
• Network failures when copying from external sources
• Permission issues when creating directories or files