Command line interface (CLI)#

stactools installs stac as a command-line entrypoint. To display all the available commands:

$ stac --help

stactools-packages can extend the command line interface with their own commands via a plugin mechanism. For example, you can browse a STAC catalog via a local server running stac-browser via:

$ pip install stactools-browse
$ stac browse catalog.json

See specific stactools-package documentation for information about what commands are available.

Note

If you’ve installed stactools with AWS S3 support via pip install 'stactools[s3]', you can enable requester pays via:

$ AWS_REQUEST_PAYER='requester' stac copy # ...etc...

Full documentation#

stac#

stac [OPTIONS] COMMAND [ARGS]...

Options

-v, --verbose#: Use verbose mode

-q, --quiet#: Use quiet mode (no output)

add#

Add an item to a catalog/collection.

stac add [OPTIONS] SOURCE_ITEM TARGET_CATALOG

Options

--collection <collection>#: The collection ID to add to. If not set, will add to the root catalog or collection.

-a, --move-assets#: Move assets to the target catalog Item locations.

Arguments

SOURCE_ITEM#: Required argument

TARGET_CATALOG#: Required argument

add-asset#

Add an asset to an item or collection.

stac add-asset [OPTIONS] OWNER_PATH ASSET_KEY ASSET_PATH

Options

--title <title>#: Optional title of the asset

--description <description>#: Optional description of the asset providing additional details, such as how it was processed or created.

--media-type <media_type>#: Optional media type of the asset

-r, --role <roles>#: Optional, semantic roles of the asset

--move-assets#: Move asset to the target Item or Collection’s location.

--ignore-conflicts#: If there already exists an asset with the given key or at the target path (when –move-assets flag is set), do not raise an error, leave the original asset from the target item in place.

Arguments

OWNER_PATH#: Required argument

ASSET_KEY#: Required argument

ASSET_PATH#: Required argument

add-raster#

Add raster extension to an Item.

stac add-raster [OPTIONS] ITEM_PATH

Arguments

ITEM_PATH#: Required argument

copy#

Copy a STAC Catalog or Collection at SRC to the directory at DST.

Note: Copying a catalog will upgrade it to the latest version of STAC.

stac copy [OPTIONS] SRC DST

Options

-t, --catalog-type <catalog_type>#

Options:: ABSOLUTE_PUBLISHED | RELATIVE_PUBLISHED | SELF_CONTAINED

-a, --copy-assets#: Copy all asset files to be alongside the new location.

-l, --publish-location <publish_location>#: Location to use for resolving HREF links instead of the destination folder.

--resolve-links, --no-resolve-links#: Whether to resolve HREF links. Defaults to –resolve-links. Use –no-resolve-links to avoid writing external child objects locally.

Arguments

SRC#: Required argument

DST#: Required argument

create-item#

Creates an Item from a href.

The href must be a rasterio readable asset. The item’s dictionary will be printed to stdout. This item is intentinonally _extremely_ minimal. If you need additional capabilities, we recommend using [rio stac](developmentseed/rio-stac).

stac create-item [OPTIONS] HREF [ASSET_KEY]

Options

-r, --role <roles>#: Optional, semantic roles of the asset

Arguments

HREF#: Required argument

ASSET_KEY#: Optional argument

describe#

Prints out a list of all catalogs, collections and items in this STAC.

stac describe [OPTIONS] CATALOG_PATH

Options

-h, --include-hrefs#: Include HREFs in description.

Arguments

CATALOG_PATH#: Required argument

info#

Display info about a static STAC catalog.

stac info [OPTIONS] CATALOG_PATH

Options

-s, --skip_items#: Skip counting items

--progress, --no-progress#: Display and update the output info while reading the catalog.

Arguments

CATALOG_PATH#: Required argument

layout#

Reformat the layout of a STAC based on templating.

stac layout [OPTIONS] CATALOG ITEM_PATH_TEMPLATE

Options

-s, --create-subcatalogs#: Create subcatalogs based on the template values instead of just creating directories.

-k, --remove-existing-subcatalogs#: If this flag is set, existing subcatalogs will beremoved. If –create_subcatalogs is used, all itemswill be places in the new subcatalogs from the source_catalog.

-a, --move-assets#: Move assets to the target catalog Item locations.

Arguments

CATALOG#: Required argument

ITEM_PATH_TEMPLATE#: Required argument

lint#

Unsupported (needs `pip install ‘stactools[validate]’)

stac lint [OPTIONS]

merge#

Merge items from one STAC into another.

stac merge [OPTIONS] SOURCE_CATALOG TARGET_CATALOG

Options

--collection <collection>#: The collection ID to merge into. If not set, will merge into the root catalog or collection.

-a, --move-assets#: Move assets to the target catalog Item locations.

--ignore-conflicts#: If there are conflicts with an item in both catalogs having the same asset key, do not error, leave the original asset from the target catalog in place.

-c, --as-child#: Merge as child catalog of destination catalog or collection

-f, --child-folder <child_folder>#: The subfolder name to copy to if the option to merge as a child is used. If not provided, the catalog id will be used

Arguments

SOURCE_CATALOG#: Required argument

TARGET_CATALOG#: Required argument

migrate#

Migrate a STAC object to the latest version

stac migrate [OPTIONS] HREF

Options

-s, --save#: Save migrated STAC object in original location.

-r, --recursive#: Recurse through all child objects and migrate them as well.

--show-diff, --hide-diff#: Whether to dump diff between original and migrated object to stdout. Defaults to –show-diff.

Arguments

HREF#: Required argument

move-assets#

Move or copy assets in a STAC catalog to the locations of the items or collections that own them.

stac move-assets [OPTIONS] CATALOG_PATH

Options

-c, --copy#: Copy assets instead of moving.

-s, --asset-subdirectory <asset_subdirectory>#: Subdirectory to place assets inside of the directory containing their items

Arguments

CATALOG_PATH#: Required argument

summary#

Summarize a STAC collection’s contents.

stac summary [OPTIONS] HREF

Options

-f, --fields <fields>#: the path to the json file with field descriptions. If no file is passed, a default one will be used.

-u, --update#: Instead of printing the summary information, update the collection itself, then print it to stdout.

-i, --inplace#: If updating, update the collection in-place, instead of printing it to stdout.

Arguments

HREF#: Required argument

update-extent#

Update a STAC collection’s extent.

stac update-extent [OPTIONS] HREF

Options

-i, --inplace#: Update the collection in-place, instead of printing it to stdout.

Arguments

HREF#: Required argument

update-geometry#

Update an item geometry from an asset footprint

stac update-geometry [OPTIONS] ITEM_PATH

Options

-a, --asset-name <asset_names>#: The names of the assets to try for footprint extraction. The first successful footprint will be used. If no assets are provided, all assets will be tried until one is successful.

-p, --precision <precision>#: The number of decimal places to include in the coordinates for the reprojected geometry.

-d, --densification-factor <densification_factor>#: The factor by which to increase point density within the polygon.

-i, --densification-distance <densification_distance>#: The distance interval at which to increase point density within the polygon

-s, --simplify-tolerance <simplify_tolerance>#: All points in the simplified object will be within the tolerance distance of the original geometry, in degrees.

-n, --no-data <no_data>#: explicitly set the no data value if not in image metadata

-b, --bands <bands>#

Comma-separated list of bands to use to create the footprint. Use the string ‘all’ to choose all bands.

Default:: 1

-e, --skip-errors <skip_errors>#

Do not raise errors for missing hrefs or footprint calculation failures

Default:: True

Arguments

ITEM_PATH#: Required argument

validate#

Unsupported (needs `pip install ‘stactools[validate]’)

stac validate [OPTIONS]

version#

Display version info.

stac version [OPTIONS]