[RFC] stac-cli

[gadomski]

• Feature Name: stac-cli
• Start Date: 2023-01-19

Summary

Adds a new repository to stac-utils, stac-cli. This repository will be a click-based Comand Line Interface (CLI), named stac, for working with STAC. The command-line interface in pystac-client will be deprecated, with the plan to remove it once stac-cli reaches an acceptable level of maturity. The command-line interface in stactools will be reworked to use a plugin interface built into stac-cli.

Motivation

Currently there are two CLIs in the Python+STAC ecosystem:

• pystac-client provides stac-client, which performs searches and other queries against STAC APIs
• stactools provides stac, which includes some built-in functionality for moving, copying, and otherwise modifing STAC items, as well as a plugin interface used by stactools-packages to add their own subcommands

Having two different command-line interfaces in the ecosystem is confusing for users; for example, it's reasonable to assume that you can do stac search https://my-great-stac-api.com/, but you can't; you need to use stac-client search. Additionally, in an effort to keep the dependency profile of pystac-client light, its CLI is not built with click, meaning that its implementation is more complex and less featured than a click-based implementation would be. By moving the CLI to a standalone stac-cli repository, we will make pystac-client smaller and more focused on its core task. Any by porting some stactools subcommands to stac-cli, we will provide more command-line functionality to users without requiring them to install the entire stactools dependency stack.

Guide-level explanation

stac-utils/stac-cli will be a standard Python library, with a similar layout to the existing stac-utils Python packages. It will depend on pystac, pystac-client, and click. The CLI will be accessible via stac, e.g.:

stac --help

Subcommands

The following subcommands currently exist for pystac-client and will be ported to stac-cli:

name	description
collections	Get all collections in this Catalog
search	Perform new search of items

The following subcommands currently exist for stactools:

name	description
add	Add an item to a catalog/collection.
add-asset	Add an asset to an item.
add-raster	Add raster extension to an Item.
copy	Copy a STAC Catalog
create-item	Creates an item from an asset
describe	Prints out a list of all catalogs, collections and items in this STAC.
info	Display info about a static STAC catalog.
layout	Reformat the layout of a STAC based on templating.
lint	Lint a stac object with stac-check.
merge	Merge items from one STAC into another.
move-assets	Move or copy assets in a STAC to the Item locations.
summary	Summarize a STAC collection's contents.
update-geometry	Update an item geometry from an asset footprint
validate	Validate a stac object.
version	Display version info.

Some of these stactools commands depend on heavy or complicated third-party libraries (e.g. rasterio); these will stay in stactools. Many of the simpler commands can be implemented purely via pystac and pystac-client, and these will be ported to stac-cli and removed from stactools.

Plugin interface

stactools currently has a plugin interface that allows outside packages to add subcommands to the stac CLI entrypoint. This plugin interface will be ported from stactools to stac-cli, and stactools will be reworked to provide any of its remaining subcommands via this plugin interface. This interface will be designed to be backwards compatible, so existing stactools-packages continue to work without any changes.

Drawbacks

• We're increasing complexity and management effort by adding another repository to the stac-utils Python ecosystem
• Users who are currently relying on the stac-client entrypoint will have to update their workflows to use stac
• By decoupling pystac-client from its CLI, we increase the probability that the CLI and the pystac-client Python API will become out-of-sync, causing breakages

Rationale and alternatives

• By removing command-line responsibilities from pystac-client, we make that library simpler and easier to maintain.
• click is widely used within the STAC+Python ecosytem, so by reimplementing pystac-client subcommands in click, we provide a less surprising experience for users.
• If we don't make this change, users will continue to be confused about whether to use stac or stac-client for command-line operations, and the maintenance burden of pystac-client will remain higher than it otherwise would be. Additionally, some functionality that could be exposed on the command line without stactools (e.g. stac describe) will be inaccessible.

Prior art

• aws-cli is a command line interface to botocore, which is similar to how stac-cli would be a CLI to pystac
• I personally have positive experiences when I decouple my command-line interfaces from my software APIs, e.g. for my stac-rs and (wip) stac-cli-rs projects

Unresolved questions

• Which stactools subcommands will get ported over to stac-cli?
• Will we need to rename any of the pystac-client subcommands?
• In stac-cli, how strictly will we bound the dependencies on pystac and pystac-client? We want to provide some flexibility to allow external packages to use the plugin mechanism, but we also want to ensure users that run pip install stac-cli will get a working installation.
• What will be the deprecation/removal timeline for the pystac-client CLI?

Future possibilities

We could enable/add async support for stac-cli, which would be extremely helpful for stac search, stac download, etc, without necessarily having to push async down into pystac and pystac-client

[gadomski]

Closing this discussion as I've shifted my efforts to the (pip-installable) stacrs-cli.