0
# Command Line Interface
1

2
py7zr provides comprehensive command-line tools for working with 7z archives, supporting all major archive operations including create, extract, list, test, and info commands. The CLI supports password protection, multi-volume archives, and various compression options.
3

4
## Capabilities
5

6
### CLI Entry Point
7

8
Main entry point for command-line operations.
9

10
```python { .api }
11
def main():
12
    """
13
    Main CLI entry point function.
14
    
15
    Parses command line arguments and executes appropriate archive operations.
16
    Called when running 'py7zr' command or 'python -m py7zr'.
17
    """
18
```
19

20
### Command Overview
21

22
The py7zr CLI supports the following commands:
23

24
- **c**: Create archive with files and directories
25
- **x**: Extract files from archive with full paths  
26
- **l**: List contents of archive
27
- **t**: Test integrity of archive
28
- **i**: Show information about supported formats
29

30
## Command Usage
31

32
### Create Archive (c)
33

34
Create new 7z archives from files and directories.
35

36
```bash
37
# Create archive from directory
38
py7zr c archive.7z /path/to/directory
39

40
# Create archive from multiple files
41
py7zr c archive.7z file1.txt file2.txt directory/
42

43
# Create archive with password
44
py7zr c -P archive.7z /path/to/directory
45
password?: ****
46

47
# Create multi-volume archive (500KB volumes)
48
py7zr c -v 500k archive.7z /path/to/large_directory
49

50
# Create archive with compression level
51
py7zr c -l 9 archive.7z /path/to/directory
52

53
# Create archive excluding files
54
py7zr c -x '*.tmp' archive.7z /path/to/directory
55
```
56

57
**Options:**
58
- `-P`: Prompt for password to encrypt archive
59
- `-v SIZE`: Create multi-volume archive with specified volume size (k/m/g suffixes)
60
- `-l LEVEL`: Set compression level (0-9, default varies by algorithm)
61
- `-x PATTERN`: Exclude files matching pattern
62

63
### Extract Archive (x)
64

65
Extract files from 7z archives with full directory paths.
66

67
```bash
68
# Extract entire archive to current directory
69
py7zr x archive.7z
70

71
# Extract to specific directory
72
py7zr x archive.7z -o /tmp/extracted
73

74
# Extract password-protected archive
75
py7zr x -P archive.7z
76
password?: ****
77

78
# Extract specific files only
79
py7zr x archive.7z file1.txt directory/file2.txt
80

81
# Extract with overwrite confirmation
82
py7zr x -y archive.7z
83

84
# Extract without creating subdirectories (flatten)
85
py7zr x -j archive.7z
86
```
87

88
**Options:**
89
- `-o PATH`: Extract to specified output directory
90
- `-P`: Prompt for password for encrypted archives
91
- `-y`: Assume yes to all prompts (overwrite existing files)
92
- `-j`: Extract without directory structure (junk paths)
93

94
### List Contents (l)
95

96
Display contents and information about files in 7z archives.
97

98
```bash
99
# List all files in archive
100
py7zr l archive.7z
101

102
# List with detailed information
103
py7zr l -v archive.7z
104

105
# List specific files/patterns
106
py7zr l archive.7z '*.txt'
107

108
# List password-protected archive
109
py7zr l -P archive.7z
110
password?: ****
111
```
112

113
**Options:**
114
- `-v`: Verbose listing with detailed file information
115
- `-P`: Prompt for password for encrypted archives
116

117
**Output Format:**
118
```
119
Date      Time    Attr         Size   Compressed  Name
120
--------- -----  ----------  -------  ----------  --------
121
2023-01-15 10:30  .....A....     1024        512  readme.txt
122
2023-01-15 10:31  D.....A....        0          0  docs/
123
2023-01-15 10:31  .....A....     2048       1024  docs/manual.pdf
124
--------- -----  ----------  -------  ----------  --------
125
                                3072       1536  3 files, 1 folders
126
```
127

128
### Test Archive (t)
129

130
Verify integrity of 7z archives by testing decompression without extracting files.
131

132
```bash
133
# Test entire archive
134
py7zr t archive.7z
135

136
# Test password-protected archive
137
py7zr t -P archive.7z
138
password?: ****
139

140
# Test specific files
141
py7zr t archive.7z file1.txt directory/
142
```
143

144
**Options:**
145
- `-P`: Prompt for password for encrypted archives
146

147
**Output:**
148
```
149
Testing archive: archive.7z
150

151
Extracting  readme.txt     OK
152
Extracting  docs/manual.pdf     OK
153

154
Everything is Ok
155

156
Archives: 1
157
Files: 2
158
Size:       3072
159
Compressed: 1536
160
```
161

162
### Show Information (i)
163

164
Display information about supported compression methods, filters, and formats.
165

166
```bash
167
# Show all supported formats and methods
168
py7zr i
169

170
# Show version information
171
py7zr --version
172
```
173

174
**Output Example:**
175
```
176
7-Zip [64] 21.07 : py7zr [Python] 0.20.0
177

178
Formats:
179
 C  7z
180

181
Methods:
182
 C  LZMA2   LZMA   BZip2   Deflate   Copy   ZStandard   Brotli   PPMd
183
 E  7zAES
184

185
Filters:
186
 C  Delta   BCJ(x86)   BCJ(ARM)   BCJ(ARMT)   BCJ(PPC)   BCJ(SPARC)   BCJ(IA64)
187
```
188

189
### Append to Archive (a)
190

191
Add files to existing archives (creates new archive if doesn't exist).
192

193
```bash
194
# Append files to existing archive
195
py7zr a archive.7z new_file.txt new_directory/
196

197
# Append with password (for encrypted archives)
198
py7zr a -P archive.7z additional_files/
199
password?: ****
200
```
201

202
**Options:**
203
- `-P`: Prompt for password for encrypted archives
204

205
## Global Options
206

207
Options that work with multiple commands:
208

209
- `--help`: Show help message and exit
210
- `--version`: Show version information and exit
211
- `-v`: Verbose output (command-specific behavior)
212
- `-P`: Prompt for password
213
- `-o PATH`: Output directory (for extraction)
214
- `-y`: Assume yes to all prompts
215

216
## Usage Examples
217

218
### Complete Workflow Examples
219

220
```bash
221
# Create backup archive
222
py7zr c -l 6 backup_$(date +%Y%m%d).7z ~/Documents ~/Pictures
223

224
# Create encrypted backup
225
py7zr c -P secure_backup.7z ~/sensitive_data
226
password?: my_secure_password
227

228
# Extract and verify
229
py7zr t backup.7z
230
py7zr x backup.7z -o ~/restored_backup
231

232
# Multi-volume archive for large datasets
233
py7zr c -v 1g large_dataset.7z ~/big_data_directory
234

235
# List and selective extraction
236
py7zr l archive.7z
237
py7zr x archive.7z 'docs/*.pdf' 'config/*.json'
238
```
239

240
### Integration with Shell Scripts
241

242
```bash
243
#!/bin/bash
244
# Backup script example
245

246
BACKUP_DIR="/backups"
247
SOURCE_DIR="/home/user/important_data"
248
DATE=$(date +%Y%m%d_%H%M%S)
249
ARCHIVE="$BACKUP_DIR/backup_$DATE.7z"
250

251
# Create compressed backup
252
py7zr c -l 9 "$ARCHIVE" "$SOURCE_DIR"
253

254
# Verify backup integrity
255
if py7zr t "$ARCHIVE"; then
256
    echo "Backup created successfully: $ARCHIVE"
257
else
258
    echo "Backup verification failed!"
259
    exit 1
260
fi
261

262
# Clean old backups (keep last 7 days)
263
find "$BACKUP_DIR" -name "backup_*.7z" -mtime +7 -delete
264
```
265

266
## Error Handling
267

268
The CLI returns appropriate exit codes:
269

270
- **0**: Success
271
- **1**: Warning (some files couldn't be processed)
272
- **2**: Fatal error
273
- **7**: Command line error
274
- **8**: Not enough memory for operation
275
- **255**: User interrupted operation
276

277
Common error scenarios:
278

279
```bash
280
# Handle password-protected archives
281
py7zr x secure.7z || echo "Extraction failed - check password"
282

283
# Check if archive exists before operations
284
if py7zr t archive.7z 2>/dev/null; then
285
    py7zr x archive.7z
286
else
287
    echo "Archive is corrupted or doesn't exist"
288
fi
289
```
290

291
## Environment Variables
292

293
py7zr CLI respects the following environment variables:
294

295
- `PY7ZR_PASSWORD`: Default password for encrypted archives (use with caution)
296
- `TMPDIR`: Directory for temporary files during operations
297

298
## Performance Considerations
299

300
- Use appropriate compression levels (`-l 1` for speed, `-l 9` for compression)
301
- Multi-volume archives (`-v`) can improve handling of very large datasets
302
- Consider available memory when working with large archives
303
- Solid archives provide better compression but slower selective extraction