CLI User Guide

CLI User Guide#

Make sure you correctly followed instructions on Configure EODAG.

Then you can start playing with it:

Run eodag --help to display all the available options and commands:

$ eodag --help
Usage: eodag [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

  Earth Observation Data Access Gateway: work on EO products from any provider

Options:
  -v, --verbose  Control the verbosity of the logs. For maximum verbosity,
                 type -vvv
  --help         Show this message and exit.

Commands:
  discover  Fetch providers to discover collections
  download  Download a list of products from a serialized search result...
  list      List supported collections
  search    Search satellite images by their collections, instruments,...
  version   Print eodag version and exit

Each command has its own help, see for instance the help of the list command with eodag list --help.
By default the command line interface of eodag is set to the minimum verbosity level. You can print more log messages by adding -v to eodag master command. The more v given (up to 3), the more verbose the tool is. This feature comes in handy when you want to inspect an error or an unexpected behaviour. 4 different verbosity levels are offered to you:

eodag list
eodag -v list
eodag -vv list
eodag -vvv list

Search#

$ eodag search --help
Usage: eodag search [OPTIONS]

  Search satellite images by their collections, instruments, constellation,
  platform, processing level or sensor type. It is mandatory to provide at
  least one of the previous criteria for eodag to perform a search. Optionally
  crunch the search results before storing them in a geojson file

Options:
  -f, --conf PATH                 File path to the user configuration file
                                  with its credentials, default is
                                  ~/.config/eodag/eodag.yml
  -l, --locs PATH                 File path to the user locations
                                  configuration file, default is
                                  ~/.config/eodag/locations.yml
  -p, --provider TEXT             Search on this provider
  -b, --box <FLOAT FLOAT FLOAT FLOAT>...
                                  Search for a product on a bounding box,
                                  providing its minlon, minlat, maxlon and
                                  maxlat (in this order). NOTE: This argument
                                  is mutually exclusive with  arguments:
                                  [geom].
  -g, --geom TEXT                 Search for a product on a geometry,
                                  providing its WKT representation. NOTE: This
                                  argument is mutually exclusive with
                                  arguments: [box].
  -s, --start [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]
                                  Start sensing time in ISO8601 format (e.g.
                                  '1990-11-26', '1990-11-26T14:30:10'). UTC is
                                  assumed
  -e, --end [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]
                                  End sensing time in ISO8601 format (e.g.
                                  '1990-11-26', '1990-11-26T14:30:10'). UTC is
                                  assumed
  -c, --collection TEXT           The collection to search
  --instruments TEXT              Search for products matching these
                                  instruments
  --platform TEXT                 Search for products matching this platform
  --constellation TEXT            Search for products matching this
                                  constellation
  --processing-level TEXT         Search for products matching this processing
                                  level
  --sensor-type TEXT              Search for products matching this type of
                                  sensor
  --cloud-cover INTEGER RANGE     Maximum cloud cover percentage needed for
                                  the product  [0<=x<=100]
  --id TEXT                       Search for the product identified by this id
  --locations TEXT                Custom query-string argument(s) to select
                                  locations. Format
                                  :'key1=value1&key2=value2'. Example:
                                  --locations country=FRA&continent=Africa
  -q, --query TEXT                Custom query-string argument(s). Format
                                  :'key1=value1&key2=value2'
  --cruncher [FilterLatestByName|FilterLatestIntersect|FilterOverlap|FilterProperty|FilterDate]
                                  A cruncher to be applied to search results.
                                  Repeat option many times to apply many
                                  crunchers
  --cruncher-args <TEXT TEXT TEXT>...
                                  Named arguments acting as the parameters of
                                  a cruncher. Enter it like this: --cruncher-
                                  args <CruncherName> <arg-name> <arg-value>.
                                  Repeat option many times to give many args
                                  to a cruncher
  --storage FILE                  Path to the file where to store search
                                  results (.geojson extension will be
                                  automatically appended to the filename).
                                  [default: search_results.geojson]
  --items INTEGER                 (DEPRECATED, use limit instead) The number
                                  of items to return. Eodag is bound to
                                  whatever limitation the providers have on
                                  the number of results they return. This
                                  option allows to control how many items
                                  eodag should request [default: 20]
  --limit INTEGER                 The number of items to return. Eodag is
                                  bound to whatever limitation the providers
                                  have on the number of results they return.
                                  This option allows to control how many items
                                  eodag should request [default: 20]
  --page INTEGER                  Retrieve the given page  [default: 1]
  --all                           Retrieve ALL the products that match the
                                  search criteria. It collects products by
                                  iterating over the results pages until no
                                  more products are available.At each
                                  iteration, the maximum number of items
                                  searched is either 'items' if set, or a
                                  maximum value defined internally for the
                                  requested provider, or a default maximum
                                  value equals to 50.
  --count                         Make a count request together with search
                                  (Enabling count will significantly slow down
                                  search requests for some providers, and
                                  might be unavailable for someothers).
  --help                          Show this message and exit.

To search for products and crunch the results of the search:

eodag search \
--conf my_conf.yml \
--box 1 43 2 44 \
--start 2018-01-01 --end 2018-01-31 \
--collection S2_MSI_L1C \
--all \
--storage my_search.geojson

The request above searches for S2_MSI_L1C collections in a given bounding box, in January 2018. The command fetches internally all the products that match these criteria. Without --all, it would only fetch the products found on the first result page. It finally saves the results in a GeoJSON file.

You can pass arguments to a cruncher on the command line by doing this (example with using FilterOverlap cruncher which takes minimum_overlap as argument):

eodag search -f my_conf.yml -b 1 43 2 44 -s 2018-01-01 -e 2018-01-31 -c S2_MSI_L1C --all \
             --cruncher FilterOverlap \
             --cruncher-args FilterOverlap minimum_overlap 10

The request above means : “Give me all the products from S2_MSI_L1C collection, use FilterOverlap to keep only those products that are contained in the bbox I gave you, or whose spatial extent overlaps at least 10% (minimum_overlap) of the surface of this bbox”.

You can use eaodag search with custom query parameters. Custom query parameters will be used as is in the query string search sent to the provider. For instance, if you want to add foo=1 and bar=2 to the previous query:

eodag search -f my_conf.yml -b 1 43 2 44 -s 2018-01-01 -e 2018-01-31 -c S2_MSI_L1C \
             --cruncher FilterOverlap \
             --cruncher-args FilterOverlap minimum_overlap 10 \
             --query "foo=1&bar=2"

If the collection is not known, it can also be guessed by EODAG during the search based on parameters in the search request. The possible parameters are:
- instruments (e.g. MSI)
- constellation (e.g. SENTINEL2)
- platform (e.g. S2A)
- processing-level (e.g. L1)
- sensor-type (e.g. OPTICAL)
- keywords (e.g. SENTINEL2 L1C SAFE), which is case insensitive and ignores - or _ characters

For example, the following search request will first search for a collection for platform SENTINEL2 and processing:level L1 (there are several collections matching these criteria, e.g., S2_MSI_L1C) and then use this collection to execute the actual search.

eodag search \
--constellation SENTINEL2 \
--processing-level L1 \
--box 1 43 2 44 \
--start 2021-03-01 --end 2021-03-31

Download#

$ eodag download --help
Usage: eodag download [OPTIONS]

  Download a list of products from a serialized search result or STAC items
  URLs/paths

  Examples:

    eodag download --search-results /path/to/search_results.geojson

    eodag download --stac-item https://example.com/stac/item1.json --stac-item
    /path/to/item2.json

Options:
  --search-results FILE   Path to a serialized search result
  --stac-item TEXT        URL/path of a STAC item to download (multiple values
                          accepted)
  -f, --conf PATH         File path to the user configuration file with its
                          credentials [default: ~/.config/eodag/eodag.yml]
  --quicklooks            Download only quicklooks of products instead full
                          set of files
  --output-dir DIRECTORY  Products or quicklooks download directory [default:
                          local temporary directory]
  --max-workers INTEGER   The maximum number of workers to use for downloading
                          products and assets in parallel
  --help                  Show this message and exit.

To download the result of a previous call to search:

eodag download --conf my_conf.yml --search-results my_search.geojson

To download STAC items from their URL or path:

eodag download --stac-item https://foo/collections/bar/items/item-1-id --stac-item /path/to/item2.json

Using commands chaining, download can also directly be executed after a search in a single command:

eodag search --collection S2_MSI_L1C --bbox 1 43 2 44 --start 2025-03-01 download

Collections#

$ eodag list --help
Usage: eodag list [OPTIONS]

  List supported collections

Options:
  -p, --provider TEXT      List collections supported by this provider
  --instruments TEXT       List collections originating from these instruments
  --platform TEXT          List collections originating from this platform
  --constellation TEXT     List collections originating from this
                           constellation
  --processing-level TEXT  List collections of processing level
  --sensor-type TEXT       List collections originating from this type of
                           sensor
  --no-fetch               Do not fetch providers for new collections
  --help                   Show this message and exit.

To list all available collections and supported providers:

eodag list

To list available collections on a specified supported provider:

eodag list -p creodias

By default, list command will also fetch for new collections, which may be slow depending on the network status. To skip fetching, use the following option:

eodag list --no-fetch

EODAG can fetch providers (all or only a given one) to discover available collections, using the following command. It will store result in a JSON file (defaults to ext_collections.json):

$ eodag discover --help
Usage: eodag discover [OPTIONS]

  Fetch providers to discover collections

Options:
  -p, --provider TEXT  Fetch only the given provider
  --storage FILE       Path to the file where to store external collections
                       configuration (.json extension will be automatically
                       appended to the filename). [default:
                       ext_collections.json]
  --help               Show this message and exit.

Examples:

eodag discover
eodag discover -p planetary_computer
eodag discover -p planetary_computer --storage my_collections_conf.json

This file can then be used in EODAG using the environment variable EODAG_EXT_COLLECTIONS_CFG_FILE.

Please note that if you did not customize EODAG with new providers settings, this command should not be useful. For more information on the collections discovery mechanism, please see Python API User Guide / Providers and collections / Collections discovery.

CLI User Guide

Contents

CLI User Guide#

Search#

Download#

Collections#