Configuration#

GeoServer CLI uses a flexible configuration system that supports multiple environments and configuration methods.

Configuration Files#

Configuration files live in the configs/ directory and follow the naming convention configs/<name>.config.toml.

Default Configuration#

The default configuration template is configs/default.config.toml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
[geoserver]
# GeoServer REST connection settings.
base_url = "http://localhost:8080/geoserver/rest"
username = "admin"
password = ""
timeout  = "30s"

[postgis]
# Optional PostGIS connection settings for publishing workflows
host = "localhost"
port = 5432
database = "gis"
user = "postgres"
password = ""
schema = "public"
sslmode = "disable"

Creating Custom Configurations#

Create environment-specific configurations:

1
2
3
4
5
# Create a development config
cp configs/default.config.toml configs/dev.config.toml

# Create a production config
cp configs/default.config.toml configs/prod.config.toml

Edit these files with your environment-specific settings.

Configuration Selection#

Configuration is selected in the following order (highest precedence wins):

CLI flag: --config or -c
Environment variable: GEOSRVCLI_CONFIG
Fallback: configs/default.config.toml

Using CLI Flag#

1
2
3
4
5
# Use a named config (resolves to configs/dev.config.toml)
./geoserver-cli workspace list --config dev

# Use a full path
./geoserver-cli workspace list --config /path/to/config.toml

Using Environment Variable#

1
2
3
4
5
# Set environment variable
export GEOSRVCLI_CONFIG=dev

# Commands will use configs/dev.config.toml
./geoserver-cli workspace list

Using direnv (Recommended)#

Create a .envrc file:

1
2
3
4
export GEOSRVCLI_CONFIG=dev
export GEOSRVCLI_DEFAULT_WORKSPACE=my_workspace
export GEOSRVCLI_ENDPOINT=http://localhost:8080/geoserver/rest
PATH_add ./bin

Then run:

1
direnv allow

Environment Variable Overrides#

You can override any configuration setting using environment variables:

Config Setting	Environment Variable
`base_url`	`GEOSRVCLI_ENDPOINT`
`username`	`GEOSRVCLI_USERNAME`
`password`	`GEOSRVCLI_PASSWORD`
`timeout`	`GEOSRVCLI_TIMEOUT`
`[postgis].host`	`GEOSRVCLI_POSTGIS_HOST`
`[postgis].port`	`GEOSRVCLI_POSTGIS_PORT`
`[postgis].database`	`GEOSRVCLI_POSTGIS_DATABASE`
`[postgis].user`	`GEOSRVCLI_POSTGIS_USER`
`[postgis].password`	`GEOSRVCLI_POSTGIS_PASSWORD`
`[postgis].schema`	`GEOSRVCLI_POSTGIS_SCHEMA`
`[postgis].sslmode`	`GEOSRVCLI_POSTGIS_SSLMODE`

CLI Flag Overrides#

Global flags can override configuration:

1
2
3
4
5
6
7
8
# Override base URL
./geoserver-cli workspace list --base-url http://prod-server:8080/geoserver/rest

# Override username
./geoserver-cli workspace list --user admin

# Override timeout
./geoserver-cli workspace list --timeout 60s

Configuration Precedence#

Settings are resolved in this order (highest to lowest):

CLI flags (--base-url, --user, etc.)
Environment variables (GEOSRVCLI_*)
Configuration file (configs/*.config.toml)
Default values

Initialize Configuration#

Create a new configuration file:

1
2
3
4
5
# Initialize default config
./geoserver-cli config init

# Initialize custom config
./geoserver-cli config init --config configs/prod.config.toml

Validate Configuration#

Check your configuration:

1
2
3
4
5
# Show resolved configuration
./geoserver-cli config show

# Validate configuration file
./geoserver-cli config validate

Default Workspace#

Set a default workspace to avoid specifying --workspace in every command:

1
2
3
4
5
# Set via environment variable
export GEOSRVCLI_DEFAULT_WORKSPACE=my_workspace

# Or use direnv (.envrc)
export GEOSRVCLI_DEFAULT_WORKSPACE=my_workspace

The CLI will prompt you to persist this setting to .envrc if you use a different workspace.