iserver-cli 1.0.0a2

CLI for SuperMap iServer GIS Server

SuperMap iServer CLI 使用文档

修订日期：2026-05-19

命令行工具，用于管理 SuperMap iServer GIS 服务器。

注意：当前 CLI 并非 iServer 全量能力支持，仅包含部分功能，会逐步完善。具体支持的命令和参数可通过 iserver help 查看。

功能概览

• 服务器管理: 登录、配置、连通性测试、日志查看、Token 生成
• 服务管理: 列出、启停、删除、发布、授权管理、清除指定服务缓存
• 地图服务: 地图列表、详情、导出、图例
• 数据服务: 数据源、数据集、要素增删改查
• 空间分析: 缓冲区分析、叠加分析
• 几何服务: 面积量算、距离量算

安装

pip install iserver-cli

命令帮助

主命令

Usage: python -m iserver_cli.cli [OPTIONS] COMMAND [ARGS]...

  SuperMap iServer CLI - Command line interface for GIS Server.

  Use 'iserver help' to see all available commands.

Options:
  --url TEXT                      iServer base URL
  --token TEXT                    Authentication token
  -f, --format [json|table|plain] Output format
  --config-file TEXT              Path to config file
  --version                       Show the version and exit.
  --help                          Show this message and exit.

Commands:
  analysis, config, data, datasources, geometry, help, login, logout, logs,
  map, ping, server, service, token, version

服务器管理 (server)

Usage: python -m iserver_cli.cli server [OPTIONS] COMMAND [ARGS]...

  Server management commands.

Commands:
  config        Configure CLI settings.
  login         Login to iServer with username/password or token.
  logout        Logout from iServer.
  logs          View iServer logs.
  ping          Test iServer connectivity.
  token         Generate a new access token.
  version       Show iServer version information.

login - 登录

Usage: python -m iserver_cli.cli login [OPTIONS]

  Login to iServer (username/password or token).

Options:
  --url TEXT           iServer base URL
  -u, --username TEXT  Username for login
  -p, --password TEXT  Password for login
  -t, --token TEXT     Token for authentication
  --help               Show this message and exit.

config - 配置

Usage: python -m iserver_cli.cli config [OPTIONS]

  Configure CLI settings.

Options:
  --set-url TEXT                  Set default server URL
  --set-format [json|table|plain] Set default output format
  --set-timeout INTEGER           Set request timeout in seconds
  --show                          Show current configuration
  --help                          Show this message and exit.

token - 生成访问令牌

Usage: python -m iserver_cli.cli token [OPTIONS]

  Generate a new access token.

Options:
  --url TEXT              iServer base URL
  --expire-hours INTEGER   Token expiration in hours (default: 24)
  --description TEXT      Token description
  -u, --username TEXT     Username
  -p, --password TEXT     Password
  --help                  Show this message and exit.

服务管理 (service)

Usage: python -m iserver_cli.cli service [OPTIONS] COMMAND [ARGS]...

  Service management commands.

Commands:
  authorization  Manage service authorization.
  cache-clear    Clear service cache.
  delete         Delete a service.
  list           List all services.
  publish        Publish workspace as GIS services.
  restart        Restart a service.
  start          Start a service.
  status         Show service status.
  stop           Stop a service.

service list - 列出服务

Usage: python -m iserver_cli.cli service list [OPTIONS]

  List all services.

Options:
  -t, --type TEXT    Filter by service type (map, data, spatial)
  -s, --status TEXT  Filter by status (OK, ERROR, DISABLED)
  --help             Show this message and exit.

service authorization - 服务授权

Usage: python -m iserver_cli.cli service authorization [OPTIONS] NAME

  Manage service authorization.

Options:
  -t, --type [PUBLIC|AUTHENTICATED|PRIVATE]  Authorization type
  --add-role TEXT     Add role to permitted list (for PRIVATE type)
  --remove-role TEXT  Remove role from permitted list
  --help              Show this message and exit.

service cache-clear - 清除服务缓存

Usage: python -m iserver_cli.cli service cache-clear NAME

  Clear service cache.

示例:
  iserver service cache-clear data-arcgis-DomainServer
  [OK] Cache cleared for service 'data-arcgis-DomainServer'

service publish - 发布服务

Usage: python -m iserver_cli.cli service publish [OPTIONS]

  Publish workspace as GIS services.

Options:
  -w, --workspace TEXT  Workspace path (.smwu/.sxwu)  [required]
  -t, --types TEXT      Service types: map,data (comma-separated)
  -n, --name TEXT       Base name for published services
  --help                Show this message and exit.

地图服务 (map)

Usage: python -m iserver_cli.cli map [OPTIONS] COMMAND [ARGS]...

  Map service commands.

Commands:
  cache-generate  Generate map cache.
  export          Export map image.
  info            Show map details (layers, bounds, coordinate system).
  legend          Get map legend.
  list            List all map services.
  maps            List all maps in a map service.
  query           Query features on map.

map export - 导出地图

Usage: python -m iserver_cli.cli map export [OPTIONS] NAME

  Export map image.

Options:
  -s, --service TEXT      Map service name  [required]
  --bbox TEXT             Bounding box (minx,miny,maxx,maxy)  [required]
  --width INTEGER         Image width in pixels
  --height INTEGER        Image height in pixels
  -o, --output TEXT       Output file path  [required]
  --format [png|jpg|bmp]  Image format
  --help                  Show this message and exit.

map query - 地图查询

Usage: python -m iserver_cli.cli map query [OPTIONS] NAME

  Query features on map using various modes.

  Query modes:
    BoundsQuery     - Query by bounding box
    DistanceQuery   - Query by distance from a geometry
    FindNearest     - Find nearest features
    SpatialQuery    - Spatial query with geometry
    SqlQuery        - SQL attribute query

Options:
  -s, --service TEXT           Map service name  [required]
  -m, --mode [BoundsQuery|DistanceQuery|FindNearest|SpatialQuery|SqlQuery]
                               Query mode  [required]
  -l, --layer TEXT             Target layer name (query only this layer)  [required]
  --layers TEXT                Multiple layer names (comma-separated)
  --bounds, --bbox TEXT        Bounds for BoundsQuery {"leftBottom":{"x":0,"y":0},"rightTop":{"x":100,"y":100}}  [required for BoundsQuery]
  --geometry TEXT              Geometry JSON for DistanceQuery/SpatialQuery/FindNearest  [required for DistanceQuery/SpatialQuery/FindNearest]
  --distance FLOAT             Distance for DistanceQuery/FindNearest  [default: 1.0 for DistanceQuery/FindNearest]
  --distance-unit [yard|mile|second|minute|radian|meter|degree|kilometer|inch|foot|milimeter|centimeter|decimeter]
                               Distance unit (default: meter)
  --spatial-mode [CONTAIN|CROSS|DISJOINT|IDENTITY|INNERINTERSECT|INTERSECT|OVERLAP|TOUCH|WITHIN]
                               Spatial query mode for SpatialQuery (default: INTERSECT)
  --attribute-filter, --sql TEXT
                               SQL attribute filter condition (e.g., "name='北京'")  [required for SqlQuery]
  --fields TEXT                Fields to return (comma-separated, e.g., "name,id,pop")
  --groupby TEXT               Group by field (for SqlQuery)
  --orderby TEXT               Order by field (for SqlQuery/SpatialQuery)
  --expect-count, --limit INTEGER
                               Expected result count (default: 1000)
  --start-record, --offset INTEGER
                               Start record position (default: 0)
  --query-option [ATTRIBUTE|ATTRIBUTEANDGEOMETRY|FIELD|GEOMETRY]
                               Query result option (default: ATTRIBUTEANDGEOMETRY)
  --prj-coord-sys TEXT         Coordinate system for query results
  --return-count-only          Only return feature count
  --help                       Show this message and exit.

Examples:
  iserver map query China -s map-China100/rest -m BoundsQuery --bounds "{\"leftBottom\":{\"x\":0,\"y\":0},\"rightTop\":{\"x\":100000000,\"y\":100000000}}" --layer Continent_L@China
  iserver map query China_4326 -s map-China100/rest -m SqlQuery --sql "name='北京市'" --layer Province_R@China
  iserver map query China_4326 -s map-China100/rest -m SpatialQuery --geometry '{\"type\":\"Point\",\"points\":[{\"x\":116.4,\"y\":39.9}]}' --spatial-mode CONTAIN --layer Capital_P@China#12
  iserver map query China_4326 -s map-China100/rest -m DistanceQuery --geometry '{\"type\":\"Point\",\"points\":[{\"x\":116.4,\"y\":39.9}]}' --distance 10000 --distance-unit meter --layer Water_R@China#8
  iserver map query China_4326 -s map-China100/rest -m FindNearest --geometry '{\"type\":\"Point\",\"points\":[{\"x\":116.4,\"y\":39.9}]}' --distance 50000 --layer Water_R@China#8

map legend - 图例

Usage: python -m iserver_cli.cli map legend [OPTIONS] NAME

  Get map legend.

Options:
  -s, --service TEXT  Map service name  [required]
  -l, --layer TEXT    Specific layer name
  -o, --output TEXT   Save legend image to file
  --help              Show this message and exit.

数据服务 (data)

Usage: python -m iserver_cli.cli data [OPTIONS] COMMAND [ARGS]...

  Data service commands.

Commands:
  add          Add new feature(s) to dataset.
  datasets     List datasets in a datasource.
  datasources  List datasources in a data service.
  delete       Delete feature(s) from dataset.
  list         List all data services.
  query        Query features from dataset using various modes.
  update       Update an existing feature.

data query - 数据查询

Usage: python -m iserver_cli.cli data query [OPTIONS] DATASET

  Query features from dataset using various modes.

  Query modes (getFeatureMode):
    ID                     - Query by feature IDs
    SQL                    - SQL attribute query
    BOUNDS                 - Bounding box query
    BOUNDS_ATTRIBUTEFILTER - Bounding box + attribute filter
    BUFFER                 - Geometry buffer query
    BUFFER_ATTRIBUTEFILTER - Buffer + attribute filter
    SPATIAL                - Spatial query with geometry
    SPATIAL_ATTRIBUTEFILTER - Spatial + attribute filter
    AREA                   - Area statistics for polygon datasets

Options:
  -s, --service TEXT              Data service name  [required]
  -d, --datasource TEXT           Datasource name  [required]
  -m, --mode [ID|SQL|BOUNDS|BOUNDS_ATTRIBUTEFILTER|BUFFER|BUFFER_ATTRIBUTEFILTER|SPATIAL|SPATIAL_ATTRIBUTEFILTER|AREA]
                                  Query mode  [required]
  --ids TEXT                      Feature IDs (JSON array, e.g. '[1,2,3]')
  --bounds TEXT                   Bounds (minx,miny,maxx,maxy)
  --geometry TEXT                 Geometry JSON for BUFFER/SPATIAL mode
  --buffer-distance FLOAT         Buffer distance
  --buffer-unit [yard|mile|second|minute|radian|meter|degree|kilometer|inch|foot|milimeter|centimeter|decimeter]
                                  Buffer distance unit
  --attribute-filter, --sql TEXT  SQL/attribute filter condition
  -l, --limit, --max-features INTEGER
                                  Max features (default 1000, -1 for all)
  --offset, --from-index INTEGER  Start index for pagination
  --return-count-only             Only return feature count
  --return-content                Return feature content directly
  --fields TEXT                   Fields to return (JSON array)
  --groupby TEXT                  Field to group results by (for AREA mode)
  -u, --unit [METER|KILOMETER|MU] Area unit for AREA mode
  --help                          Show this message and exit.

data add - 添加要素

Usage: python -m iserver_cli.cli data add [OPTIONS] DATASET

  Add new feature(s) to dataset.

Options:
  -s, --service TEXT     Data service name  [required]
  -d, --datasource TEXT  Datasource name  [required]
  --geometry TEXT        Geometry JSON (SuperMap format)
  --fields TEXT          Field values (JSON array)
  --field-names TEXT     Field names (JSON array)
  --feature TEXT         Complete feature JSON (overrides other options)
  --help                 Show this message and exit.

data update - 更新要素

Usage: python -m iserver_cli.cli data update [OPTIONS] DATASET

  Update an existing feature.

Options:
  -s, --service TEXT     Data service name  [required]
  -d, --datasource TEXT  Datasource name  [required]
  --id TEXT              Feature ID to update
  --geometry TEXT        New geometry JSON
  --fields TEXT          New field values (JSON array)
  --field-names TEXT     Field names (JSON array)
  --feature TEXT         Complete feature JSON (overrides other options)
  --help                 Show this message and exit.

data delete - 删除要素

Usage: python -m iserver_cli.cli data delete [OPTIONS] DATASET

  Delete feature(s) from dataset.

Options:
  -s, --service TEXT     Data service name  [required]
  -d, --datasource TEXT  Datasource name  [required]
  --id TEXT              Feature ID to delete
  --ids TEXT             Multiple IDs (JSON array)
  --sql TEXT             SQL condition to delete by
  --force                Skip confirmation
  --help                 Show this message and exit.

空间分析 (analysis)

Usage: python -m iserver_cli.cli analysis [OPTIONS] COMMAND [ARGS]...

  Spatial analysis commands.

Commands:
  buffer       Perform buffer analysis on geometry or dataset.
  density      Perform density analysis.
  interpolate  Perform interpolation analysis (IDW/Kriging/Spline).
  intersects   Check if two geometries intersect.
  nearest      Find nearest facility point.
  overlay      Perform overlay analysis on geometry or dataset.

analysis buffer - 缓冲区分析

Usage: python -m iserver_cli.cli analysis buffer [OPTIONS]

  Perform buffer analysis on geometry or dataset.

  Analysis types:
    geometry - Buffer analysis on input geometry (SuperMap JSON format)
    dataset  - Buffer analysis on existing dataset features

  Examples:
    # Geometry buffer (use --geometry, --dataset is ignored)
    iserver analysis buffer --type geometry --geometry '{"type":"POINT","points":[{"x":116.4,"y":39.9}]}' --distance 1000 --unit meter
    iserver analysis buffer --type geometry --geometry test/buffer/test_point.json --left-distance 500 --right-distance 1000 --unit kilometer --end-type flat --output buffer_result.json

    # Dataset buffer (use --dataset, --geometry is ignored)
    iserver analysis buffer --type dataset --dataset "Road_L@Jingjin" --filter "NAME='京深路'" --distance 10 --unit meter --output MyBuffer
    iserver analysis buffer --type dataset --dataset "World:Countries" --filter "SMID < 10" --distance 1000 --service spatialanalyst-China100 --output resultbuffer

Options:
  -t, --type [geometry|dataset]   Analysis type: geometry (input geometry) or dataset (existing dataset)
  -g, --geometry TEXT             Input geometry JSON or file path (for geometry type, ignored for dataset type)
  --dataset TEXT                  Dataset name in format 'dataset@datasource' (for dataset type, e.g. 'Road_L@Jingjin')
  --filter TEXT                   SQL filter for dataset features (for dataset type)
  -d, --distance FLOAT             Buffer distance (single distance for both sides)
  --left-distance FLOAT           Left buffer distance (for asymmetric buffers)
  --right-distance FLOAT          Right buffer distance (for asymmetric buffers)
  --unit [meter|kilometer|degree] Distance unit (meter/kilometer/degree)
  --end-type [round|flat]         Buffer end cap type (round/flat)
  --segments INTEGER              Number of segments to approximate a semicircle
  --epsg INTEGER                  EPSG code for coordinate system (e.g., 4326 for WGS84)
  -s, --service TEXT              Spatial analyst service name (default: spatialanalyst)
  -o, --output TEXT               Output: for geometry type, path to save buffer result; for dataset type, output dataset name (e.g., 'MyBuffer' or 'MyBuffer@Datasource')
  --help                          Show this message and exit.

analysis overlay - 叠加分析

Usage: python -m iserver_cli.cli analysis overlay [OPTIONS]

  Perform overlay analysis on geometry or dataset.

  Analysis types:
    geometry - Overlay analysis on input geometries
    dataset  - Overlay analysis on existing datasets

  Examples:
    # Geometry overlay
    iserver analysis overlay --type geometry --source '{"type":"Polygon",...}' --target '{"type":"Polygon",...}' --operation intersect --output result.json

    # Dataset overlay
    iserver analysis overlay --type dataset --source-dataset "Landuse_R@Jingjin" --operate-dataset "resultbuffer@Jingjin" --source-fields "LandType" --operation intersect --output MyOverlay

Options:
  -t, --type [geometry|dataset]   Analysis type
  -s, --source TEXT               Source geometry JSON (for geometry type)
  --target TEXT                   Target geometry JSON (for geometry type)
  --source-dataset TEXT           Source dataset 'datasource:dataset' (for dataset type)
  --operate-dataset TEXT          Operate dataset 'datasource:dataset' (for dataset type)
  --source-filter TEXT            SQL filter for source dataset
  --operate-filter TEXT           SQL filter for operate dataset
  --source-fields TEXT            Fields to copy from source (comma-separated, optional: if not specified, all fields from both datasets will be fetched and duplicate fields will be suffixed with _source/_operate)
  --operation [intersect|union|difference|clip]
                                  Overlay operation type (required)
  --service TEXT                  Spatial analyst service name
  -o, --output TEXT               Output: for geometry type, path to save overlay result; for dataset type, output dataset name
  --help                          Show this message and exit.

几何服务 (geometry)

Usage: python -m iserver_cli.cli geometry [OPTIONS] COMMAND [ARGS]...

  Geometry service commands.

Commands:
  area       Calculate polygon area.
  distance   Calculate path distance.

geometry area - 计算面积

Usage: python -m iserver_cli.cli geometry area [OPTIONS]

  Calculate area of a polygon defined by point set.

  Clockwise point order produces positive area; counter-clockwise produces 
  negative area.

Options:
  --point2ds TEXT   Point set JSON array (required, or @file.json)
  --unit TEXT       Result unit: METER, KILOMETER, MILE, FOOT, etc. (required)
  --epsg INTEGER    EPSG code for coordinate system (e.g., 4326 for WGS84)
  --service TEXT    Geometry service name (default: geometry)
  --no-cache        Disable server cache
  --help            Show this message and exit.

Examples:
  iserver geometry area --point2ds '[{"x":116.4,"y":39.9},{"x":117.4,"y":40.9},{"x":118.4,"y":39.2},{"x":116.4,"y":39.9}]' --unit KILOMETER --epsg 4326
  iserver geometry area --point2ds @polygon.json --unit METER --epsg 3857

geometry distance - 计算距离

Usage: python -m iserver_cli.cli geometry distance [OPTIONS]

  Calculate distance along a path defined by point set.

Options:
  --point2ds TEXT         Point set JSON array (required, or @file.json)
  --unit TEXT             Result unit: METER, KILOMETER, etc. (required)
  --epsg INTEGER          EPSG code for coordinate system
  --distance-mode [Geodesic|Planar]
                          Distance mode (default: Geodesic)
  --service TEXT          Geometry service name (default: geometry)
  --no-cache              Disable server cache
  --help                  Show this message and exit.

Examples:
  iserver geometry distance --point2ds '[{"x":116.4,"y":39.9},{"x":117.4,"y":40.9}]' --unit KILOMETER --epsg 4326
  iserver geometry distance --point2ds @path.json --unit METER --epsg 3857 --distance-mode Planar

快速开始

# 登录（自动保存 Token）
iserver login --url http://<YOUR_ISERVER_HOST>:<PORT>/iserver -u username -p password

# 查看版本
iserver version

# 列出地图服务
iserver map list

# 列出地图中的地图
iserver map maps -s map-China/rest

# 导出地图图片
iserver map export China -s map-China/rest --bbox 116,39,117,40 --width 800 --height 600 --output china_map.png --format png

输出格式

格式	参数
JSON	-f json 或 --format json（默认）
Table	-f table 或 --format table
Plain	-f plain 或 --format plain

示例：

iserver --format table service list
iserver -f json data datasources data-arcgis-China4326/rest

配置文件

配置存储在 ~/.iserver-cli/config.yaml：

url: http://<YOUR_ISERVER_HOST>:<PORT>/iserver
token: <YOUR_TOKEN>
timeout: 30
verify_ssl: true
output_format: json

依赖

• Python 3.10+
• click
• requests
• pyyaml
• tabulate