0
# CLI Interface
1

2
Command-line interface for generating changelogs with extensive configuration options and flexible output control.
3

4
## Capabilities
5

6
### CLI Command
7

8
The main command-line interface for standard-changelog.
9

10
```bash { .api }
11
standard-changelog [options]
12
```
13

14
**Basic Usage Examples:**
15

16
```bash
17
# Generate changelog for current release
18
standard-changelog
19

20
# Generate changelog for first release (includes all commits)
21
standard-changelog --first-release
22

23
# Output to stdout instead of file
24
standard-changelog --stdout
25

26
# Append to existing changelog instead of prepending
27
standard-changelog --append
28

29
# Generate changelog with verbose output
30
standard-changelog --verbose
31

32
# Generate changelog for specific number of releases
33
standard-changelog --release-count 3
34

35
# Use custom input/output files
36
standard-changelog --infile HISTORY.md --outfile CHANGELOG.md
37
```
38

39
### CLI Flags
40

41
Complete set of command-line flags for configuring changelog generation.
42

43
```typescript { .api }
44
interface Flags {
45
  /** Input file path (default: CHANGELOG.md) */
46
  infile?: string;
47
  /** Output file path (default: same as infile) */
48
  outfile?: string;
49
  /** Output to stdout instead of file */
50
  stdout?: boolean;
51
  /** Preset name to use (default: angular) */
52
  preset?: string;
53
  /** Path to package.json file */
54
  pkg?: string;
55
  /** Append newer release to older release (default: false) */
56
  append?: boolean;
57
  /** Number of releases to generate (default: 1, 0 = all) */
58
  releaseCount?: number;
59
  /** Skip unstable tags (alpha, beta, rc) */
60
  skipUnstable?: boolean;
61
  /** Output unreleased changelog */
62
  outputUnreleased?: boolean;
63
  /** Verbose output for debugging */
64
  verbose?: boolean;
65
  /** Path to configuration file */
66
  config?: string;
67
  /** Path to context JSON file */
68
  context?: string;
69
  /** Generate changelog for first release */
70
  firstRelease?: boolean;
71
  /** Generate changelog for specific lerna package */
72
  lernaPackage?: string;
73
  /** Tag prefix to consider when reading tags */
74
  tagPrefix?: string;
75
  /** Generate changelog scoped to specific directory */
76
  commitPath?: string;
77
}
78
```
79

80
### Flag Details
81

82
#### Input/Output Control
83

84
```bash
85
# -i, --infile <path>
86
# Read the CHANGELOG from this file (default: CHANGELOG.md)
87
standard-changelog -i HISTORY.md
88

89
# -o, --outfile <path>  
90
# Write the CHANGELOG to this file (default: same as infile)
91
standard-changelog -o CHANGELOG.md
92

93
# --stdout
94
# Output the result to stdout
95
standard-changelog --stdout
96
```
97

98
#### Release Configuration
99

100
```bash
101
# -f, --first-release
102
# Generate the CHANGELOG for the first time (includes all commits)
103
standard-changelog --first-release
104

105
# -r, --release-count <number>
106
# How many releases to generate (default: 1, 0 = regenerate all)
107
standard-changelog --release-count 3
108

109
# --skip-unstable
110
# Skip unstable tags like x.x.x-alpha.1, x.x.x-rc.2
111
standard-changelog --skip-unstable
112

113
# -u, --output-unreleased
114
# Output unreleased changelog
115
standard-changelog --output-unreleased
116
```
117

118
#### Behavior Control
119

120
```bash
121
# -a, --append
122
# Append newer release to older release (default: false)
123
standard-changelog --append
124

125
# -v, --verbose
126
# Verbose output for debugging
127
standard-changelog --verbose
128

129
# -t, --tag-prefix <prefix>
130
# Tag prefix to consider when reading tags
131
standard-changelog --tag-prefix v
132

133
# --commit-path <path>
134
# Generate changelog scoped to specific directory
135
standard-changelog --commit-path packages/core
136
```
137

138
#### Advanced Configuration
139

140
```bash
141
# -p, --preset <name>
142
# Name of preset to use (default: angular)
143
standard-changelog --preset conventionalcommits
144

145
# -k, --pkg <path>
146
# Path to package.json file
147
standard-changelog --pkg ./packages/core/package.json
148

149
# -n, --config <path>
150
# Path to configuration script
151
standard-changelog --config ./changelog.config.js
152

153
# -c, --context <path>
154
# Path to JSON file with template variables
155
standard-changelog --context ./changelog-context.json
156

157
# -l, --lerna-package <package>
158
# Generate changelog for specific lerna package
159
standard-changelog --lerna-package my-package@1.0.0
160
```
161

162
### runProgram Function
163

164
The main function that processes CLI flags and executes changelog generation.
165

166
```typescript { .api }
167
/**
168
 * Main CLI program runner that processes flags and generates changelog
169
 * @param generator - StandardChangelog or ConventionalChangelog instance
170
 * @param flags - Parsed CLI flags
171
 */
172
async function runProgram(
173
  generator: ConventionalChangelog,
174
  flags: Flags
175
): Promise<void>;
176
```
177

178
**Usage Example:**
179

180
```typescript
181
import { StandardChangelog, runProgram } from "standard-changelog";
182

183
// Programmatic CLI usage
184
const generator = new StandardChangelog(process.cwd());
185
const flags = {
186
  infile: "CHANGELOG.md",
187
  outfile: "CHANGELOG.md",
188
  releaseCount: 1,
189
  verbose: true
190
};
191

192
await runProgram(generator, flags);
193
```
194

195
### Flag Definitions
196

197
The exported flags object defines all available CLI options with their configurations.
198

199
```typescript { .api }
200
const flags = {
201
  infile: { shortFlag: 'i', default: 'CHANGELOG.md', type: 'string' },
202
  outfile: { shortFlag: 'o', type: 'string' },
203
  stdout: { type: 'boolean' },
204
  preset: { shortFlag: 'p', type: 'string' },
205
  pkg: { shortFlag: 'k', type: 'string' },
206
  append: { shortFlag: 'a', type: 'boolean' },
207
  releaseCount: { shortFlag: 'r', type: 'number' },
208
  skipUnstable: { type: 'boolean' },
209
  outputUnreleased: { shortFlag: 'u', type: 'boolean' },
210
  verbose: { shortFlag: 'v', type: 'boolean' },
211
  config: { shortFlag: 'n', type: 'string' },
212
  context: { shortFlag: 'c', type: 'string' },
213
  firstRelease: { shortFlag: 'f', type: 'boolean' },
214
  lernaPackage: { shortFlag: 'l', type: 'string' },
215
  tagPrefix: { shortFlag: 't', type: 'string' }
216
} as const;
217
```
218

219
## Common CLI Workflows
220

221
### First Release
222

223
```bash
224
# Generate initial changelog including all commits
225
standard-changelog --first-release
226
```
227

228
### Regular Release
229

230
```bash
231
# Generate changelog for latest release only
232
standard-changelog
233

234
# Or explicitly specify single release
235
standard-changelog --release-count 1
236
```
237

238
### Multi-Release Update
239

240
```bash
241
# Generate changelog for last 3 releases
242
standard-changelog --release-count 3
243

244
# Regenerate entire changelog
245
standard-changelog --release-count 0
246
```
247

248
### Custom File Handling
249

250
```bash
251
# Use different input/output files
252
standard-changelog --infile HISTORY.md --outfile CHANGELOG.md
253

254
# Append to existing changelog
255
standard-changelog --append
256

257
# Output to terminal only
258
standard-changelog --stdout
259
```
260

261
### Debugging and Development
262

263
```bash
264
# Verbose output for troubleshooting
265
standard-changelog --verbose
266

267
# Generate unreleased changes
268
standard-changelog --output-unreleased
269

270
# Skip pre-release tags
271
standard-changelog --skip-unstable
272
```