0
# CLI and Service Management
1

2
Command-line interface and service management for running development servers, building applications, and executing framework commands.
3

4
## Capabilities
5

6
### CLI Runner
7

8
Main entry point for executing umi commands from the command line or programmatically.
9

10
```typescript { .api }
11
/**
12
 * Main CLI runner that handles all umi commands
13
 * @param opts - Optional configuration for CLI execution
14
 * @returns Promise that resolves when command execution completes
15
 */
16
function run(opts?: IOpts): Promise<void>;
17

18
interface IOpts {
19
  presets?: string[]; // Additional presets to load
20
}
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { run } from "umi";
27

28
// Run CLI programmatically with default settings
29
await run();
30

31
// Run with custom presets
32
await run({
33
  presets: ["@umijs/preset-react", "./custom-preset"],
34
});
35
```
36

37
**Command Line Usage:**
38

39
```bash
40
# Development server
41
umi dev
42

43
# Production build
44
umi build
45

46
# Show version
47
umi -v
48
umi --version
49

50
# Show help
51
umi -h
52
umi --help
53

54
# Feature commands
55
umi setup
56
umi mfsu
57
umi deadcode
58
```
59

60
### Service Class
61

62
Core service class that extends the base CoreService with umi-specific functionality and configuration.
63

64
```typescript { .api }
65
/**
66
 * Main service class that manages application lifecycle, plugins, and configuration
67
 */
68
class Service extends CoreService {
69
  /**
70
   * Creates a new umi service instance
71
   * @param opts - Optional service configuration
72
   */
73
  constructor(opts?: ServiceOpts);
74

75
  /**
76
   * Enhanced run method with command preprocessing and error handling
77
   * @param opts - Command execution options
78
   * @returns Promise that resolves when command execution completes
79
   */
80
  run2(opts: RunOpts): Promise<any>;
81
}
82

83
interface ServiceOpts {
84
  cwd?: string; // Working directory
85
  defaultConfigFiles?: string[]; // Configuration file patterns
86
  frameworkName?: string; // Framework name override
87
  presets?: string[]; // Additional presets to load
88
  plugins?: string[]; // Additional plugins to load
89
}
90

91
interface RunOpts {
92
  name: string; // Command name to execute
93
  args?: any; // Command arguments
94
}
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import { Service } from "umi";
101

102
// Create service with default configuration
103
const service = new Service();
104

105
// Run specific command
106
await service.run2({
107
  name: "build",
108
  args: { analyze: true },
109
});
110

111
// Create service with custom options
112
const customService = new Service({
113
  cwd: "/path/to/project",
114
  frameworkName: "my-framework",
115
  presets: ["./custom-preset"],
116
});
117

118
// Run development server
119
await customService.run2({
120
  name: "dev",
121
  args: { port: 3001 },
122
});
123
```
124

125
### Development Server
126

127
Special handling for development server with support for forked processes and hot reloading.
128

129
```typescript { .api }
130
/**
131
 * Development server runner with forked process support
132
 * Automatically called when running 'umi dev' command
133
 */
134
function dev(): void;
135
```
136

137
The development server provides:
138

139
- Hot module replacement (HMR)
140
- Live reloading
141
- Mock API support
142
- Plugin system integration
143
- Forked process execution for performance
144

145
## Service Configuration
146

147
### Default Service Setup
148

149
The Service class automatically configures itself with:
150

151
```typescript
152
// Environment setup
153
process.env.UMI_DIR = dirname(require.resolve('../../package'));
154

155
// Working directory resolution
156
const cwd = getCwd();
157

158
// Configuration file discovery
159
const defaultConfigFiles = [
160
  '.umirc.ts',
161
  '.umirc.js', 
162
  'config/config.ts',
163
  'config/config.js'
164
];
165

166
// Preset loading
167
const presets = [
168
  require.resolve('@umijs/preset-umi'),
169
  ...customPresets
170
];
171

172
// Plugin discovery
173
const plugins = [
174
  // Auto-discover plugin.ts or plugin.js in project root
175
  existsSync(join(cwd, 'plugin.ts')) && join(cwd, 'plugin.ts'),
176
  existsSync(join(cwd, 'plugin.js')) && join(cwd, 'plugin.js'),
177
].filter(Boolean);
178
```
179

180
### Command Processing
181

182
Commands are processed with automatic handling for:
183

184
- Version requests (`-v`, `--version`, `v`)
185
- Help requests (`-h`, `--help`, or no command)
186
- Environment variable setup based on command type
187
- Error handling and graceful exit
188

189
## Type Definitions
190

191
```typescript { .api }
192
// CLI options interface
193
interface IOpts {
194
  presets?: string[];
195
}
196

197
// Service constructor options
198
interface ServiceOpts {
199
  cwd?: string;
200
  defaultConfigFiles?: string[];
201
  frameworkName?: string;
202
  presets?: string[];
203
  plugins?: string[];
204
  env?: string;
205
}
206

207
// Run command options
208
interface RunOpts {
209
  name: string;
210
  args?: any;
211
}
212
```