mapx CLI

MapX exposes its agent-callable surface through the mapx command-line client. Third-party platforms (WorkBuddy, local LLM tool loops, automation scripts) can run the single binary to control projects, upload data, change map styles, and save reports without embedding the product UI. The API calls each project a session internally; the CLI command names (such as mapx session create) keep that technical name.

Install and configure

Download the binary for your platform from OSS (the latest alias points to the newest release). Unix (Linux/macOS):

OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
case "$ARCH" in
  x86_64|amd64) ARCH=x86_64 ;;
  aarch64|arm64) ARCH=aarch64 ;;
  *) echo "unsupported architecture: $ARCH" >&2; exit 1 ;;
esac
curl -fsSL -o mapx "https://mapx.oss-cn-hongkong.aliyuncs.com/skill/mapx-cli/mapx-cli-${OS}-${ARCH}-latest"
chmod +x mapx
./mapx --help

Windows (PowerShell):

$arch = if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { "aarch64" } else { "x86_64" }
Invoke-WebRequest -Uri "https://mapx.oss-cn-hongkong.aliyuncs.com/skill/mapx-cli/mapx-cli-windows-$arch-latest.exe" -OutFile "mapx.exe"
.\mapx.exe --help

Then configure the API key:

export MAPX_API_URL="https://api.mapxagent.com"   # optional
export MAPX_API_KEY="mkx_..."                     # personal key, shown once
mapx auth status                                  # verify (Windows: .\mapx.exe auth status)

Every command accepts --api-key and --url overrides. The key is scoped to your account, and project ownership is enforced by the backend.

Typical workflow

mapx session create --title "analysis" (or mapx session list) to get a session_id (the project id).
mapx view live --session <id> — open the live map as soon as the project exists. The command returns a live_view_url (an SSE-synced live view). If the agent platform can render web pages, load that URL in the agent UI so the user can watch the map update in real time (for example, WorkBuddy). If the agent cannot render web pages, use mapx view live --session <id> --open to open the live map in the user’s default browser instead.
mapx upload ./data.geojson --session <id> — upload local data directly. The command accepts only GeoJSON (vector) and GeoTIFF (raster) files. For CSV/Excel sources, identify the latitude/longitude columns, convert the data to GeoJSON, then upload the resulting .geojson file.
mapx layers list --session <id> then mapx layers get <layer_id> --session <id> to inspect geometry, fields, and the current style.
mapx layers style <layer_id> --session <id> --file style.json — apply incremental style changes.
mapx report save ./report.html --session <id> — save an HTML report.

Command reference

mapx auth status                                   # verify the API key
mapx auth login <mkx_...>                          # save the API key locally (~/.mapx/config.json)
mapx auth logout                                   # remove the locally saved API key

mapx session create --title "analysis"             # create a project; returns session_id
mapx session list                                  # list projects
mapx session get <id>                              # show a project
mapx session delete <id>                           # delete a project

mapx upload ./data.geojson --session <id>          # upload: GeoJSON (vector)→layer, GeoTIFF (raster)→COG; CSV/Excel must be converted to GeoJSON first
mapx files list --session <id>                     # list files
mapx files delete <file_id> --session <id>         # delete a file and its linked layers
mapx assets list --session <id>                    # list all data assets (layers + files)

mapx layers list --session <id>                    # list layers
mapx layers get <layer_id> --session <id>          # layer info (geometry/fields/style)
mapx layers style <layer_id> --session <id> --file style.json
mapx layers visible <layer_id> true --session <id>
mapx layers rename <layer_id> "new name" --session <id>
mapx layers delete <layer_id> --session <id>
mapx layers move-up <layer_id> --session <id>      # move one layer up (persisted by backend)
mapx layers move-down <layer_id> --session <id>    # move one layer down (persisted by backend)
mapx layers reorder --session <id> --ids <id1>,<id2>,<id3>   # set the full layer order at once

mapx map fly-to --session <id> --center 116.4,39.9 --zoom 11
mapx map fit-bounds --session <id> --bounds -74.1,40.6,-73.9,40.9
mapx map go-home --session <id>
mapx map zoom-to-layer --session <id> --layer <layer_id>
mapx map basemap-style --session <id> --style dark              # positron | positronWithLabels | dark | darkWithLabels
mapx map basemap-category --session <id> --key water --color #1e3a5f
mapx map country-mask --session <id> --code CHN                 # --code "" clears the mask
mapx map custom-mask --session <id> --file mask.geojson         # or --geojson <json>; --clear removes it
mapx map zoom-in --session <id> --times 2
mapx map zoom-out --session <id>
mapx map pan --session <id> --direction north --amount large
mapx map state --session <id>                                   # center/zoom/basemap/masks
mapx map add-tile-layer --session <id> --tile-url "https://tiles.example.com/{z}/{x}/{y}.png"

mapx view static --session <id>                    # static embed URL (iframe/reports)
mapx view live --session <id>                      # print the live view URL; load it in the agent UI when the platform can render web pages (e.g. WorkBuddy)
mapx view live --session <id> --open               # open the live map in the default browser when the agent cannot render web pages

mapx report save ./report.html --session <id> --title "Analysis report"

mapx skill                                        # this manual
mapx skill list                                   # list available topics

Every command accepts --json for machine-readable output.

Output contract

With --json, stdout contains a single JSON object ({"ok":true,...} or {"ok":false,"error":"..."}); progress goes to stderr. Exit codes: 0 success, 1 business failure, 2 usage error.

Skills

Before complex tasks, print the command manual with mapx skill. The full skill index is stored in source/skills.json. See Skills.

Get Started

API Reference

Client

Install and configure

Typical workflow

Command reference

Output contract

Skills

​Install and configure

​Typical workflow

​Command reference

​Output contract

​Skills

Install and configure

Typical workflow

Command reference

Output contract

Skills