The earth CLI is EmbedEarth from the terminal: search physical-world data, run spatial analysis, build routes, prepare maps, and work with local data.

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

Modes

Mode	Purpose
`auto`	Use verified local Stratum data first, then Cloud.
`offline`	Use verified local Stratum data only.
`cloud`	Use EmbedEarth Cloud; requires an API key.

Pass a mode with --mode. It applies to Search, Compute, and Stratum query.

API key

Get a key at embed.earth, then set E2_API_KEY. Cloud mode and Street View image URLs require it.

$env:E2_API_KEY = "your_api_key"

Search

Search returns a GeoJSON FeatureCollection.

earth search restaurant --area "New York" --mode auto --limit 25 --json
earth search restaurant hospital --area-id 4915 --mode cloud --limit 100 --json

Compute

Primitive	Purpose
`nearest`	Find closest selected features.
`distance`	Measure distances between features.
`within`	Find features inside a relation distance.
`count`	Count features that meet a relation.
`density`	Measure feature concentration.
`coverage`	Measure reached area.
`gaps`	Find uncovered places.
`cluster`	Group nearby features.

earth compute count restaurant --area-id 4915 --near park --distance 500 --mode cloud --json

Routing

Set ROUTE_URL only when you want a custom compatible routing service.

$env:ROUTE_URL = "https://your-router.example"
earth route to-feature restaurant --from "40.74,-73.99" --mode walking --json

to-feature resolves the coordinate to its area, narrows feature candidates through H3, and routes to the directly closest result. route run, matrix, isochrone, map-match, and request cover the other routing operations.

Maps

earth map sources restaurant hospital --json

This returns MapLibre-ready source descriptors; it does not render a terminal map.

Stratum

Stratum includes geographic lookup as well as local and server-backed data.

Command	Purpose
`earth stratum cache set/list/delete/clear`	Manage verified local data.
`earth stratum features list/search/info`	Look up built-in geographical features.
`earth stratum areas list/search/info`	Look up built-in geographical areas.
`earth stratum data list/info`	Inspect available published data.
`earth stratum download`	Pull a stratum to cache or a file.
`earth stratum query`	Query Cloud or verified local data.
`earth stratum upload`	Add GeoJSON, CSV, or Parquet locally.

earth stratum areas search "New York" --json
earth stratum download restaurant --area-id 4915 --out ./restaurants.parquet
earth stratum upload ./stores.geojson --db ./stores.db --feature stores --namespace my-app --json

The local upload above creates local:my-app:stores, which cannot collide with the built-in feature namespace.