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.
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. Running this command will prompt you through the authentication process using your web browser. See Setting Up Authentication Credentials in the Python API documentation for additional details.
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
-u username@gmail.com:W
-d username@gmail.com
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
-p
(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
--time_end
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
ls
Lists the contents of one or more folders or collections. Example:
earthengine ls users/username
The -l
--max_items number
-m
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
--dry_run
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`.
tasks
Prints or information about or manages long-running tasks. Examples:
earthengine task list earthengine task info TASK_ID earthengine task cancel TASK_ID
The list
subcommand lists basic information about the tasks that you submitted
recently. 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
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
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
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