0
# Command Line Interface
1

2
REUSE provides a comprehensive command-line interface with 7 subcommands for managing REUSE compliance, licensing, and copyright information in software projects.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
The main `reuse` command provides global configuration options that apply to all subcommands.
9

10
```bash { .api }
11
reuse [OPTIONS] COMMAND [ARGS]...
12

13
# Global Options:
14
--debug                      Enable debug statements
15
--suppress-deprecation       Hide deprecation warnings  
16
--include-submodules         Do not skip Git submodules
17
--include-meson-subprojects  Do not skip Meson subprojects
18
--no-multiprocessing         Do not use multiprocessing
19
--root PATH                  Define project root directory
20
--version                    Show version information
21
--help                       Show help message
22
```
23

24
### Lint Command
25

26
Lint the project directory for REUSE compliance, checking all files for proper copyright and licensing information.
27

28
```bash { .api }
29
reuse lint [OPTIONS]
30

31
# Options:
32
--quiet, -q                 Prevent output
33
--json, -j                  Format output as JSON
34
--plain, -p                 Format output as plain text (default)
35
--lines, -l                 Format output as errors per line
36
```
37

38
**Usage Example:**
39

40
```bash
41
# Basic linting
42
reuse lint
43

44
# JSON output for processing
45
reuse lint --json > compliance-report.json
46

47
# Quiet mode (only show errors)
48
reuse lint --quiet
49
```
50

51
The lint command examines all files in the project and reports:
52
- Files missing copyright information
53
- Files missing license information  
54
- Files with incorrect or malformed headers
55
- Overall compliance status
56

57
### Annotate Command
58

59
Add copyright and licensing information to file headers.
60

61
```bash { .api }
62
reuse annotate [OPTIONS] FILE [FILE...]
63

64
# Options:
65
--copyright TEXT            Copyright notice (can be used multiple times)
66
--license SPDX_IDENTIFIER   SPDX license identifier (can be used multiple times)
67
--contributor TEXT          Contributor information (can be used multiple times)
68
--year INTEGER              Copyright year
69
--style [python|c|html|...]  Comment style to use
70
--template FILE             Template file for header
71
--force                     Force annotation even if file has existing info
72
--recursive                 Recursively annotate directories
73
--exclude-patterns TEXT     Exclude files matching these patterns
74
```
75

76
**Usage Examples:**
77

78
```bash
79
# Add copyright and license to a single file
80
reuse annotate --copyright="2023 Jane Doe" --license="MIT" src/example.py
81

82
# Add multiple copyrights and licenses
83
reuse annotate \
84
  --copyright="2023 Jane Doe" \
85
  --copyright="2023 Company Inc" \
86
  --license="MIT" \
87
  --license="GPL-3.0-or-later" \
88
  src/example.py
89

90
# Annotate all Python files recursively
91
reuse annotate --recursive --copyright="2023 Jane Doe" --license="MIT" src/
92

93
# Use specific year
94
reuse annotate --copyright="Jane Doe" --license="MIT" --year=2020 old-file.py
95

96
# Force annotation (overwrite existing)
97
reuse annotate --force --copyright="2023 Jane Doe" --license="MIT" src/example.py
98
```
99

100
### SPDX Command
101

102
Generate an SPDX bill of materials for the project.
103

104
```bash { .api }
105
reuse spdx [OPTIONS]
106

107
# Options:
108
--output FILE, -o FILE      Output file (default: stdout)
109
--add-license-concluded     Add license concluded field (requires creator info)
110
--creator-person TEXT       Name of person signing off on SPDX report
111
--creator-organization TEXT Name of organization signing off on SPDX report
112
```
113

114
**Usage Examples:**
115

116
```bash
117
# Generate SPDX document
118
reuse spdx > project.spdx
119

120
# Save to file
121
reuse spdx --output=project.spdx
122

123
# Generate with license conclusions
124
reuse spdx --add-license-concluded \
125
  --creator-person="Jane Doe" \
126
  --output=detailed.spdx
127

128
# With organization creator
129
reuse spdx --add-license-concluded \
130
  --creator-organization="Example Corp" \
131
  --output=project.spdx
132
```
133

134
### Download Command
135

136
Download a license from the SPDX License List and place it in the LICENSES/ directory.
137

138
```bash { .api }
139
reuse download [OPTIONS] SPDX_IDENTIFIER [SPDX_IDENTIFIER...]
140

141
# Options:
142
--output DIRECTORY  Directory to store license files (default: LICENSES/)
143
```
144

145
**Usage Examples:**
146

147
```bash
148
# Download single license
149
reuse download MIT
150

151
# Download multiple licenses
152
reuse download MIT GPL-3.0-or-later Apache-2.0
153

154
# Download to specific directory
155
reuse download --output=licenses/ MIT
156
```
157

158
The download command:
159
- Fetches the official license text from the SPDX License List
160
- Creates the LICENSES/ directory if it doesn't exist
161
- Saves the license with the SPDX identifier as filename (e.g., `MIT.txt`)
162
- Validates the SPDX identifier before downloading
163

164
### Supported Licenses Command
165

166
List all licenses available on the SPDX License List.
167

168
```bash { .api }
169
reuse supported-licenses [OPTIONS]
170

171
# Options:
172
--format [plain|json]  Output format (default: plain)
173
```
174

175
**Usage Examples:**
176

177
```bash
178
# List all supported licenses
179
reuse supported-licenses
180

181
# JSON output for processing
182
reuse supported-licenses --format=json > supported-licenses.json
183
```
184

185
### Convert DEP5 Command
186

187
Convert a .reuse/dep5 file to a REUSE.toml file format.
188

189
```bash { .api }
190
reuse convert-dep5 [OPTIONS]
191

192
# Options:
193
--no-backup        Do not create backup of original file
194
--output FILE      Output file (default: REUSE.toml)
195
```
196

197
**Usage Examples:**
198

199
```bash
200
# Convert .reuse/dep5 to REUSE.toml
201
reuse convert-dep5
202

203
# Convert without creating backup
204
reuse convert-dep5 --no-backup
205

206
# Convert to specific output file
207
reuse convert-dep5 --output=new-reuse.toml
208
```
209

210
### Lint File Command
211

212
Lint individual files for REUSE compliance instead of the entire project.
213

214
```bash { .api }
215
reuse lint-file [OPTIONS] FILE [FILE...]
216

217
# Options:
218
--json, -j                  Format output as JSON
219
--plain, -p                 Format output as plain text (default)
220
--lines, -l                 Format output as errors per line
221
```
222

223
**Usage Examples:**
224

225
```bash
226
# Lint specific files
227
reuse lint-file src/example.py src/other.py
228

229
# JSON output for individual files
230
reuse lint-file --json src/example.py
231
```
232

233
## Exit Codes
234

235
All REUSE commands use standard exit codes:
236

237
- **0**: Success (or compliant project for lint commands)
238
- **1**: General error or non-compliant project
239
- **2**: Invalid command usage or missing arguments
240

241
## Global Configuration
242

243
The global options can be used with any subcommand:
244

245
```bash
246
# Debug mode with custom root
247
reuse --debug --root=/path/to/project lint
248

249
# Include submodules and disable multiprocessing
250
reuse --include-submodules --no-multiprocessing annotate --license=MIT file.py
251

252
# Suppress deprecation warnings
253
reuse --suppress-deprecation spdx --format=json
254
```
255

256
## Environment Variables
257

258
- **`REUSE_SUPPRESS_DEPRECATION`**: Set to suppress deprecation warnings
259
- **`_SUPPRESS_DEP5_WARNING`**: Internal variable to suppress DEP5 warnings during conversion