Frequently Asked Questions#

Common questions about using GeoServer CLI.

General#

What is GeoServer CLI?#

GeoServer CLI is a command-line tool for managing GeoServer via its REST API. It’s written in Go and provides a fast, scriptable interface for common GeoServer operations.

Why use CLI instead of the web UI?#

• Automation: Script complex workflows
• Speed: Faster than clicking through the UI
• Repeatability: Same commands produce same results
• CI/CD: Integrate with deployment pipelines
• Bulk operations: Process many layers at once

What GeoServer versions are supported?#

GeoServer CLI is tested with GeoServer 2.20+ but should work with any version that supports the REST API.

Configuration#

Can I use multiple configurations?#

Yes! Create multiple config files and switch between them:

1
2
3
4
5

# Development
./geoserver-cli workspace list --config dev

# Production
./geoserver-cli workspace list --config prod

Or use environment variables:

1
2

export GEOSRVCLI_CONFIG=prod
./geoserver-cli workspace list

How do I store passwords securely?#

Best practices for password management:

1. Environment variables (recommended):

   1	export GEOSRVCLI_PASSWORD=your-password

2. Secure config file permissions:

   1	chmod 600 configs/prod.config.toml

3. Vault integration (advanced):

   1 2	# Read from vault export GEOSRVCLI_PASSWORD=$(vault read -field=password secret/geoserver)

4. Never commit passwords to git:

   1 2	# Add to .gitignore echo "configs/*.config.toml" >> .gitignore

Can I use the same config for multiple GeoServer instances?#

Yes, use environment variables to override:

1
2
3
4
5
6
7

# Staging
GEOSRVCLI_ENDPOINT=http://staging.example.com/geoserver/rest \
  ./geoserver-cli workspace list

# Production
GEOSRVCLI_ENDPOINT=http://prod.example.com/geoserver/rest \
  ./geoserver-cli workspace list

Workspaces and Datastores#

What’s the difference between a workspace and a datastore?#

• Workspace: Logical container for organizing layers (like a folder)
• Datastore: Connection to a data source (PostGIS, files, etc.)

A workspace can have multiple datastores, and each datastore belongs to one workspace.

Do I need to create a datastore before publishing layers?#

For PostGIS publishing, the CLI creates the datastore automatically if it doesn’t exist:

1
2

# CLI will create "postgis" datastore if missing
./geoserver-cli publish postgis --all -w my_workspace --store postgis

For other data sources, create the datastore first:

1

./geoserver-cli store create my_store -w my_workspace --params @params.json

Can I delete a workspace with layers?#

No, you must delete layers and datastores first:

1
2

# This will fail if workspace has content
./geoserver-cli workspace delete my_workspace --yes

Delete content through the GeoServer web UI or REST API first.

Publishing#

What data sources can I publish from?#

Currently supported:

• PostGIS - PostgreSQL with PostGIS extension
• Files - Shapefiles (.zip), GeoTIFF (.tif) via Importer extension

How do I publish all tables from a PostGIS database?#

1
2
3
4
5
6
7

# Publish all spatial tables
./geoserver-cli publish postgis --all -w my_workspace

# With filters
./geoserver-cli publish postgis --all -w my_workspace \
  --include "^data_" \
  --exclude "_temp$"

What happens if I publish the same layer twice?#

The CLI is idempotent - it skips layers that already exist:

1
2
3

roads: published
buildings: skipped (already exists)
water: published

Can I publish layers in parallel?#

Yes! Use the --concurrency flag:

1
2

# Use 4 parallel workers
./geoserver-cli publish postgis --all -w my_workspace --concurrency 4

Why is publishing slow?#

Several factors affect speed:

1. GeoServer performance - Check server resources
2. Network latency - Use --timeout to increase timeout
3. Table size - Large tables take longer to process
4. Concurrent publishing - Use --concurrency to parallelize

Styles#

How do I create a style from an SLD file?#

1

./geoserver-cli style create my_style --sld @style.sld

Can I use the same style for multiple layers?#

Yes, styles are global and can be reused:

1
2
3
4
5
6

# Create style once
./geoserver-cli style create standard --sld @standard.sld

# Apply to multiple layers
./geoserver-cli layer update roads --default-style standard
./geoserver-cli layer update highways --default-style standard

Where can I get SLD files?#

• GeoServer web UI: Preview layer → Layer Data tab → SLD
• Export from QGIS: Layer → Properties → Symbology → Style → Save as SLD
• Online galleries: GeoServer documentation, QGIS style library

QGIS Integration#

Do I need credentials in exported QGIS files?#

No! For security, credentials are NOT included by default. Configure QGIS Auth Manager instead:

1
2

# Export without credentials (recommended)
./geoserver-cli qgis export connections -w my_workspace -o connections.xml

See QGIS Authentication Guide for setup.

Can QGIS edit layers published through the CLI?#

Yes, if you use WFS connections:

1. Export with WFS: ./geoserver-cli qgis export connections
2. Configure QGIS Auth Manager
3. Enable editing in QGIS layer properties

Why don’t layers show up in QGIS?#

Check these:

1. Layer is advertised:

   1	./geoserver-cli layer update my_layer --advertised true

2. Layer is enabled:

   1	./geoserver-cli layer update my_layer --enabled true

3. QGIS auth is configured - See QGIS auth guide

Performance#

How can I speed up bulk operations?#

1. Use concurrency:

   1	./geoserver-cli publish postgis --all -w test --concurrency 8

2. Process in batches:

   1 2	# Instead of --all at once ./geoserver-cli publish postgis --layers table1,table2,table3 -w test

3. Increase timeout:

   1	./geoserver-cli publish postgis --all -w test --timeout 120s

Does the CLI support caching?#

No built-in caching, but you can script it:

1
2
3
4
5

# Cache workspace list
./geoserver-cli workspace list > workspaces.txt

# Use cached list
cat workspaces.txt

Automation and CI/CD#

Can I use this in CI/CD pipelines?#

Yes! The CLI is designed for automation:

1
2
3
4
5

# GitLab CI example
deploy:
  script:
    - ./geoserver-cli config init
    - ./geoserver-cli publish postgis --all -w production

How do I handle failures in scripts?#

The CLI returns non-zero exit codes on failure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

#!/bin/bash
set -e  # Exit on first error

./geoserver-cli workspace create prod || echo "Workspace exists"
./geoserver-cli publish postgis --all -w prod

if [ $? -eq 0 ]; then
  echo "Publishing succeeded"
else
  echo "Publishing failed"
  exit 1
fi

Can I run this in Docker?#

Yes, though there’s no official image yet. You can build your own:

1
2
3
4
5

FROM golang:1.24
WORKDIR /app
COPY . .
RUN go build -o geoserver-cli ./cmd/geoserver-cli
ENTRYPOINT ["./geoserver-cli"]

Development#

How do I contribute?#

See the Contributing Guide.

Can I add support for new data sources?#

Yes! The architecture supports adding new publishers:

1. Create a new publisher in internal/cli/publish_*.go
2. Implement the publishing logic
3. Add tests
4. Update documentation
5. Submit a merge request

How does the pre-commit hook work?#

See Pre-commit Hooks for details.

Troubleshooting#

Command fails with “connection refused”#

See Troubleshooting Guide.

“Config file not found” error#

Initialize the configuration:

1

./geoserver-cli config init

Pre-commit hook fails#

Install required tools:

1

./scripts/install-tools.sh

More Questions?#

• Check the Troubleshooting Guide
• Browse Command Reference
• Open an issue on GitLab