0
# CLI Interface
1

2
The NSP CLI provides command-line access to vulnerability scanning functionality with multiple commands and output options.
3

4
## Capabilities
5

6
### Installation and Global Usage
7

8
Install NSP globally to use the command-line interface.
9

10
```bash { .api }
11
# Install globally
12
npm install -g nsp
13

14
# Basic usage
15
nsp [command] [options]
16
```
17

18
### Root Command 
19

20
The root command provides version information and help.
21

22
```bash { .api }
23
# Show version
24
nsp --version
25
nsp -v
26

27
# Show help  
28
nsp --help
29
nsp -h
30
```
31

32
### Check Command
33

34
The main command for scanning projects for vulnerabilities.
35

36
```bash { .api }
37
# Basic vulnerability check
38
nsp check
39

40
# Check with options
41
nsp check [--output format] [--offline] [--advisoriesPath path] [--warn-only] [--quiet] [--path dir] [--help]
42
```
43

44
**Command Options:**
45

46
- `--output, -o` - Output format (default, summary, json, codeclimate, none, quiet, or custom formatter)
47
- `--offline` - Use offline mode (requires npm-shrinkwrap.json and local advisories)
48
- `--advisoriesPath` - Path to local advisories file for offline mode
49
- `--warn-only` - Exit with code 0 even when vulnerabilities are found
50
- `--quiet` - Suppress output except for errors
51
- `--path, -p` - Directory path to check (defaults to current directory)
52
- `--help, -h` - Show command help
53

54
**Output Formats:**
55

56
- `default` - Colorized table format with detailed vulnerability information
57
- `summary` - Simplified table showing key fields only
58
- `json` - Raw JSON output of vulnerability data  
59
- `codeclimate` - Code Climate compatible JSON format
60
- `none` - Suppress all output
61
- `quiet` - Minimal output for CI/CD environments
62

63
**Usage Examples:**
64

65
```bash
66
# Check current project with default output
67
nsp check
68

69
# Check with JSON output  
70
nsp check --output json
71

72
# Check with summary table
73
nsp check --output summary
74

75
# Check in offline mode
76
nsp check --offline --advisoriesPath ./advisories.json
77

78
# Check specific directory
79
nsp check --path /path/to/project
80

81
# Check with custom formatter (requires nsp-formatter-* package)
82
npm install -g nsp-formatter-checkstyle
83
nsp check --output checkstyle
84

85
# Warn only mode (don't fail CI builds)
86
nsp check --warn-only
87
```
88

89
### Exit Codes
90

91
The CLI returns different exit codes based on results:
92

93
```bash { .api }
94
# Exit code 0: No vulnerabilities found or --warn-only flag used
95
# Exit code 1: Vulnerabilities found or error occurred
96
```
97

98
### Global Options
99

100
Options available for all commands:
101

102
```bash { .api }
103
# Available for all commands
104
--path, -p <directory>    # Directory to check (default: current directory)
105
--help, -h               # Show help for command
106
--output, -o <format>    # Output format (default: default formatter)
107
```
108

109
### Environment Variables
110

111
Environment variables that affect CLI behavior:
112

113
```bash { .api }
114
# Proxy configuration
115
HTTPS_PROXY=http://proxy.example.com:8080 nsp check
116
https_proxy=http://proxy.example.com:8080 nsp check
117
```
118

119
### Configuration Files
120

121
The CLI respects .nsprc configuration files:
122

123
```bash { .api }
124
# .nsprc in project root or home directory
125
{
126
  "exceptions": ["https://nodesecurity.io/advisories/123"],
127
  "proxy": "http://proxy.example.com:8080",
128
  "advisoriesPath": "/path/to/advisories.json"
129
}
130
```
131

132
### Offline Mode Setup
133

134
Setting up offline mode requires downloading the advisory database:
135

136
```bash { .api }
137
# Download advisory database
138
npm run setup-offline
139

140
# Use offline mode (requires npm-shrinkwrap.json)
141
nsp check --offline
142
```
143

144
### Integration Examples
145

146
Common integration patterns:
147

148
```bash
149
# CI/CD pipeline integration
150
nsp check --output json > security-report.json
151

152
# Git pre-commit hook
153
nsp check --warn-only || echo "Security warnings found"
154

155
# Docker container scanning
156
docker run -v $(pwd):/app -w /app node:alpine sh -c "npm install -g nsp && nsp check"
157
```