> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapxagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# mapx CLI

> Drive MapX projects, data, styles, and reports from third-party platforms with the mapx command-line client.

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):

```bash theme={null}
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):

```powershell theme={null}
$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:

```bash theme={null}
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

1. `mapx session create --title "analysis"` (or `mapx session list`) to get a
   `session_id` (the project id).
2. `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.
3. `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.
4. `mapx layers list --session <id>` then `mapx layers get <layer_id> --session <id>`
   to inspect geometry, fields, and the current style.
5. `mapx layers style <layer_id> --session <id> --file style.json` — apply
   incremental style changes.
6. `mapx report save ./report.html --session <id>` — save an HTML report.

## Command reference

```bash theme={null}
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](/en/developers/skills).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.