0
# Command Line Interface
1
2
The Internet Archive Python library provides a comprehensive command-line interface through the `ia` command, offering access to all major Archive.org operations directly from the terminal.
3
4
## Core Commands
5
6
### Configuration
7
8
Set up and manage Archive.org credentials.
9
10
```bash
11
# Configure credentials interactively
12
ia configure
13
14
# Configure with specific credentials
15
ia configure --username your-email@example.com --password your-password
16
17
# Configure with specific config file
18
ia configure --config-file /path/to/config.ini
19
```
20
21
### Item Operations
22
23
Manage Archive.org items and their metadata.
24
25
```bash
26
# Upload files to create or update an item
27
ia upload my-item-id file1.pdf file2.txt --metadata='title:My Document Collection' --metadata='creator:Your Name'
28
29
# Upload with metadata file
30
ia upload my-item-id files/ --metadata=metadata.json
31
32
# Upload with specific options
33
ia upload my-item-id file.pdf --verify --checksum --queue-derive
34
```
35
36
### Download Operations
37
38
Download files from Archive.org items with extensive filtering options.
39
40
```bash
41
# Download all files from an item
42
ia download example-item
43
44
# Download specific files
45
ia download example-item file1.pdf file2.txt
46
47
# Download by format
48
ia download example-item --format=pdf --format=epub
49
50
# Download with pattern matching
51
ia download example-item --glob='*.txt'
52
53
# Download to specific directory
54
ia download example-item --destdir=./downloads
55
56
# Download with verification
57
ia download example-item --checksum --verify
58
59
# Dry run (show what would be downloaded)
60
ia download example-item --dry-run
61
```
62
63
### Search Operations
64
65
Search Archive.org with advanced query options.
66
67
```bash
68
# Basic search
69
ia search 'collection:nasa'
70
71
# Search with field selection
72
ia search 'collection:movies' --fields=identifier,title,creator
73
74
# Search with sorting
75
ia search 'collection:books' --sort='downloads desc'
76
77
# Search with output formats
78
ia search 'mediatype:texts' --output-format=json
79
ia search 'mediatype:texts' --output-format=csv
80
81
# Full-text search
82
ia search 'artificial intelligence' --full-text
83
84
# Advanced search with parameters
85
ia search 'collection:opensource' --rows=100 --page=2
86
```
87
88
### File Management
89
90
List and delete files from items.
91
92
```bash
93
# List all files in an item
94
ia list example-item
95
96
# List with specific formats
97
ia list example-item --format=pdf
98
99
# List with glob pattern
100
ia list example-item --glob='*.txt'
101
102
# List with detailed information
103
ia list example-item --columns=name,size,format,md5
104
105
# Delete files
106
ia delete example-item file1.pdf file2.txt
107
108
# Delete by format
109
ia delete example-item --format=tmp
110
111
# Delete with pattern
112
ia delete example-item --glob='*_backup.*'
113
114
# Delete with cascade (derived files)
115
ia delete example-item file.pdf --cascade
116
```
117
118
### Metadata Operations
119
120
View and modify item metadata.
121
122
```bash
123
# View item metadata
124
ia metadata example-item
125
126
# View specific metadata fields
127
ia metadata example-item --fields=title,creator,date
128
129
# Modify metadata
130
ia metadata example-item --modify='title:New Title' --modify='creator:New Author'
131
132
# Append to metadata
133
ia metadata example-item --append='subject:new-keyword'
134
135
# Modify metadata from file
136
ia metadata example-item --modify=metadata.json
137
138
# Target specific metadata section
139
ia metadata example-item --target=files/document.pdf --modify='title:Chapter Title'
140
```
141
142
### Task Management
143
144
Manage Archive.org catalog tasks.
145
146
```bash
147
# View tasks for an item
148
ia tasks example-item
149
150
# View all user tasks
151
ia tasks --submitter=username
152
153
# View task summary
154
ia tasks example-item --summary
155
156
# View completed tasks
157
ia tasks example-item --history
158
159
# View queued/running tasks
160
ia tasks example-item --catalog
161
162
# Get task log
163
ia tasks --task-id=12345 --log
164
```
165
166
### Copy and Move Operations
167
168
Copy or move files between items.
169
170
```bash
171
# Copy files between items
172
ia copy source-item target-item file1.pdf file2.txt
173
174
# Copy all files
175
ia copy source-item target-item
176
177
# Copy with metadata
178
ia copy source-item target-item --metadata='title:Copied Item'
179
180
# Move files between items
181
ia move source-item target-item file1.pdf
182
183
# Move with metadata update
184
ia move source-item target-item --metadata='collection:new-collection'
185
```
186
187
### Account Management
188
189
Manage Archive.org user accounts (requires admin privileges).
190
191
```bash
192
# View account information
193
ia account info username
194
195
# Lock account
196
ia account lock username --comment='Policy violation'
197
198
# Unlock account
199
ia account unlock username --comment='Issue resolved'
200
```
201
202
### Review Management
203
204
Manage item reviews.
205
206
```bash
207
# View item reviews
208
ia reviews example-item
209
210
# Submit item review
211
ia reviews example-item --review='Excellent content' --stars=5
212
213
# Moderate reviews (requires privileges)
214
ia reviews example-item --moderate --approve=review-id
215
```
216
217
### Flag Management
218
219
Flag items for administrative review and content moderation.
220
221
```bash
222
# Flag an item with reason
223
ia flag example-item --reason='Copyright concern'
224
ia flag example-item --reason='Inappropriate content'
225
ia flag example-item --reason='Spam'
226
227
# View flags for an item
228
ia flag example-item --list
229
230
# Remove a flag (requires privileges)
231
ia flag example-item --unflag --reason='Issue resolved'
232
233
# Flag with detailed comment
234
ia flag example-item --reason='Copyright violation' --comment='DMCA request received'
235
```
236
237
### Simple Lists Management
238
239
Manage simple lists within collections for organizing items.
240
241
```bash
242
# Add items to a simple list
243
ia simplelists collection-name/list-name --add=item1,item2,item3
244
245
# Remove items from a simple list
246
ia simplelists collection-name/list-name --remove=item1,item2
247
248
# View items in a simple list
249
ia simplelists collection-name/list-name --view
250
251
# Create a new simple list
252
ia simplelists collection-name/new-list --create --add=initial-item
253
254
# List all simple lists in a collection
255
ia simplelists collection-name --list-all
256
257
# Clear all items from a simple list
258
ia simplelists collection-name/list-name --clear
259
260
# Copy items from one list to another
261
ia simplelists source-collection/source-list --copy-to=target-collection/target-list
262
```
263
264
## Command Options and Parameters
265
266
### Global Options
267
268
Options available for most commands:
269
270
```bash
271
# Configuration
272
--config-file PATH # Use specific config file
273
--access-key KEY # Override access key
274
--secret-key KEY # Override secret key
275
276
# Output control
277
--verbose # Enable verbose output
278
--quiet # Suppress output
279
--debug # Enable debug logging
280
--no-color # Disable colored output
281
282
# Format options
283
--output-format FORMAT # Output format (json, csv, yaml)
284
--columns COLUMNS # Specify output columns
285
```
286
287
### Upload-Specific Options
288
289
```bash
290
--metadata KEY:VALUE # Set metadata field
291
--header KEY:VALUE # Set HTTP header
292
--verify # Verify upload integrity
293
--checksum # Calculate checksums
294
--queue-derive # Queue derive task after upload
295
--delete # Delete local files after upload
296
--retries N # Number of retry attempts
297
--size-hint N # Expected upload size
298
--no-derive # Skip derive task
299
--spreadsheet # Upload spreadsheet data
300
--file-metadata # Include file-level metadata
301
--status-check # Check upload status
302
```
303
304
### Download-Specific Options
305
306
```bash
307
--format FORMAT # Download specific formats
308
--glob PATTERN # Download files matching pattern
309
--exclude PATTERN # Exclude files matching pattern
310
--destdir PATH # Destination directory
311
--no-directory # Don't create item directory
312
--dry-run # Show what would be downloaded
313
--checksum # Verify checksums
314
--ignore-existing # Re-download existing files
315
--on-the-fly # Include on-the-fly files
316
--timeout N # Request timeout
317
```
318
319
### Search-Specific Options
320
321
```bash
322
--fields FIELDS # Comma-separated field list
323
--sort CRITERIA # Sort criteria
324
--rows N # Number of results per page
325
--page N # Page number
326
--full-text # Enable full-text search
327
--dsl-fts # Enable DSL full-text search
328
--output-format FORMAT # Output format
329
--itemlist # Output as item list
330
```
331
332
### Flag-Specific Options
333
334
```bash
335
--reason REASON # Reason for flagging
336
--comment COMMENT # Additional comment for flag
337
--list # List existing flags
338
--unflag # Remove a flag
339
```
340
341
### Simplelists-Specific Options
342
343
```bash
344
--add ITEMS # Add comma-separated items to list
345
--remove ITEMS # Remove comma-separated items from list
346
--view # View items in list
347
--create # Create new list
348
--list-all # List all lists in collection
349
--clear # Clear all items from list
350
--copy-to TARGET # Copy items to target list
351
```
352
353
## Usage Examples
354
355
### Complete Upload Workflow
356
357
```bash
358
# Create comprehensive item upload
359
ia upload my-research-2024 \
360
paper.pdf slides.pptx data.csv \
361
--metadata='title:My Research Project 2024' \
362
--metadata='creator:Dr. Jane Smith' \
363
--metadata='description:Research findings on climate change' \
364
--metadata='subject:climate change' \
365
--metadata='subject:research' \
366
--metadata='date:2024-01-15' \
367
--metadata='collection:opensource' \
368
--verify --checksum --queue-derive
369
```
370
371
### Batch Download Operations
372
373
```bash
374
# Download all PDFs from NASA collection items
375
ia search 'collection:nasa AND mediatype:texts' --fields=identifier |\
376
while read identifier; do
377
echo "Downloading PDFs from $identifier"
378
ia download "$identifier" --format=pdf --destdir=./nasa-pdfs/
379
done
380
```
381
382
### Metadata Management
383
384
```bash
385
# Bulk metadata update
386
echo "item1\nitem2\nitem3" | while read item; do
387
ia metadata "$item" \
388
--modify='subject:updated-2024' \
389
--modify='contributor:Metadata Team' \
390
--append
391
done
392
```
393
394
### Search and Analysis
395
396
```bash
397
# Generate CSV report of collection items
398
ia search 'collection:mydata' \
399
--fields=identifier,title,creator,date,downloads \
400
--sort='downloads desc' \
401
--rows=1000 \
402
--output-format=csv > collection_report.csv
403
```
404
405
### Task Monitoring
406
407
```bash
408
# Monitor derive tasks for an item
409
while true; do
410
echo "$(date): Checking tasks for my-item"
411
ia tasks my-item --summary
412
413
# Check if no tasks pending
414
if ia tasks my-item --summary | grep -q "queued.*0.*running.*0"; then
415
echo "All tasks completed!"
416
break
417
fi
418
419
sleep 30
420
done
421
```
422
423
### Content Moderation Workflow
424
425
```bash
426
#!/bin/bash
427
# Content moderation workflow
428
429
# Flag suspicious items
430
for item in $(ia search 'uploader:suspicious-user' --fields=identifier); do
431
echo "Reviewing item: $item"
432
433
# Check item metadata
434
ia metadata "$item" --fields=title,description,creator
435
436
# Flag for review if needed
437
read -p "Flag this item? (y/n): " flag_choice
438
if [ "$flag_choice" = "y" ]; then
439
read -p "Enter reason: " reason
440
ia flag "$item" --reason="$reason"
441
echo "Flagged $item for review"
442
fi
443
done
444
```
445
446
### Collection Management
447
448
```bash
449
#!/bin/bash
450
# Manage featured items in a collection
451
452
COLLECTION="my-collection"
453
FEATURED_LIST="featured-items"
454
455
# Add new featured items
456
ia simplelists "$COLLECTION/$FEATURED_LIST" --add=item1,item2,item3
457
458
# View current featured items
459
echo "Current featured items:"
460
ia simplelists "$COLLECTION/$FEATURED_LIST" --view
461
462
# Remove outdated items
463
ia simplelists "$COLLECTION/$FEATURED_LIST" --remove=old-item1,old-item2
464
465
# Create a backup list
466
ia simplelists "$COLLECTION/featured-backup" --create
467
ia simplelists "$COLLECTION/$FEATURED_LIST" --copy-to="$COLLECTION/featured-backup"
468
```
469
470
## Configuration and Environment
471
472
### Configuration File Locations
473
474
The `ia` command looks for configuration in these locations:
475
476
1. `~/.config/internetarchive/ia.ini` (Linux/macOS)
477
2. `~/.ia` (legacy location)
478
3. Path specified with `--config-file`
479
480
### Environment Variables
481
482
Supported environment variables:
483
484
```bash
485
export IA_CONFIG_FILE=/path/to/config.ini
486
export IA_ACCESS_KEY=your-access-key
487
export IA_SECRET_KEY=your-secret-key
488
```
489
490
### Shell Integration
491
492
```bash
493
# Add tab completion (bash)
494
eval "$(ia --bash-completion)"
495
496
# Add to .bashrc for permanent completion
497
echo 'eval "$(ia --bash-completion)"' >> ~/.bashrc
498
```
499
500
## Error Handling and Debugging
501
502
### Common Error Resolution
503
504
```bash
505
# Enable debug output
506
ia --debug download example-item
507
508
# Check authentication
509
ia configure --check
510
511
# Test connection
512
ia metadata archive.org
513
514
# Validate identifiers
515
ia upload test-item file.txt --dry-run
516
```
517
518
### Logging and Monitoring
519
520
```bash
521
# Enable detailed logging
522
ia --verbose --debug upload my-item files/ 2>&1 | tee upload.log
523
524
# Monitor long-running operations
525
ia download large-item --verbose | while read line; do
526
echo "$(date): $line"
527
done
528
```