rasteret.cli

Command-line interface for building collections and browsing the dataset catalog.

If you are starting fresh, the shortest path is: datasets list -> datasets info -> datasets build. Use register-local / export-local / unregister-local after you want reusable local catalog entries.

For a deeper walkthrough of the dataset catalog, see Dataset Catalog.

Common commands:

# Browse the catalog
rasteret datasets list
rasteret datasets info earthsearch/sentinel-2-l2a
rasteret datasets info pc/sentinel-2-l2a

# Build a collection from the catalog
#   datasets build <dataset_id> <name> --bbox <minx,miny,maxx,maxy> --date-range <start,end>
rasteret datasets build earthsearch/sentinel-2-l2a my_s2 \
  --bbox 77.5,12.9,77.7,13.1 --date-range 2024-01-01,2024-06-30

# Manage local collections
rasteret collections list
rasteret collections info my_s2
rasteret collections delete my_s2 --yes

# Build from a catalog entry (top-level shortcut)
rasteret build earthsearch/sentinel-2-l2a my_s2 \
  --bbox 77.5,12.9,77.7,13.1 --date-range 2024-01-01,2024-06-30

# Build from a custom STAC API (not in the catalog)
#   collections build <name> --stac-api <url> --collection <id> --bbox ... --date-range ...
rasteret collections build my_custom \
  --stac-api https://example.com/stac --collection my-collection \
  --bbox 77.5,12.9,77.7,13.1 --date-range 2024-01-01,2024-06-30

# Import a Parquet/GeoParquet table into a local collection
rasteret collections import my_parquet --record-table /path/or/uri.parquet

# Register a local Collection as a reusable catalog entry
rasteret datasets register-local local/my-collection /path/to/collection_parquet
rasteret datasets build local/my-collection my_local_build

# Export or remove local catalog entries
rasteret datasets export-local local/my-collection ./my-collection.dataset.json
rasteret datasets unregister-local local/my-collection

Authenticated datasets

• Planetary Computer (pc/*): install rasteret[azure] for SAS signing.
• Requester-pays Landsat: install rasteret[aws] and configure AWS credentials.

datasets register-local persists catalog entries to ~/.rasteret/datasets.local.json unless --no-persist is passed. datasets export-local writes one catalog entry as a JSON file (for sharing/reuse). datasets unregister-local removes local entries from the persisted registry and current runtime registry.

Use --json on most commands for script-friendly output.

Where do collections end up?

Collections are stored as Parquet datasets under ~/rasteret_workspace/ (or the directory set by --workspace-dir). The directory name follows a convention:

Build method	Directory name
datasets build / build()	{name}_{daterange}_{source}_stac/
collections import / build_from_table()	{name}_records/
collections build / build_from_stac()	{name}_{daterange}_{source}_stac/

For example, datasets build earthsearch/sentinel-2-l2a my_s2 --date-range 2024-01-01,2024-06-30 creates ~/rasteret_workspace/my-s2_202401-06_sentinel_stac/.

Use rasteret collections list to see all local collections and their paths.

cli

Classes

Functions

build_parser

build_parser() -> ArgumentParser

Build the top-level argument parser for the rasteret CLI.

Source code in src/rasteret/cli.py

def build_parser() -> argparse.ArgumentParser:
    """Build the top-level argument parser for the ``rasteret`` CLI."""
    parser = argparse.ArgumentParser(prog="rasteret")
    parser.add_argument(
        "--version",
        action="version",
        version=__version__,
        help="Show the rasteret version and exit.",
    )

    subparsers = parser.add_subparsers(dest="command")

    collections_parser = subparsers.add_parser(
        "collections", help="Manage local collections"
    )
    collections_subparsers = collections_parser.add_subparsers(
        dest="collections_command", required=True
    )

    build_parser = collections_subparsers.add_parser(
        "build", help="Build or refresh a STAC-backed collection cache"
    )
    build_parser.add_argument("name", help="Logical collection name")
    build_parser.add_argument("--stac-api", required=True, help="STAC API URL")
    build_parser.add_argument("--collection", required=True, help="STAC collection id")
    build_parser.add_argument(
        "--bbox",
        required=True,
        type=_parse_bbox,
        help="Bounding box as minx,miny,maxx,maxy",
    )
    build_parser.add_argument(
        "--date-range",
        required=True,
        type=_parse_date_range,
        help="Date range as YYYY-MM-DD,YYYY-MM-DD",
    )
    build_parser.add_argument(
        "--workspace-dir", help="Workspace directory for cached collections"
    )
    build_parser.add_argument(
        "--force",
        action="store_true",
        help="Rebuild cache even if it already exists",
    )
    build_parser.add_argument(
        "--max-concurrent",
        type=int,
        default=50,
        help="Maximum concurrent metadata fetch operations",
    )
    build_parser.add_argument(
        "--query",
        help="Optional STAC search query as JSON string",
    )
    build_parser.add_argument("--json", action="store_true", help="Emit JSON output")

    list_parser = collections_subparsers.add_parser(
        "list", help="List local collections"
    )
    list_parser.add_argument(
        "--workspace-dir", help="Workspace directory for cached collections"
    )
    list_parser.add_argument("--json", action="store_true", help="Emit JSON output")

    info_parser = collections_subparsers.add_parser(
        "info", help="Show details for a local collection"
    )
    info_parser.add_argument("name", help="Collection name or folder name")
    info_parser.add_argument(
        "--workspace-dir", help="Workspace directory for cached collections"
    )
    info_parser.add_argument("--json", action="store_true", help="Emit JSON output")

    delete_parser = collections_subparsers.add_parser(
        "delete", help="Delete a local collection"
    )
    delete_parser.add_argument("name", help="Collection name or folder name")
    delete_parser.add_argument(
        "--workspace-dir", help="Workspace directory for cached collections"
    )
    delete_parser.add_argument(
        "--yes",
        action="store_true",
        help="Skip confirmation prompt",
    )

    import_parser = collections_subparsers.add_parser(
        "import", help="Materialize a local collection from a Parquet record table"
    )
    import_parser.add_argument("name", help="Logical collection name")
    import_parser.add_argument(
        "--record-table",
        required=True,
        help="Parquet/GeoParquet record table path/URI",
    )
    import_parser.add_argument(
        "--data-source",
        default="",
        help="Optional data source identifier for band mapping and URL policy",
    )
    import_parser.add_argument(
        "--column-map",
        help='Optional column rename mapping as JSON (e.g. \'{"scene_id":"id"}\')',
    )
    import_parser.add_argument(
        "--columns",
        help="Optional projected columns (comma-separated) for scan-time pushdown",
    )
    import_parser.add_argument(
        "--workspace-dir", help="Workspace directory for cached collections"
    )
    import_parser.add_argument(
        "--force",
        action="store_true",
        help="Replace an existing imported collection",
    )
    import_parser.add_argument("--json", action="store_true", help="Emit JSON output")

    # --- top-level build shortcut (mirrors rasteret.build()) ---
    top_build_parser = subparsers.add_parser(
        "build", help="Build a collection from a registered dataset"
    )
    top_build_parser.add_argument("dataset_id", help="Dataset ID")
    top_build_parser.add_argument("name", help="Logical collection name")
    top_build_parser.add_argument(
        "--bbox",
        type=_parse_bbox,
        help="Bounding box as minx,miny,maxx,maxy",
    )
    top_build_parser.add_argument(
        "--date-range",
        type=_parse_date_range,
        help="Date range as YYYY-MM-DD,YYYY-MM-DD",
    )
    top_build_parser.add_argument("--workspace-dir", help="Workspace directory")
    top_build_parser.add_argument("--force", action="store_true", help="Rebuild cache")
    top_build_parser.add_argument(
        "--max-concurrent", type=int, default=50, help="Max concurrent fetches"
    )
    top_build_parser.add_argument("--query", help="Additional STAC query as JSON")
    top_build_parser.add_argument(
        "--json", action="store_true", help="Emit JSON output"
    )

    # --- datasets subcommand ---
    ds_parser = subparsers.add_parser("datasets", help="Browse registered datasets")
    ds_subparsers = ds_parser.add_subparsers(dest="ds_command", required=True)

    ds_list_parser = ds_subparsers.add_parser("list", help="List registered datasets")
    ds_list_parser.add_argument("--search", default="", help="Filter by keyword")
    ds_list_parser.add_argument("--json", action="store_true", help="Emit JSON output")

    ds_info_parser = ds_subparsers.add_parser(
        "info", help="Show details for a registered dataset"
    )
    ds_info_parser.add_argument(
        "dataset_id", help="Dataset ID (e.g. earthsearch/sentinel-2-l2a)"
    )
    ds_info_parser.add_argument("--json", action="store_true", help="Emit JSON output")

    ds_build_parser = ds_subparsers.add_parser(
        "build", help="Build a collection from a registered dataset"
    )
    ds_build_parser.add_argument("dataset_id", help="Dataset ID")
    ds_build_parser.add_argument("name", help="Logical collection name")
    ds_build_parser.add_argument(
        "--bbox",
        type=_parse_bbox,
        help="Bounding box as minx,miny,maxx,maxy",
    )
    ds_build_parser.add_argument(
        "--date-range",
        type=_parse_date_range,
        help="Date range as YYYY-MM-DD,YYYY-MM-DD",
    )
    ds_build_parser.add_argument("--workspace-dir", help="Workspace directory")
    ds_build_parser.add_argument("--force", action="store_true", help="Rebuild cache")
    ds_build_parser.add_argument(
        "--max-concurrent", type=int, default=50, help="Max concurrent fetches"
    )
    ds_build_parser.add_argument("--query", help="Additional STAC query as JSON")
    ds_build_parser.add_argument("--json", action="store_true", help="Emit JSON output")

    ds_register_local_parser = ds_subparsers.add_parser(
        "register-local",
        help="Register a local collection/Parquet as a reusable dataset descriptor",
    )
    ds_register_local_parser.add_argument(
        "dataset_id",
        help="Dataset ID (e.g. local/my-dataset)",
    )
    ds_register_local_parser.add_argument(
        "path",
        help="Collection path, Parquet path, or cached collection name",
    )
    ds_register_local_parser.add_argument(
        "--name",
        default="",
        help="Human-readable dataset name",
    )
    ds_register_local_parser.add_argument(
        "--description",
        default="",
        help="Optional one-line description",
    )
    ds_register_local_parser.add_argument(
        "--data-source",
        default="",
        help="Optional source id override (defaults to inferred metadata)",
    )
    ds_register_local_parser.add_argument(
        "--workspace-dir",
        help="Workspace directory (used when path is a cache name)",
    )
    ds_register_local_parser.add_argument(
        "--registry-path",
        help="Override persisted local registry path",
    )
    ds_register_local_parser.add_argument(
        "--no-persist",
        action="store_true",
        help="Register only for this process; do not persist to disk",
    )
    ds_register_local_parser.add_argument(
        "--json",
        action="store_true",
        help="Emit JSON output",
    )

    ds_unregister_local_parser = ds_subparsers.add_parser(
        "unregister-local",
        help="Remove a local dataset descriptor from registry and runtime",
    )
    ds_unregister_local_parser.add_argument(
        "dataset_id",
        help="Dataset ID (e.g. local/my-dataset)",
    )
    ds_unregister_local_parser.add_argument(
        "--registry-path",
        help="Override persisted local registry path",
    )
    ds_unregister_local_parser.add_argument(
        "--json",
        action="store_true",
        help="Emit JSON output",
    )

    ds_export_local_parser = ds_subparsers.add_parser(
        "export-local",
        help="Export a local dataset descriptor as JSON for sharing",
    )
    ds_export_local_parser.add_argument(
        "dataset_id",
        help="Dataset ID (e.g. local/my-dataset)",
    )
    ds_export_local_parser.add_argument(
        "output_path",
        help="Destination JSON path",
    )
    ds_export_local_parser.add_argument(
        "--registry-path",
        help="Override persisted local registry path",
    )
    ds_export_local_parser.add_argument(
        "--json",
        action="store_true",
        help="Emit JSON output",
    )

    return parser

main

main(argv: list[str] | None = None) -> int

Entry point for the rasteret CLI.

Source code in src/rasteret/cli.py

def main(argv: list[str] | None = None) -> int:
    """Entry point for the ``rasteret`` CLI."""
    parser = build_parser()
    args = parser.parse_args(argv)

    if args.command is None:
        parser.print_help()
        return 0

    if args.command == "build":
        return _handle_datasets_build(args)

    if args.command == "collections":
        if args.collections_command == "build":
            return _handle_collections_build(args)
        if args.collections_command == "list":
            return _handle_collections_list(args)
        if args.collections_command == "info":
            return _handle_collections_info(args)
        if args.collections_command == "delete":
            return _handle_collections_delete(args)
        if args.collections_command == "import":
            return _handle_collections_import(args)

    if args.command == "datasets":
        if args.ds_command == "list":
            return _handle_datasets_list(args)
        if args.ds_command == "info":
            return _handle_datasets_info(args)
        if args.ds_command == "build":
            return _handle_datasets_build(args)
        if args.ds_command == "register-local":
            return _handle_datasets_register_local(args)
        if args.ds_command == "unregister-local":
            return _handle_datasets_unregister_local(args)
        if args.ds_command == "export-local":
            return _handle_datasets_export_local(args)

    parser.error("Unsupported command")
    return 2