Skip to main content
`Ctrl`+`K`

# 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

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

#### 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](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.

--log-file <log_file>

  Save output to file (local filepath).

Arguments

HREF

  Required argument

#### version

Display version info.

    stac version [OPTIONS]