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 Data 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-get¶
Get an item asset.
Usage:
planet data asset-get [OPTIONS] ITEM_TYPE ITEM_ID ASSET_TYPE_ID
Options:
--help Show this message and exit.
asset-list¶
List item assets.
Usage:
planet data asset-list [OPTIONS] ITEM_TYPE ITEM_ID
Options:
--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.
item-coverage¶
Get item clear coverage.
Usage:
planet data item-coverage [OPTIONS] ITEM_TYPE ITEM_ID
Options:
--geom GEOM Either a GeoJSON or a Features API reference [required]
--mode TEXT Method used for coverage calculation. 'UDM2': activates UDM2
asset for accurate coverage, may take time. 'estimate':
provides a quick rough estimate without activation
--band TEXT Specific band to extract from UDM2 (e.g., 'clear', 'cloud',
'snow_ice'). For full details, refer to the UDM2 product
specifications.
--help Show this message and exit.
item-get¶
Get an item.
Usage:
planet data item-get [OPTIONS] ITEM_TYPE ITEM_ID
Options:
--help Show this message and exit.
item-types¶
Show valid item types.
Usage:
planet data item-types [OPTIONS]
Options:
--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.
destinations¶
Commands for interacting with the Destinations API
Usage:
planet destinations [OPTIONS] COMMAND [ARGS]...
Options:
-u, --base-url TEXT Assign custom base Destinations API URL.
--help Show this message and exit.
archive¶
Archive a destination.
This command removes the specified destination from the list endpoint without disabling it. Archiving a destination makes it no longer visible in the active destination list, but its data and configuration remain intact for potential future use.
Example:
planet destinations archive my-destination-id
Usage:
planet destinations archive [OPTIONS] DESTINATION_ID
Options:
--pretty Format JSON output.
--help Show this message and exit.
create¶
Create a new destination.
Usage:
planet destinations create [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
azure¶
Create a new Azure Blob Storage destination.
This command sets up a destination in Azure Blob Storage using the specified container name, storage account name, and SAS token. You can optionally specify a custom endpoint suffix and assign a name to the destination.
Example:
planet destinations create azure --container my-container --account mystorage --sas-token ?sv=... --name my-azure-destination
Usage:
planet destinations create azure [OPTIONS]
Options:
--pretty Format JSON output.
--container TEXT Blob storage container name. [required]
--account TEXT Azure account. [required]
--sas-token TEXT Shared-Access Signature token. [required]
--storage-endpoint-suffix TEXT Custom Azure Storage endpoint suffix.
--name TEXT Optional name to assign to the destination.
Otherwise, the bucket name is used.
--help Show this message and exit.
gcs¶
Create a new Google Cloud Storage (GCS) destination.
This command sets up a GCS destination using the specified bucket name
and base64-encoded service account credentials (in JSON format). You can
optionally assign a name to the destination for easier reference.
Note:
The `credentials` argument must be the base64-encoded JSON of your
Google Cloud service account key. To encode a JSON file to base64,
you can use the following command:
cat my_creds.json | base64 | tr -d '
'
Example:
planet destinations create gcs --bucket my-bucket --credentials eyJ0eXAiOiJKV1Qi... --name my-gcs-destination
Usage:
planet destinations create gcs [OPTIONS]
Options:
--pretty Format JSON output.
--bucket TEXT GCS bucket name. [required]
--credentials TEXT Base64-encoded service account credentials (JSON).
[required]
--name TEXT Optional name to assign to the destination. Otherwise,
the bucket name is used.
--help Show this message and exit.
ocs¶
Create a new Oracle Cloud Storage (OCS) destination.
This command sets up an OCS destination using the specified bucket name, access key ID, secret access key, namespace, and region. You can optionally assign a name to the destination for easier reference.
Example:
planet destinations create ocs --bucket my-bucket --access-key-id OCID... --secret-access-key SECRET... --namespace my-namespace --region us-ashburn-1 --name my-ocs-destination
Usage:
planet destinations create ocs [OPTIONS]
Options:
--pretty Format JSON output.
--bucket TEXT Oracle bucket name. [required]
--access-key-id TEXT Oracle account access key. [required]
--secret-access-key TEXT Oracle account secret key. [required]
--namespace TEXT Oracle Object Storage namespace. [required]
--region TEXT Oracle region bucket resides in. [required]
--name TEXT Optional name to assign to the destination.
Otherwise, the bucket name is used.
--help Show this message and exit.
s3¶
Create a new Amazon S3 destination.
This command configures an S3 destination using the specified bucket name, AWS region, access key ID, and secret access key. You can optionally assign a name to the destination and enable explicit SSE-S3 server-side encryption.
Example:
planet destinations create s3 --bucket my-bucket --region us-west-2 --access-key-id AKIA... --secret-access-key SECRET... --name my-s3-destination
Usage:
planet destinations create s3 [OPTIONS]
Options:
--pretty Format JSON output.
--bucket TEXT S3 bucket name. [required]
--region TEXT AWS region. [required]
--access-key-id TEXT AWS access key ID. [required]
--secret-access-key TEXT AWS secret access key. [required]
--explicit-sse Explicitly set headers for server-side encryption
(SSE).
--name TEXT Optional name to assign to the destination.
Otherwise, the bucket name is used.
--help Show this message and exit.
s3-compatible¶
Create a new S3-compatible destination.
This command configures a destination for an S3-compatible object storage service, using the specified bucket name, custom endpoint URL, region, and access credentials. You can optionally assign a name to the destination and choose whether to use path-style addressing.
Example:
planet destinations create s3-compatible --bucket my-bucket --endpoint https://objects.example.com --region us-east-1 --access-key-id AKIA... --secret-access-key SECRET... --name my-s3-comp-destination
Usage:
planet destinations create s3-compatible [OPTIONS]
Options:
--pretty Format JSON output.
--bucket TEXT Bucket name. [required]
--endpoint TEXT Endpoint URL. [required]
--region TEXT Region. [required]
--access-key-id TEXT Access key ID. [required]
--secret-access-key TEXT Secret access key. [required]
--use-path-style Use path-style addressing with bucket name in the
URL.
--name TEXT Optional name to assign to the destination.
Otherwise, the bucket name is used.
--help Show this message and exit.
get¶
Retrieve a destination by ID
This command returns detailed information about a specific destination identified
by its destination_id.
Example:
planet destinations get my-destination-id
Usage:
planet destinations get [OPTIONS] DESTINATION_ID
Options:
--pretty Format JSON output.
--help Show this message and exit.
list¶
List destinations with optional filters
This command retrieves a list of destinations, with the ability to filter based on various attributes like archive status, ownership, and write access.
Example:
planet destinations list --archived false --is-owner true --can-write true
Usage:
planet destinations list [OPTIONS]
Options:
--pretty Format JSON output.
--archived BOOLEAN Set to true to include only archived destinations,
false to exclude them.
--is-owner BOOLEAN Set to true to include only destinations owned by the
requesting user, false to exclude them.
--can-write BOOLEAN Set to true to include only destinations the user can
modify, false to exclude them.
--help Show this message and exit.
rename¶
Rename a destination.
This command changes the name of the specified destination and also updates the
pl:ref property, which includes the new name. The destination's data, configuration,
and status remain intact. Only the name and its associated reference are updated.
Example:
planet destinations rename my-destination-id new-destination-name
Usage:
planet destinations rename [OPTIONS] DESTINATION_ID NAME
Options:
--pretty Format JSON output.
--help Show this message and exit.
unarchive¶
Unarchive a destination.
This command restores a previously archived destination, making it visible again in the list endpoint. Unarchiving does not affect the destination's data or configuration.
Example:
planet destinations unarchive my-destination-id
Usage:
planet destinations unarchive [OPTIONS] DESTINATION_ID
Options:
--pretty Format JSON output.
--help Show this message and exit.
update¶
Update a destination.
Usage:
planet destinations update [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
azure¶
Update Azure destination parameters.
This command updates the parameters of an existing Azure destination, specifically
the sas-token. The updated SAS token will be applied to the destination configuration
without affecting other destination properties.
Example:
planet destinations update azure my-destination-id --sas-token NEW_SAS_TOKEN
Usage:
planet destinations update azure [OPTIONS] DESTINATION_ID
Options:
--pretty Format JSON output.
--sas-token TEXT New SAS token. [required]
--help Show this message and exit.
gcs¶
Update Google Cloud Storage (GCS) destination parameters.
This command updates the credentials for an existing GCS destination. The provided
`credentials` should be the base64-encoded JSON of the service account key. The updated
credentials will be applied to the destination configuration without altering other properties.
Note:
The `credentials` argument must be the base64-encoded JSON of your Google Cloud
service account key. To encode a JSON file to base64, you can use the following
command:
cat my_creds.json | base64 | tr -d '
'
Example:
planet destinations update gcs my-destination-id --credentials eyJ0eXAiOiJKV1Qi...
Usage:
planet destinations update gcs [OPTIONS] DESTINATION_ID
Options:
--pretty Format JSON output.
--credentials TEXT Base64-encoded service account credentials (JSON).
[required]
--help Show this message and exit.
ocs¶
Update Oracle Cloud Storage (OCS) destination parameters.
This command updates the parameters of an existing Oracle Cloud Storage destination,
including the access-key-id and secret-access-key. The updated credentials will
be applied to the destination configuration without affecting other properties.
Example:
planet destinations update ocs my-destination-id --access-key-id NEW_ACCESS_KEY --secret-access-key NEW_SECRET_KEY
Usage:
planet destinations update ocs [OPTIONS] DESTINATION_ID
Options:
--pretty Format JSON output.
--access-key-id TEXT Oracle account access key. [required]
--secret-access-key TEXT Oracle account secret key. [required]
--help Show this message and exit.
s3¶
Update S3 destination parameters.
This command updates the parameters of an existing S3 destination, including the
access-key-id, secret-access-key, and optionally sets headers for server-side
encryption (SSE) using the explicit-sse flag. The updated parameters will be applied
to the destination configuration without altering the destination’s other properties.
Example:
planet destinations update s3 my-destination-id --access-key-id NEW_ACCESS_KEY --secret-access-key NEW_SECRET_KEY
Usage:
planet destinations update s3 [OPTIONS] DESTINATION_ID
Options:
--pretty Format JSON output.
--access-key-id TEXT AWS access key ID. [required]
--secret-access-key TEXT AWS secret access key. [required]
--explicit-sse Explicitly set headers for server-side encryption
(SSE).
--help Show this message and exit.
s3-compatible¶
Update S3-compatible destination parameters.
This command updates the parameters of an existing S3-compatible destination,
including the access-key-id and secret-access-key. You can also optionally
enable path-style addressing using the --use-path-style flag. The updated parameters
will be applied to the destination configuration without affecting other properties.
Example:
planet destinations update s3-compatible my-destination-id --access-key-id NEW_ACCESS_KEY --secret-access-key NEW_SECRET_KEY
Usage:
planet destinations update s3-compatible [OPTIONS] DESTINATION_ID
Options:
--pretty Format JSON output.
--access-key-id TEXT Access key ID. [required]
--secret-access-key TEXT Secret access key. [required]
--use-path-style Use path-style addressing with bucket name in the
URL.
--help Show this message and exit.
features¶
Commands for interacting with the Features API
Usage:
planet features [OPTIONS] COMMAND [ARGS]...
Options:
-u, --base-url TEXT Assign custom base Features API URL.
--help Show this message and exit.
collections¶
Commands for interacting with Features API collections
Usage:
planet features collections [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
create¶
Create a new Features API collection.
Example:
planet features collections create \ --title "new collection" \ --desc "my new collection"
Usage:
planet features collections create [OPTIONS]
Options:
--pretty Format JSON output.
-t, --title TEXT a title for the collection [required]
-d, --description, --desc TEXT a description for the collection
--help Show this message and exit.
delete¶
Delete a collection by ID
Example:
planet features collections delete my-collection-123
Usage:
planet features collections delete [OPTIONS] COLLECTION_ID
Options:
--pretty Format JSON output.
--help Show this message and exit.
get¶
Get a collection by ID
Example:
planet features collections get
Usage:
planet features collections get [OPTIONS] COLLECTION_ID
Options:
--pretty Format JSON output.
--help Show this message and exit.
list¶
List Features API collections
Example:
planet features collections list
Usage:
planet features collections list [OPTIONS]
Options:
--compact Use compact output.
--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.
items¶
commands for interacting with Features API items (features within a collection)
Usage:
planet features items [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
add¶
Add features from a geojson file to a collection
Example:
planet features items add my-collection-123 ./my_geom.geojson
Usage:
planet features items add [OPTIONS] COLLECTION_ID FILENAME
Options:
--pretty Format JSON output.
--help Show this message and exit.
delete¶
Delete a feature in a collection.
You may supply either a collection ID and a feature ID, or a feature reference.
Example:
planet features items delete my-collection-123 item123 planet features items delete "pl:features/my/my-collection-123/item123"
Usage:
planet features items delete [OPTIONS] COLLECTION_ID [FEATURE_ID]
Options:
--pretty Format JSON output.
--help Show this message and exit.
get¶
Get a feature in a collection.
You may supply either a collection ID and a feature ID, or a feature reference.
Example:
planet features items get my-collection-123 item123 planet features items get "pl:features/my/my-collection-123/item123"
Usage:
planet features items get [OPTIONS] COLLECTION_ID [FEATURE_ID]
Options:
--pretty Format JSON output.
--help Show this message and exit.
list¶
List features in a Features API collection
Example:
planet features items list my-collection-123
Usage:
planet features items list [OPTIONS] COLLECTION_ID
Options:
--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.
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.
bundles¶
Show valid bundle names for ordering.
Usage:
planet orders bundles [OPTIONS]
Options:
--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, collection_id, and create_configuration. The hosting flag specifies the hosting type, the collection_id flag specifies the collection ID for Sentinel Hub, and the create_configuration flag specifies whether or not to create a layer configuration for your collection. If the collection_id is omitted, a new collection will be created. If the create_configuration flag is omitted, no configuration will be created. The collection_id flag and create_configuration flag cannot be used together.
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.
--create-configuration Automatically create a layer configuration for
your collection. If omitted, no configuration 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.
item-types¶
Show valid item types for ordering.
Usage:
planet orders item-types [OPTIONS]
Options:
--help Show this message and exit.
list¶
List orders
This command prints a sequence of the returned order descriptions, optionally pretty-printed.
By default, 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 by state.
--source-type TEXT Filter by source type. See documentation for
all available types. Default is all.
--name TEXT filter by name
--name-contains TEXT only return orders with a name that contains
the provided string.
--created-on TEXT Filter by creation time or interval. See
documentation for examples.
--last-modified TEXT Filter by creation time or interval. See
documentation for examples.
--hosting BOOLEAN Filter by presence of hosting block (e.g.
SentinelHub hosting).
--sort-by TEXT fields to sort orders by. Multiple fields
can be specified, separated by commas. The
sort direction can be specified by appending
' ASC' or ' DESC' to the field name. The
default sort direction is ascending. When
multiple fields are specified, the sort
order is applied in the order the fields are
listed.
Supported fields: [name, created_on, state,
last_modified].
Example: 'name ASC,created_on DESC'
--destination-ref TEXT Filter by orders created with the provided
destination reference.
--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 TEXT Item type for requested item ids.
[required]
--bundle TEXT Bundle type for the item. [required]
--fallback-bundle TEXT Fallback bundle type(s) for the item if
bundle is not available. Multiple fallback
bundles can be specified as a comma-
separated string.
--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.
--create-configuration Automatically create a layer configuration
for your collection. If omitted, no
configuration 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.
bulk-create¶
Bulk create subscriptions.
Submits a bulk subscription request for creation and prints a link to list the resulting subscriptions.
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, collection_id, and create_configuration. The hosting flag specifies the hosting type, the collection_id flag specifies the collection ID for Sentinel Hub, and the create_configuration flag specifies whether or not to create a layer configuration for your collection. If the collection_id is omitted, a new collection will be created. If the create_configuration flag is omitted, no configuration will be created. The collection_id flag and create_configuration flag cannot be used together.
Usage:
planet subscriptions bulk-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.
--create-configuration Automatically create a layer configuration for
your collection. If omitted, no configuration will
be created.
--pretty Format JSON output.
--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, collection_id, and create_configuration. The hosting flag specifies the hosting type, the collection_id flag specifies the collection ID for Sentinel Hub, and the create_configuration flag specifies whether or not to create a layer configuration for your collection. If the collection_id is omitted, a new collection will be created. If the create_configuration flag is omitted, no configuration will be created. The collection_id flag and create_configuration flag cannot be used together.
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.
--create-configuration Automatically create a layer configuration for
your collection. If omitted, no configuration 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.
item-types¶
Show valid item types for catalog subscriptions.
Usage:
planet subscriptions item-types [OPTIONS]
Options:
--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.
--created TEXT Filter subscriptions by creation time or
interval. See documentation for examples.
--end-time TEXT Filter subscriptions by end time or
interval. See documentation for examples.
--hosting BOOLEAN Filter subscriptions by presence of hosting
block (e.g. SentinelHub hosting).
--name-contains TEXT only return subscriptions with a name that
contains the provided string.
--name TEXT filter by name
--source-type TEXT Filter subscriptions by source type. See
documentation for all available types.
Default is all.
--start-time TEXT Filter subscriptions by start time or
interval. See documentation for examples.
--status [running|cancelled|preparing|pending|completed|suspended|failed]
Select subscriptions in one or more states.
Default is all.
--sort-by TEXT fields to sort subscriptions by. Multiple
fields can be specified, separated by
commas. The sort direction can be specified
by appending ' ASC' or ' DESC' to the field
name. The default sort direction is
ascending. When multiple fields are
specified, the sort order is applied in the
order the fields are listed.
Supported fields: [name, created, updated,
start_time, end_time].
Example: 'name ASC,created DESC'
--updated TEXT Filter subscriptions by update time or
interval. See documentation for examples.
--destination-ref TEXT Filter subscriptions created with the
provided destination reference.
--limit INTEGER Maximum number of results to return. When
set to 0, no maximum is applied. [default:
100]
--page-size INTEGER Number of subscriptions to return per page.
--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.
--create-configuration Automatically create a layer configuration for
your collection. If omitted, no configuration 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.
--var-id TEXT A Planetary Variable ID. See documentation 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. When this flag is included, --limit
is ignored
--limit INTEGER Maximum number of results to return. When
set to 0, no maximum is applied. [default:
100]
--help Show this message and exit.
summarize¶
Summarize the status of all subscriptions or the status of results for a single subscription
Usage:
planet subscriptions summarize [OPTIONS]
Options:
--subscription-id TEXT Optionally supply a subscription ID to summarize
result counts by status. If omitted, the summary
will be generated for all subscriptions the
requester has created by status.
--pretty Format JSON output.
--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.