> ## 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

> 用 mapx 命令行客户端从第三方平台驱动 MapX 的项目、数据、样式和报告。

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

API 内部把每个项目称为 `session`；CLI 命令名（如 `mapx session create`）保留了这一技术名称。

## 安装与配置

从 OSS 下载对应平台的二进制（`latest` 别名指向最新版本）。

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
```

然后配置 API key：

```bash theme={null}
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 限定在你的账号范围内，项目所有权由后端强制校验。

## 典型工作流

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

## 命令速查

```bash theme={null}
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` 中。见[技能](/zh/developers/skills)。


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