Page Summary

outlined_flag

• Theearthengine tool is a command-line utility for managing Earth Engine assets and tasks.

• It is automatically installed with the Earth Engine Python API and can be checked by typingearthengine in the command line.

• Authentication is required to use the tool and can be done using theauthenticate command or service account credentials.

• The tool can be used in Google Colab by prepending commands with an exclamation point.

• Various commands are available to manage assets, includingacl,asset,cp,create,ls,model,mv,project_config,rm,set_project,task, andupload.

Theearthengine tool is a utility program that lets you manage Earth Engineassets and tasks from the command line. It is installed automatically when youinstall the Python API. To check whether the tool is installedand functioning correctly, type the following on a command line:

    earthengine

If the tool is properly installed, it prints out a short summary of availablecommands. To get help on a specific command, use:

    earthengine command -h

When you first install the Python API you need to sign in using theauthenticate command described below. The following sections describe theavailable commands in more detail.

Service account credentials

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

    earthengine --service_account_file=service_account_creds.json

Usage in Colab

The Earth Engine Command Line Tool is preinstalled and ready for use inGoogle Colab.

Authentication

Authenticate for each new Colab session or if the virtual machineexpires from inactivity (credentials are not saved across sessions).

Import the Python client library and callee.Authenticate() to trigger theauthentication flow. Follow the prompts to complete authentication. The defaultauth_mode in Colab iscolab, see theAuthentication guidefor other options.

importeeee.Authenticate()

Command execution

To run command line utilities, like the Earth Engine CLI, you need to prependcommand calls with an exclamation point.

!earthengine -h

Set a Cloud project

Use the--project option to set a Cloud project for each individualearthengine command.

!earthengine --project my-project <command>

Alternatively, set a default project to be used by allearthenginecalls using theset_project command. The project will be addedto a credentials file (~/.config/earthengine/credentials) and used forsubsequent commands, unless overridden by the--project option.Set a default project for each new Colab session or if the virtual machineexpires from inactivity (credentials are not saved across sessions).

!earthengine set_project my-project

Command Reference

authenticate

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

    earthengine authenticate

Earth Engine uses theOAuth 2.0 protocol forauthenticating clients. The earthengine authenticate command will prompt youthrough the authentication process using your web browser.

You will need toinstall gcloud ifusing the default gcloud authentication mode. See other authentication modesavailable through theauth_mode parameter in theauthenticationguide.

acl

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

    earthengine acl get projects/my-project/assets/asset_id    earthengine acl set public projects/my-project/assets/asset_id    earthengine acl ch -u username@gmail.com:R projects/my-project/assets/asset_id

Theget sub-command prints a JSON description of the ACL. Thesetsub-command sets an ACL provided in a file with the same JSON format. You cancopy an ACL from one asset to others by saving the output fromget andproviding it toset.

The set sub-command also accepts two special ACL names:

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

Thech sub-command lets you make individual changes to an ACL. To grant readpermission specify-u username@gmail.com:R, to grant write permission specify-u username@gmail.com:W, and to remove a user's permissions specify-dusername@gmail.com. The special user identifierAllUsers may be used to grantor revoke read permission to or from all users. (Note that revokingAllUserspermissions doesnot revoke any additional permissions you may have alsogranted to individual users.)

asset

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

    earthengine asset info projects/my-project/assets/asset_id    earthengine asset set -p name=value projects/my-project/assets/asset_id

Theinfo sub-command prints detailed information about the asset, includingits metadata, in JSON form. Theset sub-command sets individual metadataproperties 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 theproperty name and value with an equals sign. The data type is detectedautomatically, or you may specify it explicitly by prefixing the property namewith(string),(number), or(date). For example, this sets a string-valuedproperty with the value"42":

    earthengine asset set -p '(string)name=42' projects/my-project/assets/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.)

To delete a property, set it tonull without a type:

    earthengine asset set -p name=null projects/my-project/assets/asset_id

Date properties are just numbers that represent a number of milliseconds sincethe Unix epoch (i.e. midnight on January 1st, 1970) and may be specifieddirectly 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 timeproperties using the--time_start and--time_end flags:

    earthengine asset set --time_start 1978-10-15T12:34:56 projects/my-project/assets/asset_id

cp

Copies an asset. Example:

    earthengine cp projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

create

Creates new folders and image collections. Example:

    earthengine create folder projects/my-project/assets/folder_id    earthengine create collection projects/my-project/assets/collection_id

Use thefolder sub-command to create folders and thecollection to createimage collections. You can specify the-p option to recursively create parentfolders as required. Newly-created folders and images have private ACLs bydefault.

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 forshort) to limit the number of items from each folder or collection you list:

    earthengine ls -m 10 projects/my-project/assets/my_large_collection

Running thels command with no arguments will list the top-level folders thatyou own.

model

Tool with which to manipulate TensorFlow saved models.

model prepare

Prepare a saved model for serving in Earth Engine. Specifically, this transformsyourSavedModel into a form suitable for processing requests from EarthEngine. (Learn more aboutSavedModel.)

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

Learn more about AI Platform modelshere. See a completeexamplehere.

mv

Moves or renames an asset. Example:

    earthengine mv projects/my-project/assets/asset_id projects/my-project/assets/new_asset_id

project_config

Sets project configuration values. Before using this command, be sure to set aproject usingset_project.

get

To view a project configuration, use theget sub-command:

    earthengine alpha project_config get

If you havepermission to view the project's batch tasksettings, theoutput contains:

• maxConcurrentExports: a number indicating the maximum number of batchtasks that can run in parallel across all users for the given project. Bydefault, this is set to the maximum allowed by the associated billingaccount'ssubscriptionplan.

Additionally, if you havepermission to view the planconfiguration, theoutput contains:

• planMaxConcurrentExports, a number indicating the maximum number of batchtasks that can run in parallel across all users and projects that use thebilling account.

set

To update the project's configuration, use theset sub-command. The followingsettings can be configured:

• max_concurrent_exports, to control the project's maximumbatch taskparallelism
  • requires the correctpermissions

For example, to configure a project to only ever allow 10 tasks to run inparallel for the given project:

    earthengine alpha project_config set --max_concurrent_exports=10

The output displays the updated project configuration, identical to whatget returns.

For more information about batch task parallelism, see theEarth Enginequotas page.

rm

Deletes one or more assets. Example:

    earthengine rm projects/my-project/assets/asset_id    earthengine rm -r projects/my-project/assets/folder_id

You can use the-r flag to delete the contents of a folder or collectionrecursively. For safety when deleting multiple assets, you can use the--dry_run flag to verify exactly what will be deleted without actuallydeleting 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 Cloudfunctionality, for examplemodel.

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

Thelist sub-command lists basic information about the tasks that yousubmitted recently. The-l option requests a long format with more informationabout each task. Theinfo sub-command prints detailed information aboutindividual tasks. Thecancel sub-command cancels one or more running tasks.

upload

Uploads images or tables from Google Cloud Storage to Earth Engine, or createsassets backed by external images.

image

To upload an image asset using default settings:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id gs://bucket/image.tif

If you specify multiple input image files they will be interpreted as tiles of asingle image asset. You can learn more about the options for uploading images toEarth Engine inUploading image assets: Advancedoptions.

You can specify the pyramid reduction policy using the--pyramiding_policyflag, which can be set to one ofmean (the default),sample,mode,min,ormax. This will control how Earth Engine generates the pyramid oflower-resolution versions of your image:

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --pyramiding_policy=sample gs://bucket/image.tif

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

    earthengine upload image --asset_id=projects/my-project/assets/asset_id --last_band_alpha gs://bucket/image.tif

You can specify a no-data value using the--nodata_value flag. This will maskany 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 sameflags that are accepted by theasset set commanddescribed above.The options are also described in theImage Manifestguide.

table

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

    earthengine upload table --asset_id=projects/my-project/assets/myUploadedShapefile gs://bucket/foo.shp    earthengine upload table --asset_id=projects/my-project/assets/myUploadedCSV gs://bucket/foo.csv    earthengine upload table --asset_id=projects/my-project/assets/myUploadedTFRecord gs://bucket/foo.tfrecord

There are many options pertaining to the way in which CSV and TFRecord files areinterpreted. You can see a complete list of table upload options by visiting theTable Manifestguide or with:

    earthengine upload table -h

external_image

earthengine alpha upload external_image --manifest /tmp/foo.json

{"name":"projects/{project}/assets/cogdemo1","tilesets":[{"id":"0","sources":[{"uris":["gs://ee-docs-demos/COG_demo.tif"]}]}],"properties":{"source":"https://code.earthengine.google.com/d541cf8b268b2f9d8f834c255698201d"},"startTime":"2016-01-01T00:00:00.000000000Z","endTime":"2016-12-31T15:01:23.000000000Z"}

See theCloud GeoTIFFguide and theImage Manifestguide for more details on constructing the manifest.