Command Line Tool

The earthengine tool is a utility program that allows you to manage Earth Engine assets and tasks from the command line. It is installed automatically when you install the Python API. To check whether the tool is installed and functioning correctly, type the following on a command line:

earthengine

If the tool is properly installed then it will print out a short summary of available commands. To get help on a specific command, use:

earthengine command -h

When you first install the Python API you will need to log in using the authenticate command described below. The following sections describe the available commands in more detail.

Service account credentials

To use the CLI with a service account's credentials, use the service_account_file flag to point to a JSON file containing the service account's key.

earthengine --service_account_file=service_account_creds.json

Command Reference

authenticate

Authenticates the command line tool and Python client library to Earth Engine. Example:

earthengine authenticate

Earth Engine uses the OAuth 2.0 protocol for authenticating clients. You will need to install gcloud before using the authentication protocol. Running the earthengine authenticate command will prompt you through the authentication process using your web browser.

Other authentication modes are also available through the auth_mode parameter:

gcloud is the default mode for the command line tool, as described above.
appdefault reads "application default credentials" from the file referenced by $GOOGLE_APPLICATION_CREDENTIALS. See cloud authentication for details.
notebook uses the same in-notebook mode as ee.Authenticate. This doesn't require gcloud to be installed, but the credentials produced will expire in 7 days.
paste is a legacy copy/paste mode, which will be removed to improve security.

acl

Prints or updates the access control list (ACL) of an Earth Engine asset. The ACL controls who can read or write to an asset. Examples:

earthengine acl get users/username/asset_id
earthengine acl set public users/username/asset_id
earthengine acl ch -u username@gmail.com:R users/username/asset_id

The get subcommand prints a JSON description of the ACL. The set subcommand sets an ACL provided in a file with the same JSON format. You can easily copy an ACL from one asset to others by saving the output from get and providing it to set.

The set subcommand also accepts two special ACL names:

private: Removes permissions from everyone except the owner.
public: Grants read permission to all users.

The ch subcommand allows you to make individual changes to an ACL. To grant read permission specify -u username@gmail.com:R, to grant write permission specify -u username@gmail.com:W, and to remove a user's permissions specify -d username@gmail.com. The special user identifier AllUsers may be used to grant or revoke read permission to or from all users. (Note that revoking AllUsers permissions does not revoke any additional permissions you may have also granted to individual users.)

asset

Prints or updates metadata associated with the an Earth Engine asset. Examples:

earthengine asset info users/username/asset_id
earthengine asset set -p name=value users/username/asset_id

The info subcommand prints detailed information about the asset, including its metadata, in JSON form. The set subcommand sets individual metadata properties on an asset.

The values of metadata properties that you set may be either numbers or strings. When setting property names using the --property or -p flag, separate the property name and value with an equals sign. The data type will be detected automatically, or you may specify it explicitly by prefixing the property name with (string), (number), or (date). For example, this will set a string-valued property with the value "42":

earthengine asset set -p '(string)name=42' users/username/asset_id

(The quotes in this example prevent the shell from interpreting the parentheses. They may or may not be necessary, depending on your shell and platform.)

Date properties are just numbers that represent a number of milliseconds since the Unix epoch (i.e. midnight on January 1st, 1970) and may be specified directly as a number or in one of the following formats:

YYYY-MM-DD
YYYY-MM-DDThh:mm:ss
YYYY-MM-DDThh:mm:ss.f

The time zone is assumed to be UTC. You may set the special start and end time properties using the --time_start and --time_end flags:

earthengine asset set --time_start 1978-10-15T12:34:56 users/username/asset_id

cp

Copies an asset. Example:

earthengine cp users/username/asset_id users/username/new_asset_id

create

Creates new folders and image collections. Example:

earthengine create folder users/username/folder_id
earthengine create collection users/username/collection_id

Use the folder subcommand to create folders and the collection to create image collections. You can specify the -p option to recursively create parent folders as required. Newly-created folders and images have private ACLs by default.

ls

Lists the contents of one or more folders or collections. Example:

earthengine ls users/username

The -l option requests a long format with more information about each asset (currently just its type). You may specify --max_items number (or -m for short) to limit the number of items from each folder or collection you list:

earthengine ls -m 10 users/username/my_large_collection

Running the ls command with no arguments will list the top-level folders that you own.

model

Tool with which to manipulate TensorFlow saved models.

`model prepare`

Prepare a saved model for serving in Earth Engine. Specifically, this transforms your SavedModel into a form suitable for processing requests from Earth Engine. (Learn more about SavedModel.)

earthengine model prepare my_source_dir my_dest_dir '{"Conv2D:0":"my_input_band"}' '{"Sigmoid:0":"my_output_band"}'

Learn more about AI Platform models here. See a complete example here.

mv

Moves or renames an asset. Example:

earthengine mv users/username/asset_id users/username/new_asset_id

rm

Deletes one or more assets. Example:

earthengine rm users/username/asset_id
earthengine rm -r users/username/folder_id

You can use the -r flag to delete the contents of a folder or collection recursively. For safety when deleting multiple assets, you can use the --dry_run flag to verify exactly what will be deleted without actually deleting anything.

set_project

Sets the Google Cloud project through which computation requests are routed.

earthengine set_project foo-project

This command is needed prior to running commands that require Cloud functionality, for example model.

task

Prints information about or manages long-running tasks. Examples:

earthengine task list
earthengine task list -l
earthengine task info TASK_ID
earthengine task cancel TASK_ID

The list subcommand lists basic information about the tasks that you submitted recently. The -l option requests a long format with more information about each task. The info subcommand prints detailed information about individual tasks. The cancel subcommand cancels one or more running tasks.

upload

Uploads images or tables from Google Cloud Storage to Earth Engine. For example, to upload an image asset using default settings:

earthengine upload image --asset_id=users/username/asset_id gs://bucket/image.tif

If you specify multiple input image files they will be interpreted as tiles of a single image asset. You can learn more about the options for uploading images to Earth Engine in Uploading image assets: Advanced options.

You can specify the pyramid reduction policy using the --pyramiding_policy flag, which can be set to one of mean (the default), sample, mode, min, or max. This will control how Earth Engine generates the pyramid of lower-resolution versions of your image:

earthengine upload image --asset_id=users/username/asset_id --pyramiding_policy=sample gs://bucket/image.tif

You can use the --last_band_alpha to indicate that the mask for the image should be taken from an alpha channel in the last band:

earthengine upload image --asset_id=users/username/asset_id --last_band_alpha gs://bucket/image.tif

You can specify a no-data value using the --nodata_value flag. This will mask any pixels in the image with that value:

earthengine upload image --asset_id=users/myuser/asset --nodata_value=255 gs://bucket/image.tif

You may also specify metadata properties to set on the asset using the same flags that are accepted by the asset set command described above.

To upload a Shapefile, CSV, or TFRecord from Google Cloud Storage to an Earth Engine table asset, you can use:

earthengine upload table --asset_id=users/username/myUploadedShapefile gs://bucket/foo.shp

earthengine upload table --asset_id=users/username/myUploadedCSV gs://bucket/foo.csv

earthengine upload table --asset_id=users/username/myUploadedTFRecord gs://bucket/foo.tfrecord

Note that when uploading Shapefiles, you only need to specify the path to the .shp file. The related .dbf, .shx, and .prj files must be present in the same location. Alternatively, you can specify a .zip file that contains the necessary files.

There are many options pertaining to the way in which CSV and TFRecord files are interpreted. You can see a complete list of table upload options with:

earthengine upload table -h