CLI Overview¶

The gpio command provides a comprehensive CLI for GeoParquet file operations.

Command Structure¶

gpio [OPTIONS] COMMAND [ARGS]...

Available Commands¶

Core Commands¶

convert - Convert vector formats to optimized GeoParquet
inspect - Examine file metadata and preview data
check - Validate files and fix issues automatically
sort - Spatially sort using Hilbert curves
add - Enhance files with spatial indices
partition - Split files into optimized partitions
upload - Upload files to cloud storage (S3, GCS, Azure)
stac - Generate STAC metadata for datasets
benchmark - Compare conversion performance

Global Options¶

--version    # Show version number
--help       # Show help message

Getting Help¶

Every command has detailed help:

# General help
gpio --help

# Command group help
gpio add --help
gpio partition --help
gpio check --help

# Specific command help
gpio add bbox --help
gpio partition h3 --help
gpio check spatial --help
gpio stac --help

Legacy Alias¶

The gt command is available as an alias for backwards compatibility:

gt inspect myfile.parquet  # Same as: gpio inspect myfile.parquet

Common Patterns¶

File Operations¶

Most commands follow this pattern:

gpio COMMAND INPUT OUTPUT [OPTIONS]

Examples:

gpio add bbox input.parquet output.parquet
gpio sort hilbert input.parquet sorted.parquet

In-Place Operations¶

Some commands modify files in place:

gpio add bbox-metadata myfile.parquet
gpio check all myfile.parquet --fix

Analysis Commands¶

Analysis commands take a single input:

gpio inspect myfile.parquet
gpio check all myfile.parquet

Partition Commands¶

Partition commands output to directories:

gpio partition h3 input.parquet output_dir/

Common Options¶

Many commands share these options:

# Compression settings
--compression [ZSTD|GZIP|BROTLI|LZ4|SNAPPY|UNCOMPRESSED]
--compression-level [1-22]

# Row group sizing
--row-group-size [exact row count]
--row-group-size-mb [target size like '256MB' or '1GB']

# Workflow options
--dry-run          # Preview SQL without executing
--verbose          # Detailed output
--preview          # Preview results (partition commands)
--hive             # Use Hive-style partitioning
--overwrite        # Overwrite existing files

--force        # Override warnings

Exit Codes¶

0 - Success
1 - Error (with error message printed)
2 - Invalid usage (incorrect arguments)

Next Steps¶

Explore individual command references for detailed options and examples.