0
# CLI Commands Reference
1

2
Safety CLI provides a comprehensive set of commands for vulnerability scanning, authentication, and project management. All commands are accessed through the `safety` entry point.
3

4
## Command Structure
5

6
```bash
7
safety [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGUMENTS]
8
```
9

10
## Global Options { .api }
11

12
```bash
13
--debug                        # Enable debug logging
14
--disable-optional-telemetry   # Disable telemetry collection
15
--help                         # Show help message
16
--version                      # Show version information
17
```
18

19
**Import Statement:**
20

21
```python
22
from safety.cli import cli
23
```
24

25
## Core Commands
26

27
### Vulnerability Scanning
28

29
#### `safety scan` { .api }
30

31
**Description**: Scan project dependencies for known vulnerabilities (primary command).
32

33
**Usage:**
34

35
```bash
36
safety scan [OPTIONS] [TARGET]
37
```
38

39
**Parameters:**
40

41
- `TARGET` (Path, optional): Directory to scan (default: current directory)
42

43
**Options:**
44

45
```bash
46
--output {screen,json}           # Output format (default: screen)
47
--detailed-output               # Show detailed vulnerability information  
48
--save-as FORMAT:FILE           # Save report to file with format
49
--policy-file PATH              # Path to policy file (.safety-policy.yml)
50
--apply-fixes                   # Apply automatic fixes when available
51
--max-fixes N                   # Maximum number of fixes to apply
52
--no-audit                      # Skip audit and monitoring
53
--short-report                  # Generate short vulnerability report
54
--continue-on-error             # Continue scan even if errors occur
55
```
56

57
**Examples:**
58

59
```bash
60
# Scan current directory
61
safety scan
62

63
# Scan specific path with JSON output
64
safety scan /path/to/project --output json
65

66
# Scan with policy file
67
safety scan --policy-file .safety-policy.yml
68

69
# Save detailed report to file
70
safety scan --detailed-output --save-as json:report.json
71
```
72

73
**Python API:**
74

75
```python
76
# Note: CLI commands are typically accessed through the main CLI interface
77
from safety.cli import cli
78
import sys
79

80
# Programmatic CLI invocation (recommended approach)
81
sys.argv = ['safety', 'scan', '--detailed-output']
82
cli()
83
```
84

85
#### `safety system-scan` { .api }
86

87
**Description**: Scan system-wide Python packages for vulnerabilities.
88

89
**Usage:**
90

91
```bash  
92
safety system-scan [OPTIONS]
93
```
94

95
**Options:**
96

97
```bash
98
--target PATH                   # Specific target path to scan (can be used multiple times)
99
--output {screen,json}           # Output format (default: screen)
100
--detailed-output               # Show detailed vulnerability information
101
--save-as FORMAT:FILE           # Save report to file with format  
102
--policy-file PATH              # Path to policy file
103
--short-report                  # Generate short vulnerability report
104
--continue-on-error             # Continue scan even if errors occur
105
```
106

107
**Examples:**
108

109
```bash
110
# Scan system packages
111
safety system-scan
112

113
# System scan with JSON output
114
safety system-scan --output json --save-as json:system-report.json
115
```
116

117
#### `safety check` (Deprecated) { .api }
118

119
**Description**: Legacy vulnerability check command (deprecated, use `scan` instead).
120

121
**Usage:**
122

123
```bash
124
safety check [OPTIONS] [FILES]
125
```
126

127
**Deprecation Notice**: This command will be unsupported beyond June 1, 2024. Use `safety scan` instead.
128

129
**Options:**
130

131
```bash
132
--db PATH                       # Path to vulnerability database
133
--full-report                   # Show full report details
134
--stdin                         # Read from stdin
135
--files FILE [FILE ...]         # Specific files to check
136
--cache                         # Use cached database
137
--ignore VULN_ID               # Ignore specific vulnerabilities
138
--ignore-unpinned-requirements  # Ignore unpinned requirements
139
--output {text,json,html,bare}  # Output format
140
--json                         # JSON output (alias)
141
--html                         # HTML output (alias)  
142
--bare                         # Minimal output (alias)
143
--exit-code                    # Exit with error code on vulnerabilities
144
--policy-file PATH             # Path to policy file
145
--audit-and-monitor            # Enable audit and monitoring
146
--project NAME                 # Project name for reporting
147
--save-json PATH               # Save JSON report
148
--save-html PATH               # Save HTML report
149
--apply-remediations           # Apply automatic remediations
150
--auto-remediation-limit N     # Limit automatic remediations
151
--no-prompt                    # Skip interactive prompts
152
--json-version VERSION         # JSON schema version
153
```
154

155
### License Management
156

157
#### `safety license` { .api }
158

159
**Description**: Find open source licenses used by Python dependencies.
160

161
**Usage:**
162

163
```bash
164
safety license [OPTIONS] [FILES]
165
```
166

167
**Options:**
168

169
```bash
170
--db PATH                      # Path to license database
171
--output {text,json}           # Output format (default: text)
172
--cache                        # Use cached database
173
--files FILE [FILE ...]        # Specific files to check
174
```
175

176
**Examples:**
177

178
```bash
179
# Check licenses in requirements.txt
180
safety license --files requirements.txt
181

182
# Check licenses with JSON output  
183
safety license --output json
184

185
# Use custom license database
186
safety license --db /path/to/license_db
187
```
188

189
### Authentication Commands
190

191
#### `safety auth login` { .api }
192

193
**Description**: Authenticate with Safety platform using browser-based OAuth flow.
194

195
**Usage:**
196

197
```bash
198
safety auth login [OPTIONS]
199
```
200

201
**Options:**
202

203
```bash
204
--headless                     # Run in headless mode (copy/paste URL)
205
```
206

207
**Examples:**
208

209
```bash
210
# Interactive browser login
211
safety auth login
212

213
# Headless login (for CI/CD environments)
214
safety auth login --headless
215
```
216

217
**Python API:**
218

219
```python
220
from safety.auth.cli import login
221
import typer
222

223
# Create context and authenticate
224
ctx = typer.Context(login)
225
login(ctx=ctx, headless=False)
226
```
227

228
#### `safety auth logout` { .api }
229

230
**Description**: Sign out from Safety platform.
231

232
**Usage:**
233

234
```bash
235
safety auth logout
236
```
237

238
#### `safety auth status` { .api }
239

240
**Description**: Check current authentication status and organization details.
241

242
**Usage:**
243

244
```bash
245
safety auth status
246
```
247

248
**Output includes:**
249
- Authentication status
250
- Organization information
251
- Account details
252
- Current CLI version
253
- Latest available version
254

255
#### `safety auth register` { .api }
256

257
**Description**: Register a new Safety platform account.
258

259
**Usage:**
260

261
```bash
262
safety auth register
263
```
264

265
### Project Initialization
266

267
#### `safety init` { .api }
268

269
**Description**: Initialize Safety configuration in a project.
270

271
**Usage:**
272

273
```bash
274
safety init [OPTIONS]
275
```
276

277
**Options:**
278

279
```bash
280
--policy-file PATH             # Path for generated policy file
281
--interactive                  # Interactive configuration setup
282
```
283

284
### Policy and Configuration
285

286
#### `safety generate policy` { .api }
287

288
**Description**: Generate a Safety policy template file.
289

290
**Usage:**
291

292
```bash
293
safety generate policy [OPTIONS] NAME
294
```
295

296
**Parameters:**
297

298
- `NAME` (str, required): Name for the generated policy
299

300
**Options:**
301

302
```bash
303
--path PATH                    # Directory to create policy file (default: .)
304
--minimum-cvss-severity LEVEL  # Minimum CVSS severity level (default: critical)
305
```
306

307
**Severity Levels:**
308
- `critical`
309
- `high` 
310
- `medium`
311
- `low`
312

313
**Examples:**
314

315
```bash
316
# Generate basic policy template
317
safety generate policy my-project
318

319
# Generate with custom path and severity
320
safety generate policy my-project --path ./config --minimum-cvss-severity high
321
```
322

323
#### `safety generate installation_policy` { .api }
324

325
**Description**: Generate an installation policy for package management.
326

327
**Usage:**
328

329
```bash
330
safety generate installation_policy [OPTIONS] NAME
331
```
332

333
**Parameters:**
334

335
- `NAME` (str, required): Name for the generated installation policy
336

337
**Options:**
338

339
```bash
340
--path PATH                    # Directory to create policy file (default: .)
341
--minimum-cvss-severity LEVEL  # Minimum CVSS severity level (default: critical)
342
```
343

344
#### `safety validate` { .api }
345

346
**Description**: Validate Safety policy file syntax and structure.
347

348
**Usage:**
349

350
```bash
351
safety validate [OPTIONS] NAME VERSION
352
```
353

354
**Parameters:**
355

356
- `NAME` (str, required): Policy name to validate
357
- `VERSION` (str, required): Policy version to validate
358

359
**Options:**
360

361
```bash
362
--path PATH                    # Path to policy file directory (default: .)
363
```
364

365
### Configuration Management
366

367
#### `safety configure` { .api }
368

369
**Description**: Configure Safety CLI settings and proxy options.
370

371
**Usage:**
372

373
```bash
374
safety configure [OPTIONS]
375
```
376

377
**Options:**
378

379
```bash
380
--proxy-protocol {http,https}  # Proxy protocol
381
--proxy-host HOST              # Proxy hostname
382
--proxy-port PORT              # Proxy port number
383
--proxy-required               # Require proxy for all requests
384
--proxy-timeout SECONDS        # Proxy timeout in seconds
385
--organization-id ID           # Organization ID
386
--organization-name NAME       # Organization name
387
--save-to-system              # Save configuration system-wide
388
```
389

390
**Examples:**
391

392
```bash
393
# Configure HTTP proxy
394
safety configure --proxy-protocol http --proxy-host proxy.company.com --proxy-port 8080
395

396
# Set organization settings
397
safety configure --organization-id 12345 --organization-name "My Company"
398

399
# Save configuration system-wide
400
safety configure --save-to-system
401
```
402

403
### Update Management
404

405
#### `safety check-updates` { .api }
406

407
**Description**: Check for Safety CLI updates and configuration changes.
408

409
**Usage:**
410

411
```bash
412
safety check-updates [OPTIONS]
413
```
414

415
**Options:**
416

417
```bash
418
--output {screen,json}         # Output format (default: screen)
419
```
420

421
**Output includes:**
422
- Current Safety version
423
- Latest available version
424
- Organization information
425
- Account status
426
- Configuration updates
427

428
### Advanced Commands
429

430
#### `safety codebase` { .api }
431

432
**Description**: Advanced codebase analysis and scanning features.
433

434
**Usage:**
435

436
```bash
437
safety codebase [SUBCOMMAND] [OPTIONS]
438
```
439

440
#### `safety firewall` { .api }
441

442
**Description**: Network security and firewall-related features.
443

444
**Usage:**
445

446
```bash
447
safety firewall [SUBCOMMAND] [OPTIONS]
448
```
449

450
## Exit Codes { .api }
451

452
Safety CLI uses standard exit codes to indicate command results:
453

454
```python
455
from safety.constants import (
456
    EXIT_CODE_OK,                    # 0 - Success
457
    EXIT_CODE_FAILURE,              # 1 - General failure  
458
    EXIT_CODE_VULNERABILITIES_FOUND, # 64 - Vulnerabilities found
459
    EXIT_CODE_INVALID_AUTH_CREDENTIAL, # 65 - Invalid authentication credential
460
    EXIT_CODE_TOO_MANY_REQUESTS,    # 66 - Too many requests (rate limited)
461
    EXIT_CODE_UNABLE_TO_LOAD_LOCAL_VULNERABILITY_DB, # 67 - Cannot load local DB
462
    EXIT_CODE_UNABLE_TO_FETCH_VULNERABILITY_DB, # 68 - Cannot fetch DB
463
    EXIT_CODE_MALFORMED_DB,         # 69 - Database is malformed
464
    EXIT_CODE_INVALID_PROVIDED_REPORT, # 70 - Invalid report provided
465
    EXIT_CODE_INVALID_REQUIREMENT,  # 71 - Invalid requirement specification
466
    EXIT_CODE_EMAIL_NOT_VERIFIED    # 72 - Email not verified
467
)
468
```
469

470
- **0**: Command executed successfully, no vulnerabilities found
471
- **1**: Command failed due to error or invalid usage
472
- **64**: Vulnerabilities were found in the scan
473
- **65**: Invalid authentication credential provided
474
- **66**: Too many requests sent to API (rate limited)
475
- **67**: Unable to load local vulnerability database
476
- **68**: Unable to fetch vulnerability database from remote
477
- **69**: Vulnerability database is malformed or corrupted
478
- **70**: Invalid report format or content provided
479
- **71**: Invalid requirement specification in files
480
- **72**: Email address not verified for account
481

482
## Command Aliases and Shortcuts { .api }
483

484
```bash
485
# Output format aliases
486
--json          # Equivalent to --output json
487
--html          # Equivalent to --output html (check command)
488
--bare          # Equivalent to --output bare (check command)
489
```
490

491
## Environment Variables { .api }
492

493
Safety CLI respects several environment variables for configuration:
494

495
```bash
496
SAFETY_API_BASE_URL         # Base URL for Safety API
497
SAFETY_DB_MIRROR           # Mirror URL for vulnerability database
498
SAFETY_PROXY_HOST          # Proxy hostname
499
SAFETY_PROXY_PORT          # Proxy port  
500
SAFETY_PROXY_PROTOCOL      # Proxy protocol (http/https)
501
SAFETY_OS_DESCRIPTION      # Operating system description override
502
```
503

504
## Common Usage Patterns
505

506
### CI/CD Integration
507

508
```bash
509
# Basic CI vulnerability check
510
safety scan --output json --continue-on-error
511

512
# Authenticated scan with policy
513
safety auth login --headless
514
safety scan --policy-file .safety-policy.yml --exit-code
515

516
# System-wide scanning in containers
517
safety system-scan --output json --save-as json:/tmp/scan-report.json
518
```
519

520
### Development Workflow
521

522
```bash
523
# Initialize project with Safety
524
safety init --interactive
525
safety generate policy myproject
526

527
# Regular development scanning
528
safety scan --detailed-output
529
safety license --output json
530

531
# Pre-deployment checks
532
safety scan --policy-file .safety-policy.yml --apply-fixes --max-fixes 5
533
```
534

535
### Reporting and Automation
536

537
```bash
538
# Generate comprehensive reports
539
safety scan --detailed-output --save-as json:vulnerability-report.json
540
safety license --output json > license-report.json
541

542
# Automated policy validation  
543
safety validate myproject 1.0 --path ./policies
544
```
545

546
This comprehensive CLI reference covers all available commands, options, and usage patterns for Safety CLI, enabling developers to effectively integrate vulnerability scanning into their development and deployment workflows.