0
# CLI and Build System
1

2
Command-line interface types for Slidev's build, export, and development commands.
3

4
## Capabilities
5

6
### Common Arguments Interface
7

8
Base interface for common command-line arguments.
9

10
```typescript { .api }
11
/**
12
 * Common arguments interface for CLI commands
13
 */
14
interface CommonArgs {
15
  /** Entry file path for the presentation */
16
  entry: string;
17
  /** Theme name to use for the presentation */
18
  theme?: string;
19
}
20
```
21

22
### Export Arguments Interface
23

24
Arguments interface for export commands.
25

26
```typescript { .api }
27
/**
28
 * Export command arguments interface
29
 */
30
interface ExportArgs extends CommonArgs {
31
  /** Output file or directory path */
32
  'output'?: string;
33
  /** Export format (pdf, png, md, etc.) */
34
  'format'?: string;
35
  /** Timeout for export operations in milliseconds */
36
  'timeout'?: number;
37
  /** Wait time before capturing in milliseconds */
38
  'wait'?: number;
39
  /** Wait until condition for export */
40
  'wait-until'?: string;
41
  /** Page range for export (e.g., "1-5,8,10-12") */
42
  'range'?: string;
43
  /** Use dark theme for export */
44
  'dark'?: boolean;
45
  /** Include click animations in export */
46
  'with-clicks'?: boolean;
47
  /** Path to executable for export engine */
48
  'executable-path'?: string;
49
  /** Include table of contents in export */
50
  'with-toc'?: boolean;
51
  /** Export each slide as separate file */
52
  'per-slide'?: boolean;
53
  /** Scale factor for export output */
54
  'scale'?: number;
55
  /** Omit background in export */
56
  'omit-background'?: boolean;
57
}
58
```
59

60
### Build Arguments Interface
61

62
Arguments interface for build commands.
63

64
```typescript { .api }
65
/**
66
 * Build command arguments interface
67
 */
68
interface BuildArgs extends ExportArgs {
69
  /** Output directory for built files */
70
  out: string;
71
  /** Base URL for the built application */
72
  base?: string;
73
  /** Enable download functionality in build */
74
  download?: boolean;
75
  /** Enable Vite inspect plugin */
76
  inspect: boolean;
77
}
78
```
79

80
## Usage Examples
81

82
**CLI Command Type Usage:**
83

84
```typescript
85
import type { CommonArgs, ExportArgs, BuildArgs } from "@slidev/types";
86

87
// Function using common arguments
88
function processEntry(args: CommonArgs) {
89
  console.log(`Processing entry: ${args.entry}`);
90
  if (args.theme) {
91
    console.log(`Using theme: ${args.theme}`);
92
  }
93
}
94

95
// Function for export operations
96
function handleExport(args: ExportArgs) {
97
  processEntry(args);
98
  
99
  const options = {
100
    output: args.output || './output',
101
    format: args.format || 'pdf',
102
    timeout: args.timeout || 30000,
103
    darkTheme: args.dark || false,
104
    includeClicks: args['with-clicks'] || false
105
  };
106
  
107
  console.log('Export options:', options);
108
  
109
  if (args.range) {
110
    console.log(`Exporting pages: ${args.range}`);
111
  }
112
  
113
  if (args['per-slide']) {
114
    console.log('Exporting each slide separately');
115
  }
116
}
117

118
// Function for build operations
119
function handleBuild(args: BuildArgs) {
120
  handleExport(args);
121
  
122
  console.log(`Building to: ${args.out}`);
123
  
124
  if (args.base) {
125
    console.log(`Base URL: ${args.base}`);
126
  }
127
  
128
  if (args.download) {
129
    console.log('Download functionality enabled');
130
  }
131
  
132
  if (args.inspect) {
133
    console.log('Vite inspect plugin enabled');
134
  }
135
}
136
```
137

138
**Command Validation:**
139

140
```typescript
141
function validateExportArgs(args: Partial<ExportArgs>): args is ExportArgs {
142
  if (!args.entry) {
143
    throw new Error('Entry file is required');
144
  }
145
  
146
  if (args.timeout && args.timeout < 1000) {
147
    console.warn('Timeout less than 1 second may cause issues');
148
  }
149
  
150
  if (args.scale && (args.scale < 0.1 || args.scale > 5)) {
151
    throw new Error('Scale must be between 0.1 and 5');
152
  }
153
  
154
  if (args.range && !isValidRange(args.range)) {
155
    throw new Error('Invalid page range format');
156
  }
157
  
158
  return true;
159
}
160

161
function isValidRange(range: string): boolean {
162
  // Simple validation for range format like "1-5,8,10-12"
163
  const rangePattern = /^(\d+(-\d+)?)(,\d+(-\d+)?)*$/;
164
  return rangePattern.test(range);
165
}
166
```
167

168
**CLI Parser Integration:**
169

170
```typescript
171
interface CLIConfig {
172
  dev: CommonArgs & {
173
    port?: number;
174
    host?: string;
175
    open?: boolean;
176
  };
177
  build: BuildArgs;
178
  export: ExportArgs;
179
}
180

181
function parseCliArgs(command: keyof CLIConfig, rawArgs: string[]): CLIConfig[typeof command] {
182
  const args: any = {};
183
  
184
  for (let i = 0; i < rawArgs.length; i++) {
185
    const arg = rawArgs[i];
186
    
187
    if (arg.startsWith('--')) {
188
      const key = arg.slice(2);
189
      const value = rawArgs[i + 1];
190
      
191
      // Handle boolean flags
192
      if (!value || value.startsWith('--')) {
193
        args[key] = true;
194
      } else {
195
        // Handle typed values
196
        if (key === 'timeout' || key === 'wait' || key === 'scale') {
197
          args[key] = parseFloat(value);
198
        } else if (key === 'dark' || key === 'with-clicks' || key === 'per-slide' || 
199
                   key === 'with-toc' || key === 'omit-background' || key === 'inspect') {
200
          args[key] = true;
201
        } else {
202
          args[key] = value;
203
        }
204
        i++; // Skip the value
205
      }
206
    } else if (!args.entry) {
207
      args.entry = arg;
208
    }
209
  }
210
  
211
  return args;
212
}
213
```
214

215
**Export Options Builder:**
216

217
```typescript
218
class ExportOptionsBuilder {
219
  private options: Partial<ExportArgs> = {};
220
  
221
  entry(path: string): this {
222
    this.options.entry = path;
223
    return this;
224
  }
225
  
226
  theme(name: string): this {
227
    this.options.theme = name;
228
    return this;
229
  }
230
  
231
  output(path: string): this {
232
    this.options.output = path;
233
    return this;
234
  }
235
  
236
  format(fmt: string): this {
237
    this.options.format = fmt;
238
    return this;
239
  }
240
  
241
  timeout(ms: number): this {
242
    this.options.timeout = ms;
243
    return this;
244
  }
245
  
246
  range(pageRange: string): this {
247
    this.options.range = pageRange;
248
    return this;
249
  }
250
  
251
  withClicks(enabled = true): this {
252
    this.options['with-clicks'] = enabled;
253
    return this;
254
  }
255
  
256
  darkMode(enabled = true): this {
257
    this.options.dark = enabled;
258
    return this;
259
  }
260
  
261
  scale(factor: number): this {
262
    this.options.scale = factor;
263
    return this;
264
  }
265
  
266
  build(): ExportArgs {
267
    if (!this.options.entry) {
268
      throw new Error('Entry is required');
269
    }
270
    return this.options as ExportArgs;
271
  }
272
}
273

274
// Usage
275
const exportOptions = new ExportOptionsBuilder()
276
  .entry('./slides.md')
277
  .theme('academic')
278
  .format('pdf')
279
  .withClicks(true)
280
  .darkMode(false)
281
  .range('1-10')
282
  .build();
283
```