mapx CLI

MapX 通过 mapx 命令行客户端暴露可供代理调用的能力。第三方平台（WorkBuddy、本地 LLM 工具循环、自动化脚本）可以运行这个单一二进制来控制项目、上传数据、修改地图样式和保存报告，而无需嵌入产品 UI。 API 内部把每个项目称为 session；CLI 命令名（如 mapx session create）保留了这一技术名称。

安装与配置

从 OSS 下载对应平台的二进制（latest 别名指向最新版本）。 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

然后配置 API key：

export MAPX_API_URL="https://api.mapxagent.com"   # 可选
export MAPX_API_KEY="mkx_..."                     # 个人 key，只显示一次
mapx auth status                                  # 验证（Windows：.\mapx.exe auth status）

每个命令都接受 --api-key 和 --url 覆盖参数。key 限定在你的账号范围内，项目所有权由后端强制校验。

典型工作流

mapx session create --title "analysis"（或 mapx session list）获取 session_id（项目 ID）。
mapx view live --session <id>——项目创建后立即打开实时地图。命令返回 live_view_url（SSE 同步的实时视图）。如果 agent 平台能渲染网页，把该 URL 加载到 agent 界面中，让用户实时看到地图变化（例如 WorkBuddy）；如果 agent 无法渲染网页，改用 mapx view live --session <id> --open，在用户默认浏览器中打开实时地图。
mapx upload ./data.geojson --session <id>——直接上传本地数据。该命令只接受 GeoJSON（矢量）和 GeoTIFF（栅格）文件。如果源数据是 CSV/Excel，先识别经纬度列，把数据转换为 GeoJSON，再上传生成的 .geojson 文件。
mapx layers list --session <id>，然后 mapx layers get <layer_id> --session <id> 查看几何、字段和当前样式。
mapx layers style <layer_id> --session <id> --file style.json——应用增量样式修改。
mapx report save ./report.html --session <id>——保存 HTML 报告。

命令速查

mapx auth status                                   # 校验 API key
mapx auth login <mkx_...>                          # 本地保存 API key（~/.mapx/config.json）
mapx auth logout                                   # 删除本地保存的 API key

mapx session create --title "analysis"             # 创建项目；返回 session_id
mapx session list                                  # 列出项目
mapx session get <id>                              # 查看项目
mapx session delete <id>                           # 删除项目

mapx upload ./data.geojson --session <id>          # 上传：GeoJSON（矢量）→图层，GeoTIFF（栅格）→COG；CSV/Excel 需先转为 GeoJSON
mapx files list --session <id>                     # 列出文件
mapx files delete <file_id> --session <id>         # 删除文件及其关联图层
mapx assets list --session <id>                    # 列出所有数据资产（图层 + 文件）

mapx layers list --session <id>                    # 列出图层
mapx layers get <layer_id> --session <id>          # 图层信息（几何/字段/样式）
mapx layers style <layer_id> --session <id> --file style.json
mapx layers visible <layer_id> true --session <id>
mapx layers rename <layer_id> "新名称" --session <id>
mapx layers delete <layer_id> --session <id>
mapx layers move-up <layer_id> --session <id>      # 图层上移（后端持久化）
mapx layers move-down <layer_id> --session <id>    # 图层下移（后端持久化）
mapx layers reorder --session <id> --ids <id1>,<id2>,<id3>   # 一次性重排全部图层

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 "" 取消遮罩
mapx map custom-mask --session <id> --file mask.geojson         # 或 --geojson <json>；--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>                                   # 视野/底图/遮罩状态
mapx map add-tile-layer --session <id> --tile-url "https://tiles.example.com/{z}/{x}/{y}.png"

mapx view static --session <id>                    # 静态 embed URL（iframe/报告）
mapx view live --session <id>                      # 打印实时视图 URL；agent 平台支持渲染网页时（如 WorkBuddy）在 agent 界面中加载
mapx view live --session <id> --open               # agent 无法渲染网页时，在默认浏览器中打开实时地图

mapx report save ./report.html --session <id> --title "分析报告"

mapx skill                                        # 本手册
mapx skill list                                   # 列出可用主题

所有命令都支持 --json 输出机器可读结果。

输出契约

使用 --json 时，stdout 输出单个 JSON 对象（{"ok":true,...} 或 {"ok":false,"error":"..."}）；进度信息输出到 stderr。退出码：0 成功、1 业务失败、2 用法错误。

技能

执行复杂任务前，用 mapx skill 打印命令手册。完整技能索引存储在 source/skills.json 中。见技能。

开始使用

API 参考

客户端

安装与配置

典型工作流

命令速查

输出契约

技能

​安装与配置

​典型工作流

​命令速查

​输出契约

​技能

安装与配置

典型工作流

命令速查

输出契约

技能