Skip to content

CLI Overview

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

Command Structure

gpio [OPTIONS] COMMAND [ARGS]...

Available Commands

Core Commands

  • inspect - Examine file metadata and preview data
  • check - Validate files against best practices
  • sort - Spatially sort using Hilbert curves
  • add - Enhance files with spatial indices
  • partition - Split files into optimized partitions
  • format - Apply formatting best practices

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

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 format bbox-metadata myfile.parquet

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

--compression [ZSTD|GZIP|BROTLI|LZ4|SNAPPY|UNCOMPRESSED]
--compression-level [1-22]  # Varies by format

Row Group Sizing

--row-group-size [exact row count]
--row-group-size-mb [target size: '256MB', '1GB', etc.]

Workflow Control

--dry-run      # Preview without executing
--verbose      # Detailed output
--preview      # Preview results (partition commands)
--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.