---
name: mapx-skill
description: Install and drive the mapx command-line client to create MapX projects, upload data, control the map, edit layer styles, and generate reports. Use when the user wants to work with MapX spatial data through the mapx CLI or third-party agents.
---

# mapx-cli Skill Manual

The MapX command-line client enables third-party platforms and local LLM agents
to upload data, manage projects, control the map, edit layer styles, and
generate reports.

## When to use

Use this skill when the user needs to:

- Upload local vector data as GeoJSON or raster imagery as GeoTIFF and convert
  it into map layers; CSV/Excel files must be converted to GeoJSON first
- Create, switch, or delete projects and inspect their layers and fields
- Edit layer styles: color, categorized, graduated, heatmap, interpolated,
  multi-field, charts, labels, and legends
- Control the map viewport: fly-to, zoom, fit-bounds, and home
- Generate HTML analysis reports
- Obtain a live or static embed URL for a project

Do not use it for general questions unrelated to map data operations.

## 1. Installation and configuration

Unix (Linux/macOS) — download the binary for the current platform from OSS
(the `latest` alias points to the newest release):

```bash
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://static.mapxagent.com/skill/mapx-cli/mapx-cli-${OS}-${ARCH}-latest"
chmod +x mapx
./mapx --help
```

Windows (PowerShell):

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

## 2. Authentication

Every command needs a personal API key (`mkx_...`). Authenticate once with
`mapx auth login`; the key is stored locally in `~/.mapx/config.json`
(0600 permissions) and reused by all later commands.

1. Check whether a key is already configured:

   ```bash
   mapx auth status
   ```

2. If it fails with a missing or invalid key, ask the user to create one: open
   `https://app.mapxagent.com?open=api-keys` (or app → Profile/Account → API
   Keys), click **Create API Key**, and copy the `mkx_...` value. The full key
   is shown only once.
3. Save the key the user pastes back:

   ```bash
   mapx auth login <mkx_...>
   ```

   Optional `--url <api-root>` points the CLI at a non-default API.
4. Verify:

   ```bash
   mapx auth status
   ```

Rules:

- API keys must start with `mkx_`.
- If `mapx auth status` reports a missing or invalid key, stop and ask the user
  for a fresh key — never invent one.
- Never print the full key back, and never include it in file names, chat
  summaries, or logs.
- Environment variables remain supported as a fallback:
  `export MAPX_API_KEY=...` (and optional `MAPX_API_URL=...`), plus
  `--api-key` / `--url` overrides on every command.

## 3. Output contract

- By default, stdout carries a human-readable summary. With `--json`, stdout
  contains exactly one JSON object (`{"ok":true,...}` or
  `{"ok":false,"error":"..."}`); progress and logs go to stderr, so output can
  be piped to `jq`.
- Exit codes: `0` success, `1` business failure (backend error), `2` usage error.
- Field names follow the backend/CLI convention: `session_id`, `file_id`,
  `layer_id`, `feature_count`, `geometry_type`, `live_view_url`, `static_view_url`.

## 4. Command reference

```bash
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 (order persisted by backend)
mapx layers move-down <layer_id> --session <id>    # move one layer down (order 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 basemap-category --session <id> --key roads --visible false
mapx map country-mask --session <id> --code CHN                  # --code "" clears the mask
mapx map custom-mask --session <id> --file mask.geojson
mapx map custom-mask --session <id> --clear
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" \
  [--name terrain] [--attribution "© OSM"] [--opacity 0.8] [--min-zoom 0] [--max-zoom 18] [--tile-size 256]

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 styles                                 # style reference (renderer schemas/paint keys/labels/legends)
mapx skill layer-style-editing                    # style editing workflow (inspect first, incremental updates)
mapx skill report-generation                      # report generation workflow
mapx skill list                                   # list available topics
```

## 5. Typical workflow

1. Use `mapx session create` or `mapx session list` to determine the
   `session_id`.
2. Open the live map as soon as the project exists. Run
   `mapx view live --session <id>` to get `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, run
   `mapx view live --session <id> --open` instead to open the live map in the
   user's default browser.
3. Upload local data with `mapx upload <file> --session <id>`. `mapx upload`
   accepts only GeoJSON (vector) and GeoTIFF (raster) files — it does not
   convert CSV or Excel files. If the source data is CSV/Excel, first inspect
   it, identify the latitude/longitude (or x/y) columns, convert the rows to
   GeoJSON, and then upload the resulting `.geojson` file. The file is sent as
   multipart; do not paste file contents into the conversation.
4. Use `mapx layers list` to get `layer_id`, then `mapx layers get` to inspect
   geometry, fields, and the current style.
5. Before editing styles, load `mapx skill layer-style-editing` and
   `mapx skill styles`, then apply incremental changes with
   `--file style.json`.
6. To generate a report, load `mapx skill report-generation`, obtain the embed
   URL with `mapx view static --session <id>`, write `report.html`, and save it
   with `mapx report save ./report.html --session <id>`.

## 6. On-demand guides

This manual covers installation, the command surface, and the typical workflow.
Load detailed guides on demand to avoid consuming unnecessary context:

| Topic | Command | Contents |
|---|---|---|
| Style reference | `mapx skill styles` | JSON schemas for 7 renderers, paint key matrix, labels/legends, color ramps, examples |
| Style editing | `mapx skill layer-style-editing` | Inspect-first, incremental updates, decision matrix, scenarios |
| Report generation | `mapx skill report-generation` | Data analysis → embed URL → HTML → `mapx report save` |
| Topic list | `mapx skill list` | List available topics |

> The platform MCP skills (`styles`, `layer-style-editing`, `report-generation`)
> are a separate set that references MCP tools such as `map_update_layer_style`.
> They apply only to the in-product AI agent. Third-party LLMs using the CLI
> must follow the CLI versions returned by `mapx skill <topic>`.

## 7. Guardrails and best practices

- Never paste file contents (base64 or full text) into the conversation. MapX
  no longer exposes base64 upload tools; use CLI uploads, `--file`, or HTTP
  multipart instead.
- Extract only the fields you need: `mapx layers get ... --json | jq .feature_count`.
  Do not echo large JSON payloads back.
- Style changes follow "inspect first, update incrementally". Invalid JSON or
  backend errors return `{"ok":false,"error":...}`; read the error before retrying.
- Large files (>100KB) must go through `mapx upload` or HTTP multipart; base64
  is not available.
- Report HTML is read from the local file by the CLI and uploaded directly; it
  never enters the LLM context.