CLI Reference
This page provides documentation for our command line tools.
planet¶
Planet SDK for Python CLI
Usage:
planet [OPTIONS] COMMAND [ARGS]...
Options:
--quiet Disable ANSI control output.
--version Show the version and exit.
--verbosity TEXT Optional: set verbosity level to warning, info, or debug.
Defaults to warning.
--help Show this message and exit.
auth¶
Commands for working with Planet authentication
Usage:
planet auth [OPTIONS] COMMAND [ARGS]...
Options:
-u, --base-url TEXT Assign custom base Auth API URL.
--help Show this message and exit.
init¶
Obtain and store authentication information
Usage:
planet auth init [OPTIONS]
Options:
--email TEXT The email address associated with your Planet credentials.
--password TEXT Account password. Will not be saved.
--help Show this message and exit.
store¶
Store authentication information
Usage:
planet auth store [OPTIONS] KEY
Options:
--help Show this message and exit.
value¶
Print the stored authentication information
Usage:
planet auth value [OPTIONS]
Options:
--help Show this message and exit.
collect¶
Collect a sequence of JSON descriptions into a single JSON blob.
If the descriptions represent GeoJSON features, a GeoJSON FeatureCollection is returned.
Output can be pretty-printed with --pretty option.
Usage:
planet collect [OPTIONS] INPUT
Options:
--pretty Format JSON output.
--help Show this message and exit.
data¶
Commands for interacting with the Data API
Usage:
planet data [OPTIONS] COMMAND [ARGS]...
Options:
-u, --base-url TEXT Assign custom base Orders API URL.
--help Show this message and exit.
asset-activate¶
Activate an asset.
Usage:
planet data asset-activate [OPTIONS] ITEM_TYPE ITEM_ID ASSET_TYPE
Options:
--help Show this message and exit.
asset-download¶
Download an activated asset.
This function will fail if the asset state is not activated. Consider
calling asset-wait before this command to ensure the asset is activated.
If --checksum is provided, the associated checksums given in the manifest are compared against the downloaded files to verify that they match.
If --checksum is provided, files are already downloaded, and --overwrite is not specified, this will simply validate the checksums of the files against the manifest.
Output: The full path of the downloaded file. If the quiet flag is not set, this also provides ANSI download status reporting.
Usage:
planet data asset-download [OPTIONS] ITEM_TYPE ITEM_ID ASSET_TYPE
Options:
--directory DIRECTORY Base directory for file download.
--filename TEXT Custom name to assign to downloaded file.
--overwrite Overwrite files if they already exist.
--checksum Verify that checksums match.
--help Show this message and exit.
asset-wait¶
Wait for an asset to be activated.
Returns when the asset status has reached "activated" and the asset is available.
Usage:
planet data asset-wait [OPTIONS] ITEM_TYPE ITEM_ID ASSET_TYPE
Options:
--delay INTEGER Time (in seconds) between polls.
--max-attempts INTEGER Maximum number of polls. Set to zero for no limit.
[default: 200]
--help Show this message and exit.
filter¶
Create a structured item search filter.
This command provides basic functionality for specifying a filter by creating an AndFilter with the filters identified with the options as inputs. This is only a subset of the complex filtering supported by the API. For advanced filter creation, either create the filter by hand or use the Python API.
If no options are specified, an empty filter is returned which, when used in a search, bypasses all search filtering.
Usage:
planet data filter [OPTIONS]
Options:
--asset TEXT Filter to items with one or more of
specified assets. TEXT is a comma-separated
list of entries. When multiple entries are
specified, an implicit 'or' logic is
applied.
--date-range <FIELD COMP DATETIME>...
Filter by date range in field. FIELD is the
name of the field to filter on. COMP can be
lt, lte, gt, or gte. DATETIME can be an
RFC3339 or ISO 8601 string.
--geom JSON Filter to items that overlap a given
geometry. Can be a json string, filename, or
'-' for stdin.
--number-in <FIELD VALUE>... Filter field by numeric in. FIELD is the
name of the field to filter on. VALUE is a
comma-separated list of entries. When
multiple entries are specified, an implicit
'or' logic is applied.
--permission Filter to assets with download permissions.
--range <FIELD COMP FLOAT>... Filter by number range in field. FIELD is
the name of the field to filter on. COMP can
be lt, lte, gt, or gte.
--std-quality Filter to standard quality.
--string-in <FIELD TEXT>... Filter field by numeric in. FIELD is the
name of the field to filter on. VALUE is a
comma-separated list of entries. When
multiple entries are specified, an implicit
'or' logic is applied.
--update <FIELD COMP DATETIME>...
Filter to items with changes to a specified
field value made after a specified date.
FIELD is the name of the field to filter on.
COMP can be gt or gte. DATETIME can be an
RFC3339 or ISO 8601 string.
--pretty Format JSON output.
--help Show this message and exit.
search¶
Execute a structured item search.
This function outputs a series of GeoJSON descriptions, one for each of the returned items, optionally pretty-printed.
ITEM_TYPES is a comma-separated list of item-types to search.
If --filter is specified, the filter must be JSON and can be a json string, filename, or '-' for stdin. If not specified, search results are not filtered.
Quick searches are stored for approximately 30 days and the --name parameter will be applied to the stored quick search.
Usage:
planet data search [OPTIONS] ITEM_TYPES
Options:
--geom GEOM
--filter JSON Apply specified filter to search. Can be a
json string, filename, or '-' for stdin.
--limit INTEGER Maximum number of results to return. When
set to 0, no maximum is applied. [default:
100]
--name TEXT Name of the saved search.
--sort [published desc|published asc|acquired desc|acquired asc]
Field and direction to order results by.
[default: published desc]
--pretty Format JSON output.
--help Show this message and exit.
search-create¶
Create a new saved structured item search.
This function outputs a full JSON description of the created search, optionally pretty-printed.
ITEM_TYPES is a comma-separated list of item-types to search.
Usage:
planet data search-create [OPTIONS] ITEM_TYPES
Options:
--geom GEOM
--filter JSON Filter to apply to search. Can be a json string, filename, or
'-' for stdin. [required]
--name TEXT Name of the saved search. [required]
--daily-email Send a daily email when new results are added.
--pretty Format JSON output.
--help Show this message and exit.
search-delete¶
Delete an existing saved search.
Usage:
planet data search-delete [OPTIONS] SEARCH_ID
Options:
--help Show this message and exit.
search-get¶
Get a saved search.
This function outputs a full JSON description of the identified saved search, optionally pretty-printed.
Usage:
planet data search-get [OPTIONS] SEARCH_ID
Options:
--pretty Format JSON output.
--help Show this message and exit.
search-list¶
List saved searches.
This function outputs a full JSON description of the saved searches, optionally pretty-printed.
Usage:
planet data search-list [OPTIONS]
Options:
--sort [created desc|created asc]
Field and direction to order results by.
[default: created desc]
--search-type [any|saved|quick]
Search type filter. [default: any]
--limit INTEGER Maximum number of results to return. When
set to 0, no maximum is applied. [default:
100]
--pretty Format JSON output.
--help Show this message and exit.
search-run¶
Execute a saved structured item search.
This function outputs a series of GeoJSON descriptions, one for each of the returned items, optionally pretty-printed.
Usage:
planet data search-run [OPTIONS] SEARCH_ID
Options:
--sort [published desc|published asc|acquired desc|acquired asc]
Field and direction to order results by.
[default: published desc]
--limit INTEGER Maximum number of results to return. When
set to 0, no maximum is applied. [default:
100]
--pretty Format JSON output.
--help Show this message and exit.
search-update¶
Update a saved search with the given search request.
This function outputs a full JSON description of the updated search, optionally pretty-printed.
Usage:
planet data search-update [OPTIONS] SEARCH_ID ITEM_TYPES
Options:
--filter JSON Filter to apply to search. Can be a json string, filename, or
'-' for stdin. [required]
--name TEXT Name of the saved search. [required]
--geom GEOM
--daily-email Send a daily email when new results are added.
--pretty Format JSON output.
--help Show this message and exit.
stats¶
Get a bucketed histogram of items matching the filter.
This function returns a bucketed histogram of results based on the item_types, interval, and filter specified.
Usage:
planet data stats [OPTIONS] ITEM_TYPES
Options:
--filter JSON Filter to apply to search. Can be a json
string, filename, or '-' for stdin.
[required]
--interval [hour|day|week|month|year]
The size of the histogram date buckets.
[required]
--help Show this message and exit.
orders¶
Commands for interacting with the Orders API
Usage:
planet orders [OPTIONS] COMMAND [ARGS]...
Options:
-u, --base-url TEXT Assign custom base Orders API URL.
--help Show this message and exit.
cancel¶
Cancel order by order ID.
This command cancels a queued order and outputs the cancelled order details.
Usage:
planet orders cancel [OPTIONS] ORDER_ID
Options:
--help Show this message and exit.
create¶
Create an order.
This command outputs the created order description, optionally pretty-printed.
REQUEST is the full description of the order to be created. It must be JSON and can be specified a json string, filename, or '-' for stdin.
Other flag options are hosting and collection_id. The hosting flag specifies the hosting type, and the collection_id flag specifies the collection ID for Sentinel Hub. If the collection_id is omitted, a new collection will be created.
Usage:
planet orders create [OPTIONS] REQUEST
Options:
--hosting [sentinel_hub] Hosting type. Currently, only "sentinel_hub" is
supported.
--collection-id TEXT Collection ID for Sentinel Hub hosting. If
omitted, a new collection will be created.
--pretty Format JSON output.
--help Show this message and exit.
download¶
Download order by order ID.
If --checksum is provided, the associated checksums given in the manifest are compared against the downloaded files to verify that they match.
If --checksum is provided, files are already downloaded, and --overwrite is not specified, this will simply validate the checksums of the files against the manifest.
Usage:
planet orders download [OPTIONS] ORDER_ID
Options:
--checksum [MD5|SHA256] Verify that checksums match.
--directory DIRECTORY Base directory for file download.
--overwrite Overwrite files if they already exist.
--help Show this message and exit.
get¶
Get order
This command outputs the order description, optionally pretty-printed.
Usage:
planet orders get [OPTIONS] ORDER_ID
Options:
--pretty Format JSON output.
--help Show this message and exit.
list¶
List orders
This command prints a sequence of the returned order descriptions, optionally pretty-printed.
Order descriptions are sorted by creation date with the last created order returned first.
Usage:
planet orders list [OPTIONS]
Options:
--state [queued|running|failed|success|partial|cancelled]
Filter orders to given state.
--limit INTEGER Maximum number of results to return. When
set to 0, no maximum is applied. [default:
100]
--pretty Format JSON output.
--help Show this message and exit.
request¶
Generate an order request.
This command provides support for building an order description used in creating an order. It outputs the order request, optionally pretty-printed.
IDs is one or more comma-separated item IDs.
Usage:
planet orders request [OPTIONS] IDS
Options:
--item-type [MYD09GA|SkySatCollect|MOD09GQ|Sentinel1|MOD09GA|MYD09GQ|Sentinel2L1C|Landsat8L1G|PSOrthoTile|SkySatScene|REScene|PSScene|REOrthoTile]
Item type for requested item ids.
[required]
--bundle [analytic|analytic_udm2|analytic_3b_udm2|analytic_5b|analytic_5b_udm2|analytic_8b_udm2|visual|uncalibrated_dn|uncalibrated_dn_udm2|basic_analytic|basic_analytic_udm2|basic_analytic_8b_udm2|basic_uncalibrated_dn|basic_uncalibrated_dn_udm2|analytic_sr|analytic_sr_udm2|analytic_8b_sr_udm2|basic_analytic_nitf|basic_panchromatic|basic_panchromatic_dn|panchromatic|panchromatic_dn|panchromatic_dn_udm2|pansharpened|pansharpened_udm2|basic_l1a_dn]
Asset type for the item. [required]
--name TEXT Order name. Does not need to be unique.
[required]
--clip JSON Clip feature Polygon or Multipolygon
GeoJSON. Can be a json string, filename, or
'-' for stdin.
--tools JSON Toolchain JSON. Can be a json string,
filename, or '-' for stdin.
--email Send email notification when order is
complete.
--archive-type [zip] Optionally zip archive each item bundle.
--archive-filename TEXT Templated filename for archived bundles or
orders. [default:
{{name}}-{{order_id}}.zip]
--single-archive Optionally zip archive all item bundles
together.
--delivery, --cloudconfig JSON Delivery configuration, which may include
credentials for a cloud storage provider, to
enable cloud delivery of data, and/or
parameters for bundling deliveries as zip
archives. Can be a JSON string, a filename,
or '-' for stdin. The --cloudconfig option
is an alias for this use case.
--stac / --no-stac Include or exclude metadata in
SpatioTemporal Asset Catalog (STAC) format.
Not specifying either defaults to including
it (--stac), except for orders with
google_earth_engine delivery
--hosting [sentinel_hub] Hosting for data delivery. Currently, only
"sentinel_hub" is supported.
--collection_id TEXT Collection ID for Sentinel Hub hosting. If
omitted, a new collection will be created.
--pretty Format JSON output.
--help Show this message and exit.
wait¶
Wait until order reaches desired state.
Reports the state of the order on the last poll.
This function polls the Orders API to determine the order state, with the specified delay between each polling attempt, until the order reaches a final state or earlier state, if specified. If the maximum number of attempts is reached before polling is complete, an exception is raised. Setting --max-attempts to zero will result in no limit on the number of attempts.
Setting --delay to zero results in no delay between polling attempts. This will likely result in throttling by the Orders API, which has a rate limit of 10 requests per second. If many orders are being polled asynchronously, consider increasing the delay to avoid throttling.
By default, polling completes when the order reaches a final state. If --state is specified, polling will complete when the specified earlier state is reached or passed.
Usage:
planet orders wait [OPTIONS] ORDER_ID
Options:
--delay INTEGER Time (in seconds) between polls.
--max-attempts INTEGER Maximum number of polls. Set to zero for no
limit. [default: 200]
--state [queued|running|failed|success|partial|cancelled]
State prior to a final state that will end
polling.
--help Show this message and exit.
subscriptions¶
Commands for interacting with the Subscriptions API
Usage:
planet subscriptions [OPTIONS] COMMAND [ARGS]...
Options:
-u, --base-url TEXT Assign custom base Subscriptions API URL.
--help Show this message and exit.
cancel¶
Cancels a subscription and prints the API response.
Usage:
planet subscriptions cancel [OPTIONS] SUBSCRIPTION_ID
Options:
--pretty Format JSON output.
--help Show this message and exit.
create¶
Create a subscription.
Submits a subscription request for creation and prints the created subscription description, optionally pretty-printed.
REQUEST is the full description of the subscription to be created. It must be JSON and can be specified a json string, filename, or '-' for stdin.
Other flag options are hosting and collection_id. The hosting flag specifies the hosting type, and the collection_id flag specifies the collection ID for Sentinel Hub. If the collection_id is omitted, a new collection will be created.
Usage:
planet subscriptions create [OPTIONS] REQUEST
Options:
--hosting [sentinel_hub] Hosting type. Currently, only "sentinel_hub" is
supported.
--collection-id TEXT Collection ID for Sentinel Hub hosting. If
omitted, a new collection will be created.
--pretty Format JSON output.
--help Show this message and exit.
get¶
Get the description of a subscription.
Usage:
planet subscriptions get [OPTIONS] SUBSCRIPTION_ID
Options:
--pretty Format JSON output.
--help Show this message and exit.
list¶
Prints a sequence of JSON-encoded Subscription descriptions.
Usage:
planet subscriptions list [OPTIONS]
Options:
--pretty Format JSON output.
--status [running|cancelled|preparing|pending|completed|suspended|failed]
Select subscriptions in one or more states.
Default is all.
--limit INTEGER Maximum number of results to return. When
set to 0, no maximum is applied. [default:
100]
--help Show this message and exit.
patch¶
Update a subscription via PATCH.
Updates a subscription and prints the updated subscription description, optionally pretty-printed.
REQUEST only requires the attributes to be changed. It must be JSON and can be specified a json string, filename, or '-' for stdin.
Usage:
planet subscriptions patch [OPTIONS] SUBSCRIPTION_ID REQUEST
Options:
--pretty Format JSON output.
--help Show this message and exit.
request¶
Generate a subscriptions request.
Note: the next version of the Subscription API will remove the clip tool option and always clip to the source geometry. Thus the --clip-to-source option is a preview of the next API version's default behavior.
Usage:
planet subscriptions request [OPTIONS]
Options:
--name TEXT Subscription name. Does not need to be unique.
[required]
--source JSON Source JSON. Can be a string, filename, or - for
stdin. [required]
--delivery JSON Delivery configuration, including credentials for
a cloud storage provider, to enable cloud delivery
of data. Can be a JSON string, a filename, or '-'
for stdin.
--notifications JSON Notifications JSON. Can be a string, filename, or
- for stdin.
--tools JSON Toolchain JSON. Can be a string, filename, or -
for stdin.
--hosting [sentinel_hub] Hosting configuration. Can be JSON,
"sentinel_hub", or omitted.
--clip-to-source Clip to the source geometry without specifying a
clip tool.
--collection-id TEXT Collection ID for Sentinel Hub hosting. If
omitted, a new collection will be created.
--pretty Format JSON output.
--help Show this message and exit.
request-catalog¶
Generate a subscriptions request catalog source description.
Usage:
planet subscriptions request-catalog [OPTIONS]
Options:
--item-types TEXT Item type for requested item ids.
[required]
--asset-types TEXT One or more comma-separated asset types.
[required]
--geometry GEOM Geometry of the area of interest of the
subscription that will be used to determine
matches. Can be a string, filename, or - for
stdin. [required]
--start-time DATETIME Date and time to begin subscription.
[required]
--end-time DATETIME Date and time to end subscription.
--rrule TEXT iCalendar recurrance rule to specify
recurrances.
--filter JSON Search filter. Can be a string, filename,
or - for stdin.
--publishing-stage [preview|standard|finalized]
Subscribe to results at a particular
publishing stage. Multiple instances of this
option are allowed.
--time-range-type [acquired|published]
Subscribe by acquisition time or time of
publication.
--pretty Format JSON output.
--help Show this message and exit.
request-pv¶
Generate a Planetary Variable subscription source.
Planetary Variables come in 4 types and are further subdivided within these types. See Subscribing to Planetary Variables or the OpenAPI spec for more details.
Usage:
planet subscriptions request-pv [OPTIONS]
Options:
--var-type TEXT A Planetary Variable type. See documentation for all
available types. [required]
--var-id TEXT A Planetary Variable ID. See documenation for all
available IDs. [required]
--geometry GEOM Geometry of the area of interest of the subscription
that will be used to determine matches. Can be a
string, filename, or - for stdin. [required]
--start-time DATETIME Date and time to begin subscription. [required]
--end-time DATETIME Date and time to end subscription.
--pretty Format JSON output.
--help Show this message and exit.
results¶
Print the results of a subscription to stdout.
The output of this command is a sequence of JSON objects (the default) or a sequence of comma-separated fields (when the --csv option is used), one result per line.
Examples:
planet subscriptions results SUBSCRIPTION_ID --status=success --limit 10
Where SUBSCRIPTION_ID is the unique identifier for a subscription, this prints the last 10 successfully delivered results for that subscription as JSON objects.
planet subscriptions results SUBSCRIPTION_ID --limit 0 --csv > results.csv
Prints all results for a subscription and saves them to a CSV file.
Usage:
planet subscriptions results [OPTIONS] SUBSCRIPTION_ID
Options:
--pretty Format JSON output.
--status [created|queued|processing|failed|success]
Select subscription results in one or more
states. Default: all.
--csv Get subscription results as comma-separated
fields.
--limit INTEGER Maximum number of results to return. When
set to 0, no maximum is applied. [default:
100]
--help Show this message and exit.
update¶
Update a subscription via PUT.
Updates a subscription and prints the updated subscription description, optionally pretty-printed.
REQUEST is the full description of the updated subscription. It must be JSON and can be specified a json string, filename, or '-' for stdin.
Usage:
planet subscriptions update [OPTIONS] SUBSCRIPTION_ID REQUEST
Options:
--pretty Format JSON output.
--help Show this message and exit.