0
# CLI Operations
1

2
Command-line interface providing development workflow tools including build, development server, inspection, and Module Federation support. The CLI is the primary interface for most Rslib operations.
3

4
## Capabilities
5

6
### CLI Entry Point
7

8
Main CLI entry point that processes command line arguments and routes to appropriate commands.
9

10
```typescript { .api }
11
/**
12
 * Main CLI entry point that processes command line arguments
13
 * Routes to appropriate commands based on arguments
14
 * Supports: build, dev, inspect, mf-dev, init
15
 */
16
function runCli(): void;
17
```
18

19
**Available Commands:**
20
- `rslib build` - Build the library
21
- `rslib dev` - Build in watch mode  
22
- `rslib inspect` - Inspect build configuration
23
- `rslib mf-dev` - Start Module Federation dev server
24
- `rslib init` - Initialize new project
25

26
**Usage Examples:**
27

28
```bash
29
# Build library
30
npx rslib build
31

32
# Build with watch mode
33
npx rslib dev
34

35
# Build specific libraries
36
npx rslib build --lib esm,cjs
37

38
# Inspect configuration
39
npx rslib inspect --verbose
40

41
# Start Module Federation dev server
42
npx rslib mf-dev
43
```
44

45
### CLI Preparation
46

47
Initializes CLI environment, sets up process handlers, and displays startup information.
48

49
```typescript { .api }
50
/**
51
 * Initializes CLI environment and sets up process handlers
52
 * Sets up graceful shutdown, error handling, and startup information
53
 */
54
function prepareCli(): void;
55
```
56

57
This function is typically called internally before CLI operations to ensure proper environment setup.
58

59
## CLI Options
60

61
### Common Options
62

63
Base options available across all CLI commands:
64

65
```typescript { .api }
66
interface CommonOptions {
67
  /** Project root directory */
68
  root?: string;
69
  /** Configuration file path */
70
  config?: string;
71
  /** Environment files directory */
72
  envDir?: string;
73
  /** Environment mode */
74
  envMode?: string;
75
  /** Library selection (array of library IDs or formats) */
76
  lib?: string[];
77
}
78
```
79

80
### Build Options
81

82
Options specific to build operations:
83

84
```typescript { .api }
85
interface BuildOptions extends CommonOptions {
86
  /** Enable watch mode for automatic rebuilds */
87
  watch?: boolean;
88
}
89
```
90

91
**Usage Examples:**
92

93
```bash
94
# Build with custom config
95
rslib build --config ./custom.config.js
96

97
# Build with watch mode
98
rslib build --watch
99

100
# Build specific libraries
101
rslib build --lib esm --lib cjs
102

103
# Build with custom root
104
rslib build --root ./packages/my-lib
105
```
106

107
### Inspect Options
108

109
Options for configuration inspection:
110

111
```typescript { .api }
112
interface InspectOptions extends CommonOptions {
113
  /** Build mode (development or production) */
114
  mode?: RsbuildMode;
115
  /** Output directory for inspection results */
116
  output?: string;
117
  /** Enable verbose output */
118
  verbose?: boolean;
119
}
120
```
121

122
**Usage Examples:**
123

124
```bash
125
# Basic inspection
126
rslib inspect
127

128
# Inspect with verbose output
129
rslib inspect --verbose
130

131
# Inspect production mode
132
rslib inspect --mode production
133

134
# Inspect with custom output
135
rslib inspect --output ./inspect-results
136
```
137

138
## CLI Integration
139

140
### Programmatic CLI Usage
141

142
While CLI commands are typically run from the command line, you can also invoke CLI functionality programmatically:
143

144
```typescript
145
import { runCli, prepareCli } from "@rslib/core";
146

147
// Set up CLI environment
148
prepareCli();
149

150
// Run CLI with programmatic arguments
151
process.argv = ["node", "rslib", "build", "--watch"];
152
runCli();
153
```
154

155
### Environment Variables
156

157
The CLI respects several environment variables:
158

159
- `NODE_ENV` - Sets the build environment
160
- `RSLIB_LOG_LEVEL` - Controls logging verbosity
161
- `RSLIB_CONFIG` - Default configuration file path
162

163
### Configuration File Discovery
164

165
The CLI automatically discovers configuration files in this order:
166

167
1. `--config` CLI argument
168
2. `rslib.config.js`
169
3. `rslib.config.mjs`
170
4. `rslib.config.ts`
171
5. `rslib.config.mts`
172

173
## CLI Commands Detail
174

175
### Build Command
176

177
Compiles the library according to the configuration:
178

179
```bash
180
rslib build [options]
181

182
Options:
183
  --watch, -w          Watch for changes and rebuild
184
  --config, -c <file>  Configuration file path
185
  --root <dir>         Project root directory
186
  --lib <libs...>      Build specific libraries
187
  --env-mode <mode>    Environment mode
188
  --env-dir <dir>      Environment files directory
189
```
190

191
### Dev Command
192

193
Builds the library in watch mode (alias for `build --watch`):
194

195
```bash
196
rslib dev [options]
197

198
# Equivalent to:
199
rslib build --watch [options]
200
```
201

202
### Inspect Command
203

204
Analyzes and outputs the build configuration:
205

206
```bash
207
rslib inspect [options]
208

209
Options:
210
  --mode <mode>        Build mode (development|production)
211
  --output, -o <dir>   Output directory
212
  --verbose, -v        Verbose output
213
  --config, -c <file>  Configuration file path
214
  --root <dir>         Project root directory
215
  --lib <libs...>      Inspect specific libraries
216
```
217

218
### Module Federation Dev Command
219

220
Starts a development server for Module Federation builds:
221

222
```bash
223
rslib mf-dev [options]
224

225
Options:
226
  --config, -c <file>  Configuration file path
227
  --root <dir>         Project root directory
228
  --lib <libs...>      Serve specific libraries
229
  --env-mode <mode>    Environment mode
230
```
231

232
### Init Command
233

234
Initializes a new Rslib project with interactive setup:
235

236
```bash
237
rslib init [project-name]
238

239
Options:
240
  [project-name]        Name of the project to create
241

242
# Interactive project setup
243
rslib init my-library
244

245
# Create project in current directory
246
rslib init
247
```
248

249
The init command provides an interactive CLI to create a new Rslib project with:
250
- Project template selection (Node.js, React, Vue, etc.)
251
- TypeScript/JavaScript choice
252
- Package manager selection
253
- Output format configuration
254

255
## CLI Error Handling
256

257
The CLI provides comprehensive error handling and reporting:
258

259
- **Configuration Errors**: Clear messages for invalid configurations
260
- **Build Errors**: Detailed compilation error reporting with file locations
261
- **Validation Errors**: Type checking and validation error details
262
- **Process Errors**: Graceful handling of interruptions and cleanup
263

264
## Logging and Debug
265

266
The CLI includes built-in logging capabilities:
267

268
```typescript { .api }
269
const logger: Logger;
270
```
271

272
**Log Levels:**
273
- `debug` - Detailed debugging information
274
- `info` - General information
275
- `warn` - Warning messages
276
- `error` - Error messages
277

278
**Environment Variables:**
279
- `DEBUG=rslib` - Enable debug logging
280
- `RSLIB_LOG_LEVEL=debug` - Set specific log level
281

282
**Usage:**
283

284
```bash
285
# Enable debug logging
286
DEBUG=rslib rslib build
287

288
# Set log level
289
RSLIB_LOG_LEVEL=verbose rslib build
290
```