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.

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](https://github.com/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

Lint a STAC object via stac-check.

Prints any warnings to stdout.

stac-check: https://github.com/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

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

Validates a STAC object.

This is a thin wrapper around [stac-validate](https://github.com/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.

--validate-assets, --no-validate-assets

Validate assets.

-v, --verbose

Enables verbose output.

--log-file <log_file>

Save output to file (local filepath).

Arguments

HREF

Required argument

version

Display version info.

stac version [OPTIONS]