GeoServer CLI Tools Stable

The official command-line interface for managing GeoServer instances, automating geospatial workflows, and orchestrating spatial data pipelines. Designed for DevOps, GIS engineers, and automation-first teams.

📦 Package Manager Support

Available via npm, Homebrew, apt, and direct binary distribution. Supports Windows, macOS, and Linux.

Install via npm

Terminal

$ npm install -g @geoserver/cli
✓ Installed geoserver@2.4.1

Install via Homebrew (macOS/Linux)

Terminal

$ brew tap geoserver/tools
$ brew install geoserver-cli

Direct Binary

Download pre-compiled binaries from the releases page. Extract and add the binary to your system PATH.

Quick Start

Get up and running in three steps. The CLI caches credentials securely and supports context switching for multi-tenant environments.

1. Authenticate

Terminal

$ geoserver login --url https://gis.example.com --user admin --pass your-password
✓ Authenticated to gis.example.com (Profile: default)

2. Publish a Layer

Terminal

$ geoserver layers create --workspace hydrology --name river_network --type shp --src ./data/rivers.shp
✓ Uploaded 1.2MB (2,403 features)
✓ Published WMS/WFS endpoint
🔗 https://gis.example.com/geoserver/wms?LAYERS=hydrology:river_network

Core Commands

All commands follow the pattern: geoserver <command> [subcommand] [options]

Data Management

Command	Description	Example
`layers create`	Publish a new vector/raster layer	`geoserver layers create --name lakes --src lakes.geojson`
`layers update`	Refresh layer data or styling	`geoserver layers update --name lakes --style dark_water`
`layers delete`	Remove a layer and its store	`geoserver layers delete --name lakes --force`
`data import`	Batch import multiple formats	`geoserver data import ./datasets/ --recursive`
`data export`	Extract features to file	`geoserver data export --query "POP > 10000" --out cities.csv`

Administration

Command	Description	Example
`workspaces ls`	List all workspaces	`geoserver workspaces ls --json`
`stores add`	Create database/file store	`geoserver stores add --type postgis --conn "host=db user=gis dbname=spatial"`
`styles apply`	Attach SLD/SE style	`geoserver styles apply --layer roads --style-file custom.sld`
`security sync`	Synchronize RBAC rules	`geoserver security sync --config rbac.yaml`

Utility

Command	Description	Example
`status`	Check instance health & quotas	`geoserver status`
`cache purge`	Clean tile/feature cache	`geoserver cache purge --layer topo --recursive`
`validate`	Check data/schema compliance	`geoserver validate ./input/ --strict`

Global Flags & Options

Flags Reference

-h, --help        Show usage information
-v, --verbose     Enable debug logging
--json            Output machine-readable JSON
--dry-run         Preview changes without executing
--timeout ms      API request timeout (default: 30000)
--profile name    Switch authentication context

Configuration

The CLI stores configuration in ~/.geoserver/config.json. Environment variables take precedence.

Environment Variables

Variable	Description	Example
`GEOSERVER_URL`	Default instance endpoint	`https://api.geoserver.com`
`GEOSERVER_TOKEN`	API key / JWT token	`gsv_8x92k3...`
`GEOSERVER_TIMEOUT`	Default request timeout	`60000`
`GEOSERVER_VERIFY_SSL`	Disable SSL verification	`false`

⚠️ Security Note

Never commit config.json or plaintext credentials to version control. Use environment variables or secret managers in CI/CD pipelines.

Real-World Examples

CI/CD Pipeline Deployment

GitHub Actions

- name: Deploy GeoLayers
  run: "geoserver login --token $GEOSERVER_TOKEN && geoserver data import ./output/ --auto-publish"

Batch Style Update

Bash Script

for layer in rivers highways cities; do
  geoserver layers update --name $layer --style new_theme_2025
done
echo "✅ Batch update complete"

Export to GeoPackage

Terminal

$ geoserver data export --workspace survey --layers parcels,roads --format gpkg --out export.gpkg
✓ Exported 2 layers (4.8MB)

Troubleshooting

Authentication Failed: Check GEOSERVER_TOKEN expiration or run geoserver login --refresh
Timeout Errors: Increase timeout with --timeout 60000 or check network latency
CRS Mismatch: Use geoserver validate --strict to catch projection issues before upload
Permission Denied: Verify RBAC roles via geoserver security sync --dry-run

🐛 Report an Issue

CLI bugs and feature requests are tracked on GitHub. Include geoserver --verbose output when reporting.