EmbedEarth is an open, programmable geographic layer for applications and AI: search physical-world data, analyze it, route across networks, render it on maps, and work locally without proprietary map-data lock-in.

The earth CLI uses the same six core areas as the SDK and MCP server: Search, Compute, Routing, Maps, Catalog, and Stratum.

Product: embed.earth · Docs: CLI docs · Docs home

Install

npm install -g @embed-earth/cli-test
earth --help

Node 20 or newer is required. Add --json to any command for machine-readable output.

Enable Cloud

Cloud workflows require an API key from embed.earth. Set its value in E2_API_KEY; the CLI sends it for Cloud requests. A Cloud API key is also required to access Street View image URLs.

$env:E2_API_KEY = "your_api_key" # PowerShell
earth search restaurant --area "New York" --limit 25

ROUTE_URL is optional. Routes use https://route.embed.earth by default.

Search

earth search returns matching records as a GeoJSON FeatureCollection. Use --area for a human-readable place name or --area-id for an exact raw catalog ID.

earth search restaurant --area "New York" --limit 25 --json
earth search restaurant hospital --area-id 4915 --bbox "-74.1,40.65,-73.9,40.85" --limit 100 --json

Input	Purpose
`<features...>` / `--feature`	Feature keys or numeric IDs.
`--area` / `--area-id`	Named area or exact raw area ID.
`--bbox`	`minLng,minLat,maxLng,maxLat` result boundary.
`--where` / `--property`	Repeated source-column or property filters.
`--columns` / `--limit`	Select output columns or bound results.
`--mode`	`cloud`, `offline`, or `auto`.

Compute

earth compute evaluates a spatial relation or aggregate. It is neither raw record retrieval nor turn-by-turn routing.

Primitive	Purpose
`nearest`	Find the closest selected features to a relation feature.
`distance`	Measure distances between selected and relation features.
`within`	Return selected features inside a specified relation distance.
`count`	Count selected features that meet the relation.
`density`	Measure feature concentration in an area.
`coverage`	Measure area reached by a selected relation.
`gaps`	Identify places not reached by selected coverage.
`cluster`	Group selected features by spatial proximity.

earth compute count restaurant --area "New York" --near park --distance 500 --json
earth compute nearest restaurant --area-id 4915 --near park --distance 500 --limit 3 --json
earth compute compare --features restaurant,hospital --area "New York" --primitive COUNT --json

Every primitive supports --area or --area-id, optional --near or --within, --distance in meters, --limit, and --mode. Add --db to run against a local SQLite database.

Routing

Routing uses https://route.embed.earth by default.

Command	Purpose
`earth route run`	Route between ordered locations.
`earth route matrix`	Return travel metrics for source/target pairs.
`earth route isochrone`	Return reachable contours.
`earth route map-match`	Align a coordinate trace to the network.
`earth route to-feature`	Find the nearest indexed destination, then route to it.
`earth route request`	Call a compatible route operation not covered above.

earth route run --locations "40.74,-73.99;40.71,-74.01" --mode walking --json
earth route matrix --sources "40.74,-73.99" --targets "40.71,-74.01" --json
earth route to-feature hospital --from "40.74,-73.99" --area-id 4915 --mode walking --json

Maps

earth map sources returns MapLibre-ready Planet basemap and published feature PMTiles source descriptors. It does not render a map in the terminal.

earth map sources restaurant hospital --json

Catalog

Catalog lookup discovers valid feature, area, and published-data inputs. It is list/search/info only—there is no separate resolve command or endpoint.

earth catalog features search restaurant --json
earth catalog areas search "New York" --json
earth catalog areas info 4915 --json
earth catalog data list --json

Area IDs are raw values such as 4915; do not add a provider-specific prefix.

Stratum

Stratum manages verified local cached data, server pulls, local querying, and uploads of your own GeoJSON, CSV, or Parquet.

earth stratum cache set 5GB --json
earth stratum download restaurant --area-id 4915 --out ./restaurants.parquet
earth stratum query restaurant --area "New York" --mode auto --limit 100 --json
earth stratum upload ./places.geojson --db ./places.db --connect-to restaurant --out ./places.parquet --json

stratum cache provides set, list, delete, and clear. Downloaded data is verified before it enters the cache. stratum upload indexes user-owned data locally and writes GeoParquet when --out is supplied.

Choose Search for records, Compute for spatial analysis, Routing for network travel, Maps for source descriptors, Catalog for valid inputs, and Stratum for server pulls and local data.