0
# Command Line Interface
1

2
Complete command-line interface with 23+ subcommands for raster operations including format conversion, reprojection, masking, analysis, and data exploration. The `rio` command provides comprehensive raster processing capabilities from the command line.
3

4
## Capabilities
5

6
### Information Commands
7

8
Commands for examining raster dataset properties and metadata.
9

10
```bash { .api }
11
# Display comprehensive dataset information
12
rio info [OPTIONS] INPUT
13

14
# Print geographic bounds of dataset  
15
rio bounds [OPTIONS] INPUT
16

17
# Show dataset block structure
18
rio blocks [OPTIONS] INPUT
19

20
# Print ground control points
21
rio gcps [OPTIONS] INPUT
22

23
# Show GDAL environment information
24
rio env [OPTIONS]
25
```
26

27
Usage examples:
28

29
```bash
30
# Get detailed dataset information
31
rio info landsat_scene.tif
32
rio info --indent 2 landsat_scene.tif  # Pretty-printed JSON
33
rio info --count landsat_scene.tif     # Include pixel counts
34

35
# Get geographic bounds
36
rio bounds landsat_scene.tif
37
rio bounds --dst-crs EPSG:3857 landsat_scene.tif  # Transform bounds to different CRS
38

39
# Examine internal block structure  
40
rio blocks landsat_scene.tif
41
rio blocks --bidx 1 landsat_scene.tif  # Specific band only
42

43
# Check ground control points
44
rio gcps landsat_scene.tif
45

46
# Display environment information
47
rio env
48
rio env --formats  # Show supported formats
49
```
50

51
### Transformation Commands
52

53
Commands for coordinate and spatial transformations.
54

55
```bash { .api }
56
# Transform coordinates between CRS
57
rio transform [OPTIONS] INPUT
58

59
# Warp raster to new CRS or resolution  
60
rio warp [OPTIONS] INPUT OUTPUT
61

62
# Reproject raster dataset
63
rio reproject [OPTIONS] INPUT OUTPUT
64
```
65

66
Usage examples:
67

68
```bash
69
# Transform point coordinates
70
echo "-120.5 35.2" | rio transform --dst-crs EPSG:3857 input.tif
71

72
# Transform with different precision
73
echo "-120.5 35.2" | rio transform --precision 2 --dst-crs EPSG:3857 input.tif
74

75
# Warp to new projection
76
rio warp --dst-crs EPSG:3857 --resampling bilinear input.tif output_mercator.tif
77

78
# Warp with custom resolution
79
rio warp --dst-crs EPSG:3857 --res 30 input.tif output_30m.tif
80

81
# Warp with specific bounds
82
rio warp --bounds -13580000 4200000 -13570000 4210000 input.tif cropped.tif
83

84
# Reproject with compression
85
rio reproject --dst-crs EPSG:4326 --compress lzw input.tif output_wgs84.tif
86
```
87

88
### Processing Commands
89

90
Commands for raster processing and analysis operations.
91

92
```bash { .api }
93
# Merge multiple rasters into mosaic
94
rio merge [OPTIONS] INPUT... OUTPUT
95

96
# Apply vector mask to raster
97
rio mask [OPTIONS] INPUT FEATURES OUTPUT
98

99
# Clip raster to geometry bounds  
100
rio clip [OPTIONS] INPUT FEATURES OUTPUT
101

102
# Raster calculator operations
103
rio calc [OPTIONS] COMMAND INPUT... OUTPUT
104

105
# Sample raster values at coordinates
106
rio sample [OPTIONS] INPUT
107
```
108

109
Usage examples:
110

111
```bash
112
# Merge multiple GeoTIFF files
113
rio merge tile1.tif tile2.tif tile3.tif mosaic.tif
114
rio merge --bounds -180 -90 180 90 tiles/*.tif world_mosaic.tif
115

116
# Apply shapefile mask
117
rio mask --crop landsat_scene.tif study_area.shp masked_scene.tif
118
rio mask --invert landsat_scene.tif water_bodies.shp land_only.tif
119

120
# Clip to vector bounds
121
rio clip landsat_scene.tif study_area.shp clipped_scene.tif
122

123
# Calculator operations
124
rio calc "(+ (read 1) (read 2))" band1.tif band2.tif sum.tif
125
rio calc "(* (read 1) 2)" input.tif doubled.tif
126
rio calc "(where (> (read 1) 100) 1 0)" input.tif binary.tif
127

128
# Sample values at points
129
echo "-120.5 35.2" | rio sample input.tif
130
echo "-120.5 35.2\n-119.8 35.9" | rio sample --bidx 1,2,3 rgb_image.tif
131
```
132

133
### Conversion Commands
134

135
Commands for format conversion and data translation.
136

137
```bash { .api }
138
# Convert between raster formats
139
rio convert [OPTIONS] INPUT OUTPUT
140

141
# Translate datasets (GDAL wrapper)
142
rio translate [OPTIONS] INPUT OUTPUT
143

144
# Stack bands from multiple files
145
rio stack [OPTIONS] INPUT... OUTPUT
146
```
147

148
Usage examples:
149

150
```bash
151
# Convert format
152
rio convert input.tif output.jpg
153
rio convert --format PNG input.tif output.png
154

155
# Translate with options
156
rio translate --compress lzw --tiled input.tif output.tif
157
rio translate --dtype uint8 --scale-ratio 0.1 float_input.tif scaled_output.tif
158

159
# Stack bands into single file
160
rio stack red.tif green.tif blue.tif rgb_composite.tif
161
rio stack --bidx 1 *.tif stacked_band1.tif
162
```
163

164
### Shape Operations
165

166
Commands for extracting and working with vector shapes from raster data.
167

168
```bash { .api }
169
# Extract polygon shapes from raster
170
rio shapes [OPTIONS] INPUT
171

172
# Rasterize vector features  
173
rio rasterize [OPTIONS] FEATURES INPUT OUTPUT
174
```
175

176
Usage examples:
177

178
```bash
179
# Extract shapes to GeoJSON
180
rio shapes landcover.tif > landcover_polygons.geojson
181
rio shapes --mask nodata_mask.tif --precision 6 landcover.tif > shapes.geojson
182

183
# Rasterize shapefile
184
rio rasterize --like template.tif polygons.shp rasterized.tif
185
rio rasterize --dimensions 1000 1000 --res 0.001 points.shp density.tif
186
rio rasterize --burn 1 --all-touched lines.shp line_raster.tif
187
```
188

189
### Overview and Optimization
190

191
Commands for creating overviews and optimizing raster datasets.
192

193
```bash { .api }
194
# Build overview images
195
rio overview [OPTIONS] INPUT
196

197
# Edit dataset metadata  
198
rio edit-info [OPTIONS] INPUT
199
```
200

201
Usage examples:
202

203
```bash
204
# Build overviews with default settings
205
rio overview build input.tif
206

207
# Build overviews with specific resampling  
208
rio overview build --resampling average input.tif
209

210
# Build overviews with custom factors
211
rio overview build --factors 2,4,8,16 input.tif
212

213
# List existing overviews
214
rio overview list input.tif
215

216
# Edit dataset information
217
rio edit-info --crs EPSG:4326 input.tif
218
rio edit-info --nodata -9999 input.tif
219
rio edit-info --tag "DESCRIPTION=Processed satellite imagery" input.tif
220
```
221

222
### Dataset Creation
223

224
Commands for creating new raster datasets.
225

226
```bash { .api }
227
# Create new raster dataset  
228
rio create [OPTIONS] OUTPUT
229

230
# Inspect dataset interactively
231
rio insp [OPTIONS] INPUT
232
```
233

234
Usage examples:
235

236
```bash
237
# Create new empty raster
238
rio create --driver GTiff --width 1000 --height 1000 --count 3 --dtype uint8 --crs EPSG:4326 new_raster.tif
239

240
# Inspect dataset in interactive mode
241
rio insp landsat_scene.tif
242
```
243

244
### Utility Commands
245

246
General utility commands for file management and operations.
247

248
```bash { .api }
249
# Remove raster files and associated files
250
rio rm [OPTIONS] INPUT...
251
```
252

253
Usage examples:
254

255
```bash
256
# Remove single file and auxiliaries
257
rio rm dataset.tif
258

259
# Remove multiple files
260
rio rm tile*.tif
261

262
# Remove with confirmation
263
rio rm --dry-run large_dataset.tif  # Show what would be deleted
264
```
265

266
### Global Options
267

268
Common options available across multiple commands:
269

270
```bash { .api }
271
# Global options (available for most commands)
272
--verbose, -v          # Increase verbosity
273
--quiet, -q           # Suppress output  
274
--format DRIVER       # Output format driver
275
--co NAME=VALUE       # Creation options
276
--compress METHOD     # Compression method
277
--dtype TYPE          # Data type
278
--nodata VALUE        # NoData value
279
--crs CRS            # Coordinate reference system
280
--resampling METHOD   # Resampling algorithm
281
--threads N          # Number of processing threads
282
```
283

284
### Advanced Usage Patterns
285

286
Complex workflows combining multiple commands:
287

288
```bash
289
# Processing pipeline example
290
# 1. Get dataset info
291
rio info --count input.tif
292

293
# 2. Warp to standard projection  
294
rio warp --dst-crs EPSG:3857 --compress lzw input.tif warped.tif
295

296
# 3. Apply mask and crop
297
rio mask --crop warped.tif study_area.shp masked.tif
298

299
# 4. Calculate vegetation index
300
rio calc "(/ (- (read 4) (read 3)) (+ (read 4) (read 3)))" masked.tif ndvi.tif
301

302
# 5. Extract high NDVI areas
303
rio calc "(where (> (read 1) 0.5) (read 1) 0)" ndvi.tif high_ndvi.tif
304

305
# 6. Convert to shapes
306
rio shapes --mask high_ndvi.tif high_ndvi.tif > vegetation_polygons.geojson
307

308
# Batch processing with shell scripting
309
for file in *.tif; do
310
    output="${file%.tif}_processed.tif"
311
    rio warp --dst-crs EPSG:4326 --compress lzw "$file" "$output"
312
done
313

314
# Piping coordinates for sampling
315
cat coordinates.txt | rio sample --bidx 1,2,3 landsat.tif > sampled_values.txt
316

317
# Using with other tools
318
rio bounds *.tif | jq -s 'map(select(.bounds)) | .[].bounds' > all_bounds.json
319
```
320

321
### Output Formats
322

323
The CLI supports numerous output formats through GDAL drivers:
324

325
```bash
326
# Common format examples
327
rio convert input.tif output.jpg        # JPEG
328
rio convert input.tif output.png        # PNG  
329
rio convert input.tif output.nc         # NetCDF
330
rio convert --format COG input.tif output.tif  # Cloud Optimized GeoTIFF
331
rio convert --format GTiff --co TILED=YES input.tif tiled.tif  # Tiled GeoTIFF
332

333
# List available formats
334
rio env --formats
335
```
336

337
### Error Handling
338

339
The CLI provides detailed error messages and return codes:
340

341
```bash
342
# Check command success
343
rio info nonexistent.tif
344
echo $?  # Returns non-zero exit code on error
345

346
# Verbose error information
347
rio --verbose warp invalid_crs.tif output.tif
348

349
# Dry run mode (where available)
350
rio overview build --dry-run input.tif  # Show what would be done
351
```