0
# Command Line Interface
1

2
Command-line tools for model management, dataset processing, and InsightFace operations. Provides convenient CLI access to common tasks without requiring Python scripting.
3

4
## Capabilities
5

6
### CLI Entry Point
7

8
Main command-line interface providing access to all InsightFace CLI commands.
9

10
```python { .api }
11
def main() -> None:
12
    """
13
    Main CLI entry point for insightface-cli command.
14
    
15
    Provides access to subcommands for model management and data processing.
16
    """
17
```
18

19
### Model Download Command
20

21
Command for downloading and managing pre-trained model packs.
22

23
```python { .api }
24
class ModelDownloadCommand:
25
    def __init__(self, model: str, root: str, force: bool):
26
        """
27
        Initialize model download command.
28
        
29
        Parameters:
30
        - model: str, model pack name to download
31
        - root: str, storage root directory
32
        - force: bool, force re-download even if model exists
33
        """
34
    
35
    def run(self) -> None:
36
        """Execute model download operation."""
37
```
38

39
### Dataset Processing Commands
40

41
Commands for processing recognition datasets and adding augmentation parameters.
42

43
```python { .api }
44
class RecAddMaskParamCommand:
45
    def __init__(self, input_path: str, output_path: str):
46
        """
47
        Initialize command to add mask parameters to recognition datasets.
48
        
49
        Parameters:
50
        - input_path: str, path to input dataset file (.rec format)
51
        - output_path: str, path for output dataset with mask parameters
52
        """
53
    
54
    def run(self) -> None:
55
        """Execute mask parameter addition to dataset."""
56
```
57

58
## Command Line Usage
59

60
### Model Management
61

62
Download and manage pre-trained model packs using the CLI.
63

64
```bash
65
# Download default model pack (buffalo_l)
66
insightface-cli model.download buffalo_l
67

68
# Download specific model pack
69
insightface-cli model.download buffalo_s
70

71
# Download model pack to custom directory
72
insightface-cli model.download buffalo_m --root ./my_models
73

74
# Force re-download of existing model pack
75
insightface-cli model.download buffalo_l --force
76

77
# Download multiple model packs
78
insightface-cli model.download buffalo_l buffalo_s buffalo_m
79
```
80

81
### Dataset Processing
82

83
Process recognition datasets for training and evaluation.
84

85
```bash
86
# Add mask parameters to recognition dataset
87
insightface-cli rec.add_mask_param --input dataset.rec --output masked_dataset.rec
88

89
# Process multiple datasets
90
insightface-cli rec.add_mask_param --input train.rec --output train_masked.rec
91
insightface-cli rec.add_mask_param --input val.rec --output val_masked.rec
92
```
93

94
### Help and Information
95

96
Get help and information about available commands.
97

98
```bash
99
# Show general help
100
insightface-cli --help
101

102
# Show help for specific command
103
insightface-cli model.download --help
104
insightface-cli rec.add_mask_param --help
105

106
# List available model packs
107
insightface-cli model.list
108
```
109

110
## Python API Usage
111

112
You can also use the CLI commands programmatically from Python code.
113

114
### Programmatic Model Download
115

116
```python
117
from insightface.commands.model_download import ModelDownloadCommand
118

119
# Create and execute download command
120
cmd = ModelDownloadCommand(model='buffalo_l', root='~/.insightface', force=False)
121
cmd.run()
122

123
print("Model download completed")
124
```
125

126
### Programmatic Dataset Processing
127

128
```python
129
from insightface.commands.rec_add_mask_param import RecAddMaskParamCommand
130

131
# Process dataset with mask parameters
132
cmd = RecAddMaskParamCommand(
133
    input_path='original_dataset.rec',
134
    output_path='masked_dataset.rec'
135
)
136
cmd.run()
137

138
print("Dataset processing completed")
139
```
140

141
### Batch Operations
142

143
```python
144
def download_all_models(root_dir='./models'):
145
    """Download all common model packs."""
146
    models = ['buffalo_l', 'buffalo_m', 'buffalo_s', 'antelopev2']
147
    
148
    for model_name in models:
149
        print(f"Downloading {model_name}...")
150
        cmd = ModelDownloadCommand(model=model_name, root=root_dir, force=False)
151
        try:
152
            cmd.run()
153
            print(f"✓ {model_name} downloaded successfully")
154
        except Exception as e:
155
            print(f"✗ Failed to download {model_name}: {e}")
156

157
# Execute batch download
158
download_all_models()
159
```
160

161
### Dataset Pipeline Integration
162

163
```python
164
def prepare_training_datasets(input_dir, output_dir):
165
    """Prepare datasets for masked face training."""
166
    import os
167
    from pathlib import Path
168
    
169
    input_path = Path(input_dir)
170
    output_path = Path(output_dir)
171
    output_path.mkdir(exist_ok=True)
172
    
173
    # Process all .rec files in input directory
174
    for rec_file in input_path.glob('*.rec'):
175
        output_file = output_path / f"masked_{rec_file.name}"
176
        
177
        print(f"Processing {rec_file.name}...")
178
        cmd = RecAddMaskParamCommand(
179
            input_path=str(rec_file),
180
            output_path=str(output_file)
181
        )
182
        
183
        try:
184
            cmd.run()
185
            print(f"✓ Created {output_file.name}")
186
        except Exception as e:
187
            print(f"✗ Failed to process {rec_file.name}: {e}")
188

189
# Process datasets
190
prepare_training_datasets('./datasets/original', './datasets/masked')
191
```
192

193
## CLI Configuration
194

195
### Environment Variables
196

197
Configure CLI behavior using environment variables.
198

199
```bash
200
# Set default model storage directory
201
export INSIGHTFACE_ROOT=/path/to/models
202

203
# Set default context ID for GPU
204
export INSIGHTFACE_CTX_ID=0
205

206
# Use custom download mirror
207
export INSIGHTFACE_DOWNLOAD_MIRROR=https://custom-mirror.com
208
```
209

210
### Configuration File
211

212
Create a configuration file for persistent settings.
213

214
```python
215
# ~/.insightface/config.py
216
DEFAULT_ROOT = '/opt/insightface/models'
217
DEFAULT_CTX_ID = 0
218
DOWNLOAD_TIMEOUT = 300
219
VERIFY_DOWNLOADS = True
220
```
221

222
## Advanced CLI Usage
223

224
### Custom Scripts Integration
225

226
Integrate CLI commands into shell scripts and automation workflows.
227

228
```bash
229
#!/bin/bash
230
# setup_insightface.sh - Complete InsightFace setup script
231

232
set -e
233

234
echo "Setting up InsightFace..."
235

236
# Create model directory
237
mkdir -p ./models
238

239
# Download required models
240
echo "Downloading models..."
241
insightface-cli model.download buffalo_l --root ./models
242
insightface-cli model.download buffalo_s --root ./models
243

244
# Process training datasets if they exist
245
if [ -d "./datasets/original" ]; then
246
    echo "Processing training datasets..."
247
    mkdir -p ./datasets/processed
248
    
249
    for dataset in ./datasets/original/*.rec; do
250
        if [ -f "$dataset" ]; then
251
            filename=$(basename "$dataset")
252
            insightface-cli rec.add_mask_param \
253
                --input "$dataset" \
254
                --output "./datasets/processed/masked_$filename"
255
        fi
256
    done
257
fi
258

259
echo "InsightFace setup completed!"
260
```
261

262
### Docker Integration
263

264
Use CLI commands in Docker containers for reproducible deployments.
265

266
```dockerfile
267
FROM python:3.8-slim
268

269
# Install InsightFace
270
RUN pip install insightface
271

272
# Download models during build
273
RUN insightface-cli model.download buffalo_l --root /opt/models
274

275
# Set default model directory
276
ENV INSIGHTFACE_ROOT=/opt/models
277

278
COPY app.py /app/
279
WORKDIR /app
280

281
CMD ["python", "app.py"]
282
```
283

284
### Monitoring and Logging
285

286
Add monitoring and logging to CLI operations.
287

288
```python
289
import logging
290
from insightface.commands.model_download import ModelDownloadCommand
291

292
# Configure logging
293
logging.basicConfig(
294
    level=logging.INFO,
295
    format='%(asctime)s - %(levelname)s - %(message)s',
296
    handlers=[
297
        logging.FileHandler('insightface_cli.log'),
298
        logging.StreamHandler()
299
    ]
300
)
301

302
def monitored_model_download(model_name, root_dir='./models'):
303
    """Download model with comprehensive logging."""
304
    logger = logging.getLogger(__name__)
305
    
306
    logger.info(f"Starting download of model: {model_name}")
307
    
308
    try:
309
        cmd = ModelDownloadCommand(model=model_name, root=root_dir, force=False)
310
        cmd.run()
311
        logger.info(f"Successfully downloaded model: {model_name}")
312
        return True
313
    except Exception as e:
314
        logger.error(f"Failed to download model {model_name}: {e}")
315
        return False
316

317
# Use monitored download
318
success = monitored_model_download('buffalo_l')
319
```
320

321
## Troubleshooting
322

323
### Common Issues and Solutions
324

325
#### Download Failures
326
```bash
327
# Retry with force flag
328
insightface-cli model.download buffalo_l --force
329

330
# Check network connectivity
331
curl -I https://github.com/deepinsight/insightface/releases
332

333
# Use custom root directory with write permissions
334
insightface-cli model.download buffalo_l --root /tmp/models
335
```
336

337
#### Permission Issues
338
```bash
339
# Use user directory
340
insightface-cli model.download buffalo_l --root ~/.insightface
341

342
# Fix permissions
343
chmod -R 755 ~/.insightface
344
```
345

346
#### Storage Space Issues
347
```bash
348
# Check available space
349
df -h ~/.insightface
350

351
# Clean up old models
352
rm -rf ~/.insightface/models/old_model_pack
353

354
# Use external storage
355
insightface-cli model.download buffalo_l --root /external/storage/models
356
```