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.
stac add-asset [OPTIONS] ITEM_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’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
- ITEM_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 item assets to be alongside the new item location.
- -l, --publish-location <publish_location>#
Location to use for resolving HREF links instead of the destination folder.
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
Arguments
- HREF#
Required 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#
Lint a STAC object via stac-check.
Prints any warnings to stdout.
stac-check: stac-utils/stac-check
stac lint [OPTIONS] HREF
Options
- --quiet#
Do not print anything to standard output, simply set the process exit code to 1 on error.
- --config-file <config_file>#
Path to a configuration file to use instead of the default configuration
Arguments
- HREF#
Required argument
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
move-assets#
Move or copy assets in a STAC Catalog.
For all assets in the catalog at CATALOG_PATH, move or copy those assets into the directory of the item for which they belong. If –asset-subdirectory is used, moves them instead into a directory called ‘assets’ next to the item for which they belong. If -c is used, assets are copied; otherwise they are moved.
Note: If the catalog is an ABSOLUTE_PUBLISHED catalog, the assets will have an absolute HREF after this operation. Otherwise, it will have a relative HREF.
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-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#
Validates a STAC object.
This is a thin wrapper around [stac-validate](stac-utils/stac-validator). Not all command-line options are exposed. If you want more control over validation, use stac-validator directly.
If you’d like linting, use stac lint.
stac validate [OPTIONS] HREF
Options
- --recursive, --no-recursive#
Recursively validate all STAC objects in this catalog.
- --validate-links, --no-validate-links#
Validate links.
- --validate-assets, --no-validate-assets#
Validate assets.
- -v, --verbose#
Enables verbose output.
- --quiet, --no-quiet#
Do not print output to console.
- --log-file <log_file>#
Save output to file (local filepath).
Arguments
- HREF#
Required argument
version#
Display version info
stac version [OPTIONS]