Skip to content

CLI

GeoVault does not ship a dedicated binary CLI. The federation acugis Python CLI (sibling ../cli) exposes dataset commands that call GeoVault HTTP APIs (typically under the /geovault reverse-proxy prefix).

Install and login are documented in ../cli/README.md. The commands below are the complete datasets group registered by ../cli/acugis/services/geovault.py at the reviewed revision.

Command map

CLI REST (proxied paths) Status
acugis datasets list GET /api/catalog (Central; filters type=dataset) Implemented
acugis datasets info <name> GET /geovault/datasets-summary; versions; metadata; fields; GeoServer publications Implemented; metadata/fields/publication failures are partly tolerated
acugis datasets schema <name> GET /geovault/datasets/{name}/versions/{v}/fields Implemented
acugis datasets sample <name> GET /geovault/datasets/{name}/versions/{v}/edit/rows with fallback GET /geovault/preview Implemented
acugis datasets versions <name> GET /geovault/datasets/{name}/versions Implemented
acugis datasets download <name> GET /geovault/versions/{version_id}/download Implemented for local-file versions only
acugis datasets preview <name> GET /geovault/preview Implemented (deprecated in CLI messaging)
acugis datasets upload Backend: POST /datasets/{name}/upload, POST /projects/{id}/upload CLI placeholder (not_implemented)
acugis datasets publish Backend: POST /versions/{id}/publish CLI placeholder (not_implemented)

The CLI docstring says PostGIS downloads receive GeoJSON, but the actual GeoVault handler requires file_path and only calls http.ServeFile; a live PostGIS row without a local path returns 404. Remote-only S3 versions likewise cannot be downloaded through this route.

Examples

acugis login https://app.example
acugis whoami

acugis datasets list
acugis datasets list --json

acugis datasets info nyc
acugis datasets info nyc --version 2 --json

acugis datasets schema nyc --layer neighborhoods
acugis datasets sample nyc --limit 10

acugis datasets versions nyc
acugis datasets download nyc --directory ./downloads
acugis datasets download nyc --version 2 --output boroughs.gpkg --overwrite

# Deprecated:
acugis datasets preview bees --version 2 --json

Token-oriented automation accepted by Central endpoints:

export ACUGIS_URL=https://app.example
export ACUGIS_TOKEN=agp_xxxxxxxx
acugis datasets list

PAT caveat: this is not merely an intermittent rejection. shared/auth can parse Bearer PATs, but GeoVault's provider is constructed without a TokenStore, so PAT-only requests to GeoVault routes are currently treated as unauthenticated. acugis datasets list calls Central /api/catalog and may work with a PAT while info, schema, sample, versions, download, and preview fail. Use a Central login/session cookie for those GeoVault routes until the provider wires token storage.

datasets download --json issues HEAD against the download URL, but GeoVault registers that route only for GET. Gorilla Mux will not infer a HEAD route from that explicit method list, so metadata mode can fail even where normal download works.

Explicit placeholders

  • acugis datasets upload is registered but only calls not_implemented(). Backend candidates exist at POST /geovault/datasets/{name}/upload and POST /geovault/projects/{id}/upload.
  • acugis datasets publish is registered but only calls not_implemented(). The legacy backend candidate is POST /geovault/versions/{id}/publish; GeoServer also has a separate publish API.
  • All sibling acugis db commands—list, create, clone, backup, restore, and delete—are placeholders. They are described as PostGIS Service commands and do not map to GeoVault's database-service proxy.

GeoVault endpoints with no dataset CLI mapping

No acugis datasets command maps the following route families:

  • Folder create/read/update/archive and folder-scoped browsing
  • URL import, S3 import/remote registration, quick import, and direct project upload/list
  • Dataset version delete, edit capability/schema, row insert/update/delete, distinct values, filter, dissolve, and clip
  • Dataset rename, user metadata save, archive, restore, clone, permanent delete, lineage, rollback, and publish-capability
  • QGIS project list/detail/version/restore/download proxy routes
  • PostgreSQL connection test/CRUD/table browse/edit and PostGIS dataset registration
  • PostGIS Service connection/database discovery, create, adopt, PostgreSQL-user, schema, and table proxy routes
  • ESRI browse/import/job routes
  • GeoServer connection/workspace/catalog/style/publish/job administration routes
  • Discovery and the no-op POST /register

This is an explicit absence of CLI mappings, not a claim that the HTTP endpoints are unsupported. See API for route contracts.

Source references

Path Role
../cli/acugis/services/geovault.py Typer command group
../cli/acugis/services/geovault_client.py HTTP helpers
../cli/acugis/cli.py Registers datasets group