QGIS from the command line. A concise, readable grammar for QGIS geoprocessing — for people who don't want to write PyQGIS. Easy wins every time.
Ever get tired of clicking? Write a whole pipeline on one line — friendly verbs running on QGIS's own Processing algorithms underneath:
load roads.gpkg | buffer 100m dissolve | clip city.gpkg | save roads_local.gpkg
or even
# ── TEST 24 | add then remove vertices | densify → smooth → simplify
load "{data}/collected.gpkg|layername=park_lines" | densify 5m | smooth iterations=2 | simplify 10 | save /tmp/niva_validation/out/s3_24.gpkg
Niva turns QGIS automation from PyQGIS code into a readable single lines of text.
- Runs in QGIS's own Python
- Reaches any of its ~878 algorithms
- Near-zero dependencies on other packages. We're trying to stay within the python standard library.
- ~45 friendly verbs → real QGIS algorithms, across vector geometry, overlay, attributes, raster or use
runto any of the ~878 with no dedicated verb alias;describeshows their parameters. Every alias is validated against the installed QGIS. - Discoverable —
describe <verb>ends with a runnable example;search <keyword>fuzzy-finds functions across the verbs and QGIS ; anddocs <keyword>emits the full reference for every match — save it out withto=<file>. And more! - Databases via named QGIS connections — read (
load @conn.table,sql @conn "SELECT …"), write (save @conn.table, fail-closed withmode=create|replace|append), and analyze server-side (non-SELECTsql @conn "CREATE TABLE … AS SELECT …"). Credentials never leave QGIS. - Provenance for free — every
saverecords processing steps into metadata;assesswrites data-quality reports; the run journal echoes the exactprocessing.run(…)for each step. - Composable — chain stages with
|, compose .niva files withcall mypipeline.niva, and export a flow to a standalone PyQGIS script (niva export) or import one back. - It's just PyQGIS under the hood. - Utility verbs beyond QGIS —
notify(ntfy push when a long job finishes),email(SMTP, Gmail-aware),catalog(recurse a directory and inventory every geospatial dataset — CRS, extent, fields, bands — to a Markdown report),show(list the loadable layers/tables at a file, directory,@conn, or remote WFS/WMS/ArcGIS REST/XYZ URL — name, type, format, ready-to-load source), andinfo(inspect the local QGIS environment — the registered@connconnection names across every profile, providers, versions). Credentials fornotify/emailcome only from the environment, never the flow text.
niva in the QGIS plugin dock and on the command line — see docs/screenshots.md.
New here? Start with the Quick start.
- Quick start — install & run niva, in QGIS or as a CLI on QGIS's own Python
- User Guide — install & run niva inside QGIS and standalone, configuration, scratch space, troubleshooting
- Reference — every verb, alias, option, type, env var, CLI command, and Python entry point · Algorithm appendix — all 878 QGIS algorithms with parameters & descriptions
- Cookbook — 50 worked recipes, including spatial SQL for SpatiaLite and PostGIS
- FAQ — what libraries you need, how to run niva, scratch space, databases
- Template projects — author a QGIS project once (layout + styles), reuse it against fresh data with
project from-template= - Testing — platform support (QGIS 4.0.3 & 3.44 LTR), running the suite, and the test
.niva-companion rule (per-run detail:tests/TESTING_LOG.md) - About & goals · Plugin · Publishing a QGIS plugin — a reusable playbook · Verb ↔ algorithm map
- Design & risk docs — PRD, architecture, grammar, security, the
Oscarfailure register - CHANGELOG
📘 The whole guide (User Guide + Reference + Cookbook + FAQ + the 878-algorithm appendix) is also one PDF: niva-guide.pdf (also attached to the latest release; rebuild with python3 scripts/build_guide_pdf.py, which needs pandoc + a LaTeX engine).
GPLv3 — consistent with the QGIS ecosystem (niva builds on PyQGIS, a GPL library). Not yet on PyPI; install from source or the plugin zip.
