0
# CLI Commands
1

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

4
## Capabilities
5

6
### Run Command
7

8
Execute custom generators with optional configuration and arguments.
9

10
```typescript { .api }
11
/**
12
 * Run custom generators
13
 * Command: npx @turbo/gen run [generator-name]
14
 * Alias: r
15
 */
16
run [generator-name] --config <config> --root <dir> --args <args...>
17
```
18

19
**Options:**
20
- `[generator-name]` - Optional name of the generator to run
21
- `-c, --config <config>` - Generator configuration file (default: turbo/generators/config.js)
22
- `-r, --root <dir>` - Repository root directory (default: directory with root turbo.json)
23
- `-a, --args <args...>` - Arguments passed directly to the generator
24

25
**Usage Examples:**
26

27
```bash
28
# Run with interactive generator selection
29
npx @turbo/gen run
30

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

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

37
# Run with arguments
38
npx @turbo/gen run my-generator --args name=Button type=component
39
```
40

41
### Workspace Command
42

43
Create new packages or apps in your Turborepo monorepo.
44

45
```typescript { .api }
46
/**
47
 * Add a new package or app to your project
48
 * Command: npx @turbo/gen workspace
49
 * Alias: w
50
 */
51
workspace --name <name> --type <type> --empty|--copy [source] --destination <dir>
52
```
53

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

64
**Usage Examples:**
65

66
```bash
67
# Create empty package
68
npx @turbo/gen workspace --name my-package --type package --empty
69

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

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

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

80
### Raw Command
81

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

84
```typescript { .api }
85
/**
86
 * Internal command for JSON arguments processing
87
 * Command: npx @turbo/gen raw <type>
88
 * Hidden command - not shown in help
89
 */
90
raw <type> --json <arguments>
91
```
92

93
**Options:**
94
- `<type>` - Required generator type
95
- `--json <arguments>` - Arguments as raw JSON string
96

97
**Usage Examples:**
98

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

104
## Interactive Prompts
105

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

108
### Run Command Prompts
109

110
**Generator Selection:**
111
```typescript { .api }
112
interface GeneratorPrompt {
113
  selectedGenerator: string;
114
}
115
```
116

117
**Template Choice (for new generator setup):**
118
```typescript { .api }
119
interface TemplatePrompt {
120
  answer: "ts" | "js";
121
}
122
```
123

124
### Workspace Command Prompts
125

126
**Workspace Name:**
127
```typescript { .api }
128
interface NamePrompt {
129
  answer: string;
130
}
131
```
132

133
**Workspace Type:**
134
```typescript { .api }
135
interface TypePrompt {
136
  answer: WorkspaceType; // "app" | "package"
137
}
138
```
139

140
**Location Selection:**
141
```typescript { .api }
142
interface LocationPrompt {
143
  absolute: string;
144
  relative: string;
145
}
146
```
147

148
**Source Workspace (for copying):**
149
```typescript { .api }
150
interface SourcePrompt {
151
  answer: Workspace;
152
}
153
```
154

155
**Dependencies Selection:**
156
```typescript { .api }
157
interface DependencyGroups {
158
  dependencies: string[];
159
  devDependencies: string[];
160
  peerDependencies: string[];
161
}
162
```
163

164
## Global Options
165

166
All commands support these global options:
167

168
- `-v, --version` - Output the current version
169
- `-h, --help` - Display help for command
170

171
## Error Handling
172

173
CLI commands throw `GeneratorError` instances for known error conditions:
174

175
```typescript { .api }
176
class GeneratorError extends Error {
177
  public type: GenerateErrorType;
178
  constructor(message: string, opts?: GeneratorErrorOptions);
179
}
180

181
type GenerateErrorType =
182
  | "plop_error_running_generator"
183
  | "plop_unable_to_load_config"
184
  | "plop_generator_not_found"
185
  | "plop_no_config"
186
  | "config_directory_already_exists"
187
  | "unknown";
188
```
189

190
Common error scenarios:
191
- Missing or invalid generator configuration
192
- Generator execution failures
193
- Invalid workspace names or destinations
194
- Network failures when copying from external sources
195
- Permission issues when creating directories or files