0
# Command Line Interface
1

2
Ice.js provides a powerful CLI for development and build operations with extensive configuration options and multi-platform support. The CLI is accessible through the `ice` command after installing `@ice/app`.
3

4
## Capabilities
5

6
### Build Command
7

8
Build the project for production with optimization and multi-platform support.
9

10
```typescript { .api }
11
ice build [options]
12
```
13

14
**Build Options:**
15

16
```typescript { .api }
17
interface BuildOptions {
18
  /** Build target platform */
19
  --target: 'web' | 'weex' | 'ali-miniapp' | 'wechat-miniprogram' | 
20
           'bytedance-microapp' | 'baidu-smartprogram' | 'kuaishou-miniprogram';
21
  /** Build mode */
22
  --mode: string; // default: 'production'
23
  /** Enable bundle analyzer visualization */
24
  --analyzer: boolean; // default: false
25
  /** Custom configuration file path */
26
  --config: string;
27
  /** Project root directory */
28
  --rootDir: string; // default: process.cwd()
29
  /** Add custom Ice.js plugin by npm package name */
30
  --plugin: string;
31
  /** Enable Rust-based build optimization */
32
  --speedup: boolean; // default: false
33
}
34
```
35

36
**Usage Examples:**
37

38
```bash
39
# Basic production build
40
ice build
41

42
# Build for specific platform
43
ice build --target ali-miniapp
44

45
# Build with bundle analysis
46
ice build --analyzer
47

48
# Build with custom config
49
ice build --config ./configs/ice.prod.config.ts
50

51
# Build with custom plugin
52
ice build --plugin @my-org/ice-plugin-custom
53

54
# Build with speedup mode for faster builds
55
ice build --speedup
56
```
57

58
### Start Command
59

60
Start the development server with hot reloading and comprehensive development features.
61

62
```typescript { .api }
63
ice start [options]
64
```
65

66
**Development Server Options:**
67

68
```typescript { .api }
69
interface StartOptions {
70
  /** Build target platform */
71
  --target: 'web' | 'weex' | 'ali-miniapp' | 'wechat-miniprogram' | 
72
           'bytedance-microapp' | 'baidu-smartprogram' | 'kuaishou-miniprogram';
73
  /** Development mode */
74
  --mode: string; // default: 'development'
75
  /** Custom configuration file path */
76
  --config: string;
77
  /** Development server host */
78
  --host: string; // -h shorthand
79
  /** Development server port */
80
  --port: number; // -p shorthand
81
  /** Disable automatic browser opening */
82
  --no-open: boolean;
83
  /** Disable mock service */
84
  --no-mock: boolean;
85
  /** Project root directory */
86
  --rootDir: string; // default: process.cwd()
87
  /** Enable bundle analyzer during development */
88
  --analyzer: boolean; // default: false
89
  /** Enable HTTPS server */
90
  --https: boolean | 'self-signed'; // default: false
91
  /** Force remove cache directory */
92
  --force: boolean; // default: false
93
  /** Enable Rust-based build optimization */
94
  --speedup: boolean; // default: false
95
  /** Open browser with specific route */
96
  --open: boolean | string; // default: true
97
  /** List all available pages */
98
  --list: boolean; // default: false
99
}
100
```
101

102
**Usage Examples:**
103

104
```bash
105
# Basic development server
106
ice start
107

108
# Start on specific host and port
109
ice start --host 0.0.0.0 --port 8080
110

111
# Start with HTTPS
112
ice start --https
113

114
# Start without opening browser
115
ice start --no-open
116

117
# Start with mock service disabled
118
ice start --no-mock
119

120
# Start with speedup mode (Rust tools)
121
ice start --speedup
122

123
# Start and open specific route
124
ice start --open /dashboard
125

126
# List all available pages
127
ice start --list
128

129
# Force cache clear and start
130
ice start --force
131

132
# Start miniapp development
133
ice start --target ali-miniapp
134
```
135

136
### Global Options
137

138
Options available for all commands.
139

140
```typescript { .api }
141
interface GlobalOptions {
142
  /** Show version number */
143
  --version: boolean; // -V shorthand
144
  /** Show help information */
145
  --help: boolean; // -h shorthand
146
}
147
```
148

149
**Usage Examples:**
150

151
```bash
152
# Show version
153
ice --version
154
ice -V
155

156
# Show help
157
ice --help
158
ice -h
159

160
# Show command-specific help
161
ice build --help
162
ice start --help
163
```
164

165
### Multi-Platform Targets
166

167
Ice.js supports multiple deployment targets through the `--target` option.
168

169
```typescript { .api }
170
type BuildTarget = 
171
  | 'web'                    // Standard web application (default)
172
  | 'weex'                   // Weex mobile framework
173
  | 'ali-miniapp'           // Alibaba Mini Program
174
  | 'wechat-miniprogram'    // WeChat Mini Program
175
  | 'bytedance-microapp'    // ByteDance Micro App
176
  | 'baidu-smartprogram'    // Baidu Smart Program
177
  | 'kuaishou-miniprogram'; // Kuaishou Mini Program
178
```
179

180
**Platform-Specific Examples:**
181

182
```bash
183
# Web development (default)
184
ice start
185
ice build
186

187
# WeChat Mini Program
188
ice start --target wechat-miniprogram
189
ice build --target wechat-miniprogram
190

191
# Alibaba Mini Program  
192
ice start --target ali-miniapp
193
ice build --target ali-miniapp --analyzer
194

195
# Weex mobile app
196
ice start --target weex --host 0.0.0.0
197
ice build --target weex --mode production
198
```
199

200
### Configuration File Resolution
201

202
The CLI automatically resolves configuration files in the following order:
203

204
```typescript { .api }
205
// Configuration file resolution order
206
const configFiles = [
207
  'ice.config.mts',  // TypeScript ES modules
208
  'ice.config.mjs',  // JavaScript ES modules  
209
  'ice.config.ts',   // TypeScript
210
  'ice.config.js',   // JavaScript
211
  'ice.config.cjs',  // CommonJS
212
  'ice.config.json'  // JSON
213
];
214
```
215

216
**Custom Configuration:**
217

218
```bash
219
# Use specific config file
220
ice build --config ./configs/production.config.ts
221
ice start --config ./configs/development.config.mjs
222

223
# Config files are resolved relative to rootDir
224
ice build --rootDir ./packages/web --config ice.config.ts
225
```
226

227
### Environment Variables
228

229
The CLI automatically sets and recognizes various environment variables.
230

231
```typescript { .api }
232
interface CLIEnvironmentVariables {
233
  /** Automatically set by CLI based on command */
234
  NODE_ENV: 'development' | 'production';
235
  /** Set by CLI with package version */
236
  __ICE_VERSION__: string;
237
  /** Custom environment variables from .env files */
238
  [key: string]: string;
239
}
240
```
241

242
**Environment File Support:**
243

244
```bash
245
# Environment files loaded in order of precedence
246
.env.local          # Local overrides (gitignored)
247
.env.development    # Development-specific
248
.env.production     # Production-specific  
249
.env                # Default environment
250
```
251

252
### Advanced CLI Usage
253

254
#### Plugin Integration
255

256
```bash
257
# Install and use custom plugins
258
npm install @my-org/ice-plugin-custom
259
ice build --plugin @my-org/ice-plugin-custom
260

261
# Multiple plugins (space-separated)
262
ice start --plugin plugin-one --plugin plugin-two
263
```
264

265
#### Development Workflow
266

267
```bash
268
# Full development setup
269
ice start --host 0.0.0.0 --port 3000 --https --analyzer --speedup
270

271
# Production build with analysis
272
ice build --analyzer --mode production
273

274
# Cross-platform development
275
ice start --target wechat-miniprogram --list
276
```
277

278
#### Debugging and Analysis
279

280
```bash
281
# Enable bundle analysis
282
ice build --analyzer
283
ice start --analyzer
284

285
# List all available routes
286
ice start --list
287

288
# Force cache clear for troubleshooting
289
ice start --force
290

291
# Use speedup mode for faster builds
292
ice start --speedup
293
ice build --speedup
294
```
295

296
#### CI/CD Integration
297

298
```bash
299
# Production build for CI
300
ice build --mode production --no-open
301

302
# Build specific platform for deployment
303
ice build --target ali-miniapp --config ./configs/miniapp.config.ts
304

305
# Build with custom root directory
306
ice build --rootDir ./packages/frontend --config ice.config.ts
307
```
308

309
### Command Exit Codes
310

311
```typescript { .api }
312
interface ExitCodes {
313
  0: 'Success';
314
  1: 'Build error or process failure';
315
}
316
```
317

318
The CLI will exit with code 1 on build failures to ensure proper CI/CD integration.
319

320
### Configuration Integration
321

322
All CLI options can be overridden by configuration files:
323

324
```typescript
325
// ice.config.ts
326
import { defineConfig } from "@ice/app";
327

328
export default defineConfig({
329
  // CLI --analyzer option can be overridden
330
  analyzer: process.env.ANALYZE === 'true',
331
  
332
  // CLI --target option default
333
  // (CLI option takes precedence)
334
  
335
  // Development server defaults
336
  // (CLI --host and --port take precedence)
337
  server: {
338
    host: 'localhost',
339
    port: 3000,
340
    https: false
341
  }
342
});
343
```
344

345
The precedence order is: CLI options > Configuration file > Default values.