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
extract - Filter and subset GeoParquet files
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
benchmark - Compare conversion performance

publish¶

Upload files to cloud storage and generate STAC metadata for datasets. Use gpio publish upload for cloud storage uploads and gpio publish stac for STAC metadata generation.

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 convert reproject --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
gpio check spec myfile.parquet

Partition Commands¶

Partition commands output to directories:

gpio partition h3 input.parquet output_dir/

Command Piping¶

Chain commands with Unix pipes for efficient multi-step workflows:

gpio add bbox input.parquet | gpio sort hilbert - output.parquet

Use - as input to read from stdin. See the Piping Guide for details.

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
--profile NAME     # AWS profile for S3 operations

--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.