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.
--auth-profile TEXT Select the client authentication profile to use.
[env var: PL_AUTH_PROFILE]
--auth-client-id TEXT Specify the OAuth client ID. [env var:
PL_AUTH_CLIENT_ID]
--auth-client-secret TEXT Specify the OAuth client Secret. [env var:
PL_AUTH_CLIENT_SECRET]
--auth-api-key TEXT Specify an API key. [env var: PL_API_KEY]
--help Show this message and exit.
auth¶
Commands for working with Planet authentication.
Usage:
planet auth [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
login¶
Perform an initial login.
This command performs an initial login, obtains user authorization, and saves access tokens for the selected authentication profile. The specific process used depends on the selected options and authentication profile.
Usage:
planet auth login [OPTIONS]
Options:
--open-browser / --no-open-browser
Allow/Suppress the automatic opening of a
browser window. [default: open-browser]
--show-qr-code / --no-show-qr-code
Control whether a QR code is displayed for
the user. [default: no-show-qr-code]
--scope TEXT Token scope. Specify multiple options to
specify multiple scopes. When set via
environment variable, scopes should be white
space delimited. Default value is
determined by the selected auth profile.
[env var: PL_AUTH_SCOPE]
--auth-profile TEXT Select the client authentication profile to
use. [env var: PL_AUTH_PROFILE]
--auth-client-id TEXT Specify the OAuth client ID. [env var:
PL_AUTH_CLIENT_ID]
--auth-client-secret TEXT Specify the OAuth client Secret. [env var:
PL_AUTH_CLIENT_SECRET]
--auth-api-key TEXT Specify an API key. [env var: PL_API_KEY]
--sops / --no-sops Use sops when creating new files where
applicable. The environment must be
configured for SOPS to work by default.
[default: no-sops]
-y, --yes / -n, --no Skip user prompts with a "yes" or "no"
selection.
--help Show this message and exit.
print-access-token¶
Show the current OAuth access token. Stale tokens will be automatically refreshed. This command only applies to auth profiles that use OAuth access tokens.
Usage:
planet auth print-access-token [OPTIONS]
Options:
--refresh / --no-refresh Automatically perform a credential refresh if
required. [default: refresh]
--help Show this message and exit.
print-api-key¶
Show the current API Key. This command only applies to auth profiles that use simple API keys.
Usage:
planet auth print-api-key [OPTIONS]
Options:
--help Show this message and exit.
profile¶
Manage auth profiles.
Usage:
planet auth profile [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
copy¶
Copy an existing profile to create a new profile. Only the persistent profile configuration will be copied. User access tokens initialized via a call to login will not be copied.
Usage:
planet auth profile copy [OPTIONS] SRC DST
Options:
--sops / --no-sops Use sops when creating new files where applicable. The
environment must be configured for SOPS to work by
default. [default: no-sops]
--help Show this message and exit.
list¶
List auth profiles.
Usage:
planet auth profile list [OPTIONS]
Options:
-l, --long Longer, more detailed output.
--help Show this message and exit.
set¶
Configure the default authentication profile. Preference will be saved to disk and will be used when one is not otherwise specified. Command line options and environment variables override on-disk preferences.
Usage:
planet auth profile set [OPTIONS] [SELECTED_PROFILE]
Options:
--help Show this message and exit.
show¶
Show the current authentication profiles.
Usage:
planet auth profile show [OPTIONS]
Options:
--help Show this message and exit.
refresh¶
Obtain a new credential using the saved refresh token.
It is possible to request a refresh token with scopes that are different from what is currently possessed, but you will never be granted more scopes than what the user has authorized.
This command only applies to auth profiles that use OAuth access tokens.
Usage:
planet auth refresh [OPTIONS]
Options:
--scope TEXT Token scope. Specify multiple options to specify multiple
scopes. When set via environment variable, scopes should be
white space delimited. Default value is determined by the
selected auth profile. [env var: PL_AUTH_SCOPE]
--help Show this message and exit.
reset¶
Reset saved auth state.
Old auth state is not deleted. It is moved aside and preserved.
Usage:
planet auth reset [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 with a given geometry. Can
be a json string, filename, or '-' for
stdin.
--geom-relation [intersects|contains|within|disjoint]
Geometry search relation. Options are
intersects (default), contains, within, or
disjoint.
--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.
default¶
Commands for interacting with default destinations.
Usage:
planet destinations default [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
get¶
Get the current default destination.
This command gets the current default destination for the organization, if one is set. The default destination is globally available to all members of an organization.
Example:
planet destinations default get
Usage:
planet destinations default get [OPTIONS]
Options:
--pretty Format JSON output.
--help Show this message and exit.
set¶
Set a default destination.
This command sets a specified destination as the default for the organization. Default destinations are globally available to all members of an organization. An organization can have zero or one default destination at any time. Ability to set a default destination is restricted to organization administrators and destination owners.
Example:
planet destinations default set my-destination-id
Usage:
planet destinations default set [OPTIONS] DESTINATION_ID
Options:
--pretty Format JSON output.
--help Show this message and exit.
unset¶
Unset the current default destination.
This command unsets the current default destination. Ability to unset a default destination is restricted to organization administrators and destination owners. Returns None (HTTP 204, No Content) on success.
Example:
planet destinations default unset
Usage:
planet destinations default unset [OPTIONS]
Options:
--pretty Format JSON output.
--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.
--is-default BOOLEAN Set to true to include only the default destination,
false to exclude it.
--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.
mosaics¶
Commands for interacting with the Mosaics API
Usage:
planet mosaics [OPTIONS] COMMAND [ARGS]...
Options:
-u, --base-url TEXT Assign custom base Mosaics API URL.
--help Show this message and exit.
contributions¶
Get contributing scenes for a quad in a mosaic specified by name or ID
Example:
planet mosaics contribution global_monthly_2025_04_mosaic 575-1300
Usage:
planet mosaics contributions [OPTIONS] NAME_OR_ID QUAD
Options:
--pretty Format JSON output.
--help Show this message and exit.
download¶
Download quads from a mosaic by name or ID
Example:
planet mosaics search global_monthly_2025_04_mosaic --bbox -100,40,-100,41
Usage:
planet mosaics download [OPTIONS] NAME_OR_ID
Options:
--pretty Format JSON output.
--output-dir DIRECTORY Directory for file download. Defaults to mosaic name
--bbox BBOX Region to download as comma-delimited strings:
lon_min,lat_min,lon_max,lat_max
--geometry GEOM A geojson geometry to search with. Can be a string,
filename, or - for stdin.
--help Show this message and exit.
info¶
Get information for a mosaic specified by name or ID
Example:
planet mosaics info global_monthly_2025_04_mosaic
Usage:
planet mosaics info [OPTIONS] NAME_OR_ID
Options:
--pretty Format JSON output.
--links If enabled, include API links
--help Show this message and exit.
list¶
List information for all available mosaics
Example:
planet mosaics list --name-contains global_monthly
Usage:
planet mosaics list [OPTIONS]
Options:
--pretty Format JSON output.
--name-contains TEXT Match if the name contains text, case-insensitive
--interval TEXT Match this interval, e.g. 1 mon
--acquired_gt DATETIME Imagery acquisition after than this date
--acquired_lt DATETIME Imagery acquisition before than this date
--links If enabled, include API links
--help Show this message and exit.
search¶
Search quads in a mosaic specified by name or ID
Example:
planet mosaics search global_monthly_2025_04_mosaic --bbox -100,40,-100,41
Usage:
planet mosaics search [OPTIONS] NAME_OR_ID
Options:
--pretty Format JSON output.
--bbox BBOX Region to download as comma-delimited strings:
lon_min,lat_min,lon_max,lat_max
--geometry GEOM A geojson geometry to search with. Can be a string,
filename, or - for stdin.
--summary Get a count of how many quads would be returned
--links If enabled, include API links
--help Show this message and exit.
series¶
Commands for interacting with Mosaic Series through the Mosaics API
Usage:
planet mosaics series [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
info¶
Get information for a series specified by name or ID
Example:
planet series info "Global Quarterly"
Usage:
planet mosaics series info [OPTIONS] NAME_OR_ID
Options:
--pretty Format JSON output.
--links If enabled, include API links
--help Show this message and exit.
list¶
List information for available series
Example:
planet mosaics series list --name-contains=Global
Usage:
planet mosaics series list [OPTIONS]
Options:
--pretty Format JSON output.
--name-contains TEXT Match if the name contains text, case-insensitive
--interval TEXT Match this interval, e.g. 1 mon
--acquired_gt DATETIME Imagery acquisition after than this date
--acquired_lt DATETIME Imagery acquisition before than this date
--links If enabled, include API links
--help Show this message and exit.
list-mosaics¶
List mosaics in a series specified by name or ID
Example:
planet mosaics series list-mosaics global_monthly_2025_04_mosaic
Usage:
planet mosaics series list-mosaics [OPTIONS] NAME_OR_ID
Options:
--pretty Format JSON output.
--latest Get the latest mosaic in the series
--acquired_gt DATETIME Imagery acquisition after than this date
--acquired_lt DATETIME Imagery acquisition before than this date
--links If enabled, include API links
--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.
--user-id TEXT Filter by user ID. Accepts 'all' or a
specific user ID.
--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.
bulk-reactivate¶
Reactivates multiple subscriptions.
By default (no flags), reactivates all of the user's subscriptions. Use --subscription-ids to reactivate specific subscriptions. Use --all to reactivate all organization subscriptions (requires admin).
Usage:
planet subscriptions bulk-reactivate [OPTIONS]
Options:
--subscription-ids TEXT Comma-separated list of subscription IDs to
reactivate
--all Reactivate all organization subscriptions (admin
only)
--pretty Format JSON output.
--help Show this message and exit.
bulk-suspend¶
Suspends multiple subscriptions.
By default (no flags), suspends all of the user's subscriptions. Use --subscription-ids to suspend specific subscriptions. Use --all to suspend all organization subscriptions (requires admin).
Usage:
planet subscriptions bulk-suspend [OPTIONS]
Options:
--subscription-ids TEXT Comma-separated list of subscription IDs to suspend
--all Suspend all organization subscriptions (admin only)
--details TEXT Optional details explaining suspension reason
--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 (RFC 3339). See documentation for
examples.
--end-time TEXT Filter subscriptions by end time or interval
(RFC 3339). 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 (RFC 3339). See documentation for
examples.
--status [running|cancelled|preparing|pending|completed|suspended|failed|invalid]
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 (RFC 3339). See documentation for
examples.
--destination-ref TEXT Filter subscriptions created with the
provided destination reference.
--user-id TEXT Filter by user ID. Accepts 'all' or a
specific user ID.
--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.
reactivate¶
Reactivates a subscription.
Usage:
planet subscriptions reactivate [OPTIONS] SUBSCRIPTION_ID
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.
--geometry-relation [intersects|contains|within]
The relationship between the subscription geometry and the item geometry.
intersects (default): Returns items whose footprint geometry partially or
fully overlaps with the subscription geometry.
contains: Returns items where the footprint geometry fully encloses the
subscription geometry.
within: Returns items whose entire footprint geometry is fully contained
within the subscription geometry.
--pretty Format JSON output.
--help Show this message and exit.
request-source¶
Generate a subscription source.
See Subscribing to Planetary Variables and Analysis Ready sources or the OpenAPI spec to learn more about different product options.
Usage:
planet subscriptions request-source [OPTIONS]
Options:
--source-id TEXT A source 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
--created TEXT Filter results by creation time or interval
(RFC 3339). See documentation for examples.
--updated TEXT Filter results by update time or interval
(RFC 3339). See documentation for examples.
--completed TEXT Filter results by completion time or
interval (RFC 3339). See documentation for
examples.
--item-datetime TEXT Filter results by item datetime or interval
(RFC 3339). See documentation for examples.
--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.
suspend¶
Suspends a subscription and prints the suspended subscription.
Usage:
planet subscriptions suspend [OPTIONS] SUBSCRIPTION_ID
Options:
--details TEXT Optional details explaining suspension reason
--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.