geonodectl Documentation

Overview

geonodectl is a command-line interface (CLI) tool for interacting with the GeoNode REST API v2. It allows users to manage datasets, resources, documents, maps, users, and more from the command line, making it ideal for automation, scripting, and power users.

• Project Repository: https://github.com/GeoNodeUserGroup-DE/geonodectl
• License: MIT

Features

• List, describe, upload, patch, and delete datasets, documents, maps, and geoapps
• Manage users, groups, uploads, execution requests, keywords, and linked resources
• Read and write the MapStore blob JSON for maps (get-blob, set-blob)
• Add and remove maplayers of an existing map (maplayers add, maplayers remove)
• Validate resource metadata against a JSON Schema (validate)
• Manage GeoServer styles — list, describe, upload SLD, set default style
• Transfer resources between users
• Supports authentication and secure API access
• Supports pagination, filtering, and ordering

Installation

From PyPI (recommended)

pip install geonodectl

From Source (latest development version)

pip install -e 'git+https://github.com/GeoNodeUserGroup-DE/geonodectl.git@main#egg=geonodectl'

Development Setup

pip install .[test]
pre-commit install

Configuration

GeoNode API

Set the following environment variables to connect to your GeoNode instance:

export GEONODE_API_URL=https://your-geonode-instance/api/v2/
export GEONODE_API_BASIC_AUTH=<base64-user:password>

Generate the basic auth string with:

echo -n user:password | base64

GeoServer (for geoserver subcommands)

GeoServer credentials are required only for the geoserver subcommand group.

Authentication (in order of precedence):

# Option 1 — preferred, same format as GEONODE_API_BASIC_AUTH:
export GEOSERVER_API_BASIC_AUTH=<base64-admin:password>

# Option 2 — explicit username and password:
export GEOSERVER_USER=admin
export GEOSERVER_PASSWORD=geoserver

URL — defaults to the GeoNode base URL with /geoserver appended, so no extra config is needed in standard GeoNode deployments. Override if needed:

export GEOSERVER_URL=https://your-geonode-instance/geoserver  # optional

SSL — follows GEONODE_API_VERIFY (default: True).

Usage

Get help and see available commands:

geonodectl --help

See docs/example.md for worked examples.

Command Reference

GeoNode API commands

Command	Aliases	Capabilities
resources	resource	list, delete, metadata, validate
datasets	ds, dataset	list, delete, patch, describe, upload, validate
documents	doc, document	list, delete, patch, describe, upload, validate
maps	—	list, delete, patch, describe, create, get-blob, set-blob, maplayers list/add/remove, validate
geoapps	apps	list, delete, patch, describe, validate
users	user	list, delete, patch, describe, create, transfer_resources
groups	—	list, delete, patch, describe, create
uploads	—	list, describe
executionrequest	execrequest	list, describe
keywords	—	list, describe
tkeywords	thesaurikeywords	list, describe
tkeywordlabels	thesaurikeywordlabels	list, describe
linked-resources	linkedresources	delete, add, describe
attributes	attr, attribute	describe, patch

GeoServer commands

The geoserver command group requires GeoServer credentials (see Configuration above).

Command	Description
geoserver styles list	List styles in GeoServer, optionally filtered by workspace
geoserver styles describe	Print the SLD XML for a named style
geoserver styles upload	Create or update a style from an SLD file
geoserver styles set-default	Set the default style for a GeoServer layer

Examples

# List all styles in the geonode workspace
geonodectl geoserver styles list --workspace geonode

# Show the SLD XML for a style
geonodectl geoserver styles describe foss4g_buildings --workspace geonode

# Upload a new or updated SLD file
geonodectl geoserver styles upload --name foss4g_buildings \
  --sld-path ./buildings.sld --workspace geonode

# Set the default style for a layer
geonodectl geoserver styles set-default \
  --layer geonode:buildings --style foss4g_buildings

Map blob commands

The MapStore blob is the JSON configuration that controls how a map is rendered in the GeoNode MapStore viewer (layers, zoom, center, widgets, etc.).

# Print the blob JSON for map 2073 (pipe-friendly)
geonodectl maps get-blob 2073
geonodectl maps get-blob 2073 | jq '.map.layers'

# Replace the blob JSON from a file, or from a url
geonodectl maps set-blob 2073 --json_path ./my_blob.json
geonodectl maps set-blob 2073 --json_path https://example.org/blobs/my_blob.json

Map layer commands

Add or remove the datasets shown on an existing map. Both the maplayers entries and the matching MapStore blob layers are updated, so the map stays renderable.

# Which datasets are on the map?
geonodectl maps maplayers list 2073

# Add datasets 36 and 42 as maplayers
geonodectl maps maplayers add 2073 36 42

# Remove dataset 36 from the map
geonodectl maps maplayers remove 2073 36

Metadata validation

Check that a resource's metadata meets a baseline expressed as a JSON Schema — required fields, value patterns, and conditional rules such as "a resource with a DOI must carry a real license".

geonodectl dataset validate 2162 --json_schema ./dataset-schema.json
geonodectl maps    validate 1-5  --json_schema ./map-schema.json
geonodectl resources validate 2162 --json_schema ./common-baseline.json

# the same flag takes a url, so the schema need not be copied to every machine
geonodectl dataset validate 2162 --json_schema https://example.org/schemas/dataset-schema.json

# machine readable report for CI
geonodectl --raw dataset validate 2162 --json_schema ./dataset-schema.json

Worked example schemas live in json-examples/schemas/; see docs/validate.md for details.

Identifiers: pk or uuid

Anywhere an object is named you can give its pk or its uuid — geonodectl works out which and resolves a uuid internally, refusing one that belongs to a different kind of object:

geonodectl dataset describe 2162
geonodectl dataset describe 550e8400-e29b-41d4-a716-446655440000
geonodectl maps maplayers add <map-uuid> <dataset-uuid> 42

Users and groups are not GeoNode resources and stay pk-only. A uuid is given on its own; ranges and comma lists remain integer-only. See docs/identifiers.md.

Exit codes

Every command reports its outcome through its exit code, so $? is enough to drive a script or a CI gate:

Code	Meaning
0	success
1	the operation failed (not found, rejected by the API, metadata invalid)
2	the command could not be run as asked (bad pk, missing env vars, unreadable input JSON)

geonodectl dataset describe 2162 || echo "not there"
geonodectl dataset validate 1-100 --json_schema ./dataset-schema.json || exit 1

In a pk range or list, one failure is enough to exit 1. See docs/exit-codes.md for the full contract, including how it keeps geonoderest safe to use as a library.

Development

Code Quality

This project uses pre-commit hooks and GitHub Actions for:

• Black (code formatting)
• mypy (type checking)
• flake8 (linting)

Run checks locally:

pre-commit run --all-files

Or individually:

black .
mypy src/ --ignore-missing-imports
flake8 src/

Testing

Tests are in tests/. Run with:

pytest

Contribution Guide

1. Fork the repository and create a feature branch.
2. Install development dependencies: pip install .[test]
3. Install pre-commit hooks: pre-commit install
4. Make your changes and ensure all checks pass.
5. Submit a pull request.

License

This project is licensed under the MIT License.

Further Reading

• GeoNode REST API v2 Documentation
• GeoNode Project