0
# Command Line Interface
1

2
CLI command creation and management with Commander.js integration for generator commands and environment interaction.
3

4
## Capabilities
5

6
### YeomanCommand Class
7

8
Extended Commander class with Yeoman-specific functionality for handling generator options and arguments.
9

10
```typescript { .api }
11
/**
12
 * Extended Commander class with Yeoman-specific functionality
13
 */
14
class YeomanCommand extends Command {
15
  /** Environment instance associated with this command */
16
  env?: BaseEnvironment;
17

18
  /**
19
   * Create sub-command with YeomanCommand type
20
   * @param name - Optional command name
21
   * @returns New YeomanCommand instance
22
   */
23
  createCommand(name?: string): YeomanCommand;
24

25
  /**
26
   * Add option with automatic negative alternative creation
27
   * @param option - Commander Option instance
28
   * @returns This command for chaining
29
   */
30
  addOption(option: Option): YeomanCommand;
31

32
  /**
33
   * Register generator options and arguments with the command
34
   * @param generator - Generator instance with _options and _arguments
35
   * @returns This command for chaining
36
   */
37
  registerGenerator(generator: any): YeomanCommand;
38

39
  /**
40
   * Add generator arguments to command
41
   * @param generatorArgs - Array of generator argument definitions
42
   * @returns This command for chaining
43
   */
44
  addGeneratorArguments(generatorArgs: any[]): YeomanCommand;
45

46
  /**
47
   * Add generator options to command
48
   * @param options - Object mapping option names to definitions
49
   * @returns This command for chaining
50
   */
51
  addGeneratorOptions(options: Record<string, any>): YeomanCommand;
52
}
53
```
54

55
**Usage Examples:**
56

57
```typescript
58
import { YeomanCommand } from "yeoman-environment";
59

60
// Create command with Yeoman extensions
61
const command = new YeomanCommand("generate");
62

63
// Add environment-aware options
64
command.option("--skip-install", "Skip dependency installation");
65

66
// Register generator options
67
const generator = await env.get("webapp:app");
68
command.registerGenerator(generator);
69

70
// Create sub-command
71
const subCommand = command
72
  .createCommand("component")
73
  .description("Generate a component");
74
```
75

76
### Environment Options
77

78
Add standard environment options to any command.
79

80
```typescript { .api }
81
/**
82
 * Add standard environment options to a command
83
 * @param command - Command to add options to (defaults to new YeomanCommand)
84
 * @returns Command with environment options added
85
 */
86
function addEnvironmentOptions(command?: YeomanCommand): YeomanCommand;
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import { addEnvironmentOptions, YeomanCommand } from "yeoman-environment";
93

94
// Add to existing command
95
const command = new YeomanCommand("generate");
96
addEnvironmentOptions(command);
97

98
// Create new command with options
99
const envCommand = addEnvironmentOptions();
100

101
// Chain with other options
102
const fullCommand = addEnvironmentOptions(new YeomanCommand("build"))
103
  .option("--production", "Build for production")
104
  .option("--watch", "Watch for changes");
105
```
106

107
**Standard Environment Options Added:**
108

109
- `--cwd` - Path to use as current directory
110
- `--skip-install` - Do not automatically install dependencies
111
- `--skip-cache` - Do not remember prompt answers
112
- `--local-config-only` - Generate .yo-rc-global.json locally
113
- `--ask-answered` - Show prompts for already configured options
114
- `--force` - Override every file
115
- `--dry-run` - Print conflicts without applying
116
- `--whitespace` - Whitespace changes will not trigger conflicts
117
- `--bail` - Fail on first conflict
118
- `--skip-yo-resolve` - Ignore .yo-resolve files
119

120
### Command Preparation
121

122
Prepare Commander instances for CLI support with generator integration.
123

124
```typescript { .api }
125
/**
126
 * Prepare a commander instance for CLI support with generator integration
127
 * @param options - Command preparation configuration
128
 * @returns Configured YeomanCommand instance
129
 */
130
function prepareGeneratorCommand(options: CommandPreparation): Promise<YeomanCommand>;
131

132
/**
133
 * Prepare a commander instance for CLI support
134
 * @param options - Command preparation configuration
135
 * @returns Configured YeomanCommand instance
136
 */
137
function prepareCommand(options: CommandPreparation): Promise<YeomanCommand>;
138

139
interface CommandPreparation {
140
  /** Generator file path or module path */
141
  resolved?: string;
142
  /** Command instance to configure */
143
  command?: YeomanCommand;
144
  /** Generator constructor to use */
145
  generator?: BaseGeneratorConstructor;
146
  /** Generator namespace */
147
  namespace?: string;
148
}
149
```
150

151
**Usage Examples:**
152

153
```typescript
154
import { prepareCommand, prepareGeneratorCommand } from "yeoman-environment";
155

156
// Prepare command for specific generator
157
const command1 = await prepareGeneratorCommand({
158
  resolved: "./generators/app/index.js",
159
  namespace: "myapp:app"
160
});
161

162
// Prepare with generator constructor
163
const command2 = await prepareGeneratorCommand({
164
  generator: MyGeneratorClass,
165
  namespace: "myapp:component"
166
});
167

168
// Prepare basic command
169
const command3 = await prepareCommand({
170
  resolved: "generator-webapp/generators/app",
171
  namespace: "webapp:app"
172
});
173

174
// Use prepared command
175
command1.action(async function() {
176
  console.log("Running generator with args:", this.args);
177
  console.log("Running generator with options:", this.opts());
178
});
179
```
180

181
## Built-in CLI Binary
182

183
The package includes a `yoe` CLI binary for direct generator interaction.
184

185
### yoe Commands
186

187
```bash
188
# Run a generator
189
yoe run <namespace> [generator-options]
190

191
# Find installed generators
192
yoe find
193

194
# List available generators
195
yoe list
196

197
# Get help
198
yoe --help
199
```
200

201
**Examples:**
202

203
```bash
204
# Run webapp generator
205
yoe run webapp:app MyProject --skip-install
206

207
# Run with environment options
208
yoe run angular:component UserCard --force --dry-run
209

210
# Find all installed generators
211
yoe find
212

213
# List registered generators
214
yoe list
215
```
216

217
### CLI Integration Example
218

219
Complete example of CLI integration with custom commands:
220

221
```typescript
222
import { Command } from "commander";
223
import { 
224
  createEnv, 
225
  addEnvironmentOptions, 
226
  YeomanCommand,
227
  prepareGeneratorCommand 
228
} from "yeoman-environment";
229

230
// Create main program
231
const program = new YeomanCommand();
232
program.version("1.0.0");
233

234
// Add generate command
235
const generateCommand = addEnvironmentOptions(
236
  program
237
    .command("generate <type>")
238
    .description("Generate code")
239
    .argument("<type>", "Type of code to generate")
240
);
241

242
generateCommand.action(async function(type, options) {
243
  const env = createEnv({ ...options, command: this });
244
  
245
  this.env = env;
246
  await env.lookupLocalPackages();
247
  
248
  // Execute generator based on type
249
  await env.execute(`myapp:${type}`, this.args.slice(1));
250
});
251

252
// Add generator-specific commands
253
const componentCommand = await prepareGeneratorCommand({
254
  resolved: "./generators/component/index.js",
255
  namespace: "myapp:component"
256
});
257

258
program.addCommand(componentCommand.name("component"));
259

260
// Parse arguments
261
await program.parseAsync(process.argv);
262
```
263

264
## Advanced CLI Patterns
265

266
### Dynamic Command Registration
267

268
```typescript
269
import { createEnv, YeomanCommand, addEnvironmentOptions } from "yeoman-environment";
270

271
async function createDynamicCLI() {
272
  const env = createEnv();
273
  const program = new YeomanCommand();
274
  
275
  // Discover generators
276
  const generators = await env.lookup();
277
  
278
  // Create commands for each generator
279
  for (const meta of generators) {
280
    const command = addEnvironmentOptions(
281
      program
282
        .command(meta.namespace.replace(":", "-"))
283
        .description(`Run ${meta.namespace} generator`)
284
    );
285
    
286
    command.action(async function() {
287
      await env.execute(meta.namespace, this.args);
288
    });
289
  }
290
  
291
  return program;
292
}
293

294
// Usage
295
const cli = await createDynamicCLI();
296
await cli.parseAsync(process.argv);
297
```
298

299
### Custom Environment Integration
300

301
```typescript
302
import { YeomanCommand, createEnv } from "yeoman-environment";
303

304
class CustomCommand extends YeomanCommand {
305
  constructor() {
306
    super();
307
    this.env = createEnv({
308
      // Custom environment options
309
      skipInstall: true,
310
      adapter: myCustomAdapter
311
    });
312
  }
313
  
314
  async executeGenerator(namespace: string, args: string[]) {
315
    await this.env!.lookup();
316
    return this.env!.execute(namespace, args);
317
  }
318
}
319

320
const customCLI = new CustomCommand()
321
  .command("build <generator>")
322
  .action(async function(generator, options) {
323
    await this.executeGenerator(`myapp:${generator}`, this.args.slice(1));
324
  });
325
```
326

327
## CLI Configuration Types
328

329
```typescript { .api }
330
interface CommandPreparation {
331
  /** Generator file path or module path */
332
  resolved?: string;
333
  /** Command instance to configure */
334
  command?: YeomanCommand;
335
  /** Generator constructor to use */
336
  generator?: BaseGeneratorConstructor;
337
  /** Generator namespace */
338
  namespace?: string;
339
}
340

341
interface GeneratorOptionDefinition {
342
  /** Option description */
343
  description: string;
344
  /** Option type (String, Boolean, Array, etc.) */
345
  type: any;
346
  /** Default value */
347
  default?: any;
348
  /** Short alias */
349
  alias?: string;
350
  /** Whether option is required */
351
  required?: boolean;
352
  /** Hide from help */
353
  hide?: boolean;
354
}
355

356
interface GeneratorArgumentDefinition {
357
  /** Argument name */
358
  name: string;
359
  /** Argument type */
360
  type: any;
361
  /** Whether argument is required */
362
  required: boolean;
363
  /** Argument description */
364
  description?: string;
365
}
366
```