0
# Command Line Interface
1

2
The Metlo CLI provides comprehensive tooling for API security operations including initialization, traffic mirroring setup, security test management, and platform integration.
3

4
## Capabilities
5

6
### Installation and Setup
7

8
Install the CLI globally and initialize it with your Metlo backend.
9

10
```bash
11
# Install globally
12
npm install -g @metlo/cli
13

14
# Initialize with backend connection
15
metlo init --backend_url https://your-metlo-backend.com --api_key your-api-key
16
```
17

18
### Core Commands
19

20
#### Initialize CLI
21

22
Configure the CLI with your Metlo backend connection details.
23

24
```bash { .api }
25
metlo init [options]
26

27
Options:
28
  -b, --backend_url <string>  The backend address for Metlo
29
  -k, --api_key <string>      An API key for Metlo
30
```
31

32
**Usage Examples:**
33

34
```bash
35
# Basic initialization
36
metlo init --backend_url https://api.metlo.com --api_key sk_live_abc123
37

38
# Interactive setup (prompts for missing values)
39
metlo init
40
```
41

42
### Security Testing Commands
43

44
#### Generate Tests
45

46
Generate security tests for specific endpoints and vulnerability types.
47

48
```bash { .api }
49
metlo test generate [options]
50

51
Required Options:
52
  -t, --testType <string>     Type of test to generate (auth, sqli, xss, bola, etc.)
53
  -e, --endpoint <string>     The endpoint to generate this test for
54

55
Optional:
56
  -p, --path <string>         Path to generate the test at
57
  -v, --version <number>      The version of the test template
58
  -h, --host <string>         The host to generate this test for
59
  -x, --method <string>       The method of the endpoint
60
```
61

62
**Usage Examples:**
63

64
```bash
65
# Generate authentication test
66
metlo test generate --testType auth --endpoint /api/users/profile --host api.example.com --method GET
67

68
# Generate SQL injection test with custom path
69
metlo test generate --testType sqli --endpoint /api/search --path ./tests/sqli-search.yaml
70

71
# Generate BOLA (Broken Object Level Authorization) test
72
metlo test generate --testType bola --endpoint /api/users/:id --method GET
73
```
74

75
#### Run Tests
76

77
Execute security tests from YAML files with flexible filtering options.
78

79
```bash { .api }
80
metlo test run [paths...] [options]
81

82
Arguments:
83
  [paths...]                  Path to yaml test files (optional, runs all if not specified)
84

85
Options:
86
  -e, --endpoint <string>     endpoint pattern or uuid
87
  -x, --method <string>       The method of the endpoint
88
  -n, --host <string>         hostname for which tests are to be run
89
  -v, --verbose               print detailed test errors
90
  --envfile <string>          path for your env file
91
  --env <key>=<value>         environment variables (can be used multiple times)
92
```
93

94
**Usage Examples:**
95

96
```bash
97
# Run all tests in directory
98
metlo test run ./tests/*.yaml
99

100
# Run tests for specific endpoint
101
metlo test run --endpoint /api/users --method GET
102

103
# Run with environment variables
104
metlo test run --env API_KEY=abc123 --env BASE_URL=https://staging.api.com
105

106
# Run with environment file and verbose output
107
metlo test run --envfile .env.test --verbose
108
```
109

110
#### Run Authentication Tests
111

112
Execute pre-configured authentication security tests.
113

114
```bash { .api }
115
metlo test run-auth-tests
116

117
# Runs comprehensive authentication vulnerability tests
118
```
119

120
### Template Management Commands
121

122
#### Initialize Custom Templates
123

124
Set up custom test templates for your organization's specific security testing needs.
125

126
```bash { .api }
127
metlo template init <path>
128

129
Arguments:
130
  <path>                      Path to project directory
131
```
132

133
**Usage Examples:**
134

135
```bash
136
# Initialize templates in current directory
137
metlo template init .
138

139
# Initialize in specific directory
140
metlo template init ./my-security-templates
141
```
142

143
#### Push Templates
144

145
Upload custom test templates to your Metlo backend.
146

147
```bash { .api }
148
metlo template push [paths...]
149

150
Arguments:
151
  [paths...]                  Path to template files
152
```
153

154
**Usage Examples:**
155

156
```bash
157
# Push all templates in directory
158
metlo template push ./templates/*.yaml
159

160
# Push specific template files
161
metlo template push ./templates/custom-auth.yaml ./templates/api-fuzzing.yaml
162
```
163

164
### Traffic Mirroring Commands
165

166
#### AWS Traffic Mirroring
167

168
Set up and manage traffic mirroring on AWS infrastructure.
169

170
```bash { .api }
171
# Create new AWS traffic mirror
172
metlo traffic-mirror aws new [options]
173

174
Options:
175
  -i, --id <string>               UUID for the identifier
176
  -r, --region <string>           AWS Region where source and target are located
177
  -t, --target-eni-id <string>    Target ENI ID
178
  -s, --source-eni-id <string>    Source ENI ID
179

180
# List AWS traffic mirrors
181
metlo traffic-mirror aws list
182

183
# Remove AWS traffic mirror
184
metlo traffic-mirror aws remove
185
```
186

187
**Usage Examples:**
188

189
```bash
190
# Set up traffic mirroring
191
metlo traffic-mirror aws new \
192
  --region us-east-1 \
193
  --source-eni-id eni-1234567890abcdef0 \
194
  --target-eni-id eni-0987654321fedcba0 \
195
  --id my-mirror-session
196

197
# List all traffic mirrors
198
metlo traffic-mirror aws list
199

200
# Remove traffic mirror (interactive)
201
metlo traffic-mirror aws remove
202
```
203

204
#### GCP Traffic Mirroring
205

206
Set up and manage traffic mirroring on Google Cloud Platform.
207

208
```bash { .api }
209
# Create new GCP traffic mirror
210
metlo traffic-mirror gcp new [options]
211

212
Options:
213
  -f, --force                 Force creation of new instance
214

215
# List GCP traffic mirrors
216
metlo traffic-mirror gcp list
217

218
# Remove GCP traffic mirror
219
metlo traffic-mirror gcp remove
220

221
# Cleanup GCP resources
222
metlo traffic-mirror gcp cleanup
223
```
224

225
**Usage Examples:**
226

227
```bash
228
# Set up GCP traffic mirroring (interactive)
229
metlo traffic-mirror gcp new
230

231
# Force creation of new mirror instance
232
metlo traffic-mirror gcp new --force
233

234
# List all GCP mirrors
235
metlo traffic-mirror gcp list
236

237
# Remove mirror (interactive)
238
metlo traffic-mirror gcp remove
239

240
# Clean up unused resources
241
metlo traffic-mirror gcp cleanup
242
```
243

244
### Demo and Testing Commands
245

246
#### Juice Shop Integration
247

248
Set up demo data and templates using OWASP Juice Shop for testing and demonstration purposes.
249

250
```bash { .api }
251
# Initialize Juice Shop demo data
252
metlo juice-shop init-data [options]
253

254
Required Options:
255
  -h, --host <string>         Juice Shop server host
256

257
# Initialize Juice Shop test templates
258
metlo juice-shop init-templates
259
```
260

261
**Usage Examples:**
262

263
```bash
264
# Set up demo data with local Juice Shop
265
metlo juice-shop init-data --host http://localhost:3000
266

267
# Set up demo data with hosted Juice Shop
268
metlo juice-shop init-data --host https://juice-shop.herokuapp.com
269

270
# Initialize test templates
271
metlo juice-shop init-templates
272
```
273

274
## Configuration
275

276
### Environment Variables
277

278
The CLI supports several environment variables for configuration:
279

280
```bash { .api }
281
# Metlo backend URL
282
METLO_BACKEND_URL=https://your-backend.com
283

284
# API key for authentication
285
METLO_API_KEY=your-api-key
286

287
# Default region for cloud operations
288
AWS_DEFAULT_REGION=us-east-1
289
GCP_DEFAULT_REGION=us-central1
290
```
291

292
### Configuration File
293

294
The CLI stores configuration in a local file after initialization. You can also manually create a `.metlo` configuration file:
295

296
```json
297
{
298
  "backend_url": "https://your-metlo-backend.com",
299
  "api_key": "your-api-key"
300
}
301
```
302

303
## Exit Codes
304

305
The CLI uses standard exit codes for integration with CI/CD systems:
306

307
- `0` - Success
308
- `1` - General error
309
- `2` - Command not found
310
- `3` - Authentication error
311
- `4` - Network error
312
- `5` - Test failures detected
313

314
## Integration Examples
315

316
### CI/CD Pipeline Integration
317

318
```yaml
319
# GitHub Actions example
320
name: API Security Tests
321
on: [push, pull_request]
322

323
jobs:
324
  security-tests:
325
    runs-on: ubuntu-latest
326
    steps:
327
      - uses: actions/checkout@v2
328
      - uses: actions/setup-node@v2
329
        with:
330
          node-version: '18'
331
      
332
      - name: Install Metlo CLI
333
        run: npm install -g @metlo/cli
334
      
335
      - name: Initialize Metlo
336
        run: metlo init --backend_url ${{ secrets.METLO_BACKEND_URL }} --api_key ${{ secrets.METLO_API_KEY }}
337
      
338
      - name: Generate security tests
339
        run: |
340
          metlo test generate --testType auth --endpoint /api/users --host api.staging.com
341
          metlo test generate --testType sqli --endpoint /api/search --host api.staging.com
342
      
343
      - name: Run security tests
344
        run: metlo test run --verbose --env BASE_URL=https://api.staging.com
345
```
346

347
### Docker Integration
348

349
```dockerfile
350
FROM node:18-alpine
351

352
# Install Metlo CLI
353
RUN npm install -g @metlo/cli
354

355
# Copy test configurations
356
COPY tests/ /app/tests/
357
WORKDIR /app
358

359
# Initialize and run tests
360
CMD ["sh", "-c", "metlo init --backend_url $METLO_BACKEND_URL --api_key $METLO_API_KEY && metlo test run tests/*.yaml"]
361
```