ACUGIS CLI

Command-line interface for the AcuGIS geospatial platform. Manage datasets, maps, dashboards, reports, databases, ETL pipelines, and synchronization projects from the terminal.

Authentication uses Central username/password login (session cookie) or a personal access token (Authorization: Bearer). Password login persists the shared acugis_session cookie — the same model as the browser. Token login is intended for CI/CD and non-interactive scripts.

Installation

Development install

cd cli
python3 -m venv .venv

# Linux / macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

pip install -e .

This installs the acugis command into your virtual environment.

Verify

acugis version
acugis --help

Quick start

acugis login https://app.acugis.cloud
acugis whoami
acugis catalog
acugis datasets list
acugis datasets preview bees

Token login (CI / automation)

Create a token in Central under Account → Personal Access Tokens, then:

acugis login https://app.acugis.cloud --token agp_xxxxxxxx
acugis whoami

Or without writing credentials to disk:

export ACUGIS_URL=https://app.acugis.cloud
export ACUGIS_TOKEN=agp_xxxxxxxx
acugis whoami
acugis catalog

Configuration

Login writes local session files under ~/.config/acugis/:

File	Purpose
config.json	Platform base URL (and optional saved PAT)
cookies.txt	Central session cookies (acugis_session) after password login

Example config.json after password login:

{
  "base_url": "https://app.acugis.cloud"
}

Example after token login:

{
  "base_url": "https://app.acugis.cloud",
  "token": "agp_xxxxxxxx"
}

Environment variable	Purpose
ACUGIS_TOKEN	Personal access token (overrides token in config.json)
ACUGIS_URL / ACUGIS_BASE_URL	Platform base URL (overrides config.json)

Session cookies or a saved token are reused across CLI restarts until they expire, are revoked, or you run acugis logout.

Shell completion

Typer provides shell completion for Bash, Zsh, Fish, and PowerShell.

Install completion for your shell:

acugis --install-completion

Show the completion script without installing:

acugis --show-completion

Restart your shell after installing completion.

Command reference

Authentication

Command	Description
acugis login <url>	Log in with Central username and password
acugis login <url> --token <pat>	Log in with a personal access token
acugis logout	Remove local config, token, and session cookies
acugis whoami	Show the current authenticated user

acugis login https://app.acugis.cloud
acugis login https://app.acugis.cloud --token agp_xxxxxxxx
acugis whoami
acugis whoami --json
acugis logout

Catalog

Command	Description
acugis catalog	List datasets, maps, dashboards, and reports

acugis catalog
acugis catalog --json

Datasets (Geovault)

Command	Description
acugis datasets list	List datasets from the platform catalog
acugis datasets preview <name>	Preview dataset records (GeoJSON)
acugis datasets info	Show dataset metadata (placeholder)
acugis datasets upload	Upload a dataset (placeholder)
acugis datasets download	Download a dataset (placeholder)
acugis datasets publish	Publish a dataset (placeholder)
acugis datasets versions	List dataset versions (placeholder)

acugis datasets list
acugis datasets list --json
acugis datasets preview bees
acugis datasets preview bees --version 2
acugis datasets preview bees --json

Maps (QGIS Publish Service)

Command	Description
acugis maps list	List published maps from the platform catalog
acugis maps info <map>	Show a comprehensive published-map summary
acugis maps open <map>	Open the map viewer URL in a browser
acugis maps layers <map>	Show layers contained in a published map
acugis maps versions <map>	List map versions/snapshots
acugis maps publish <source>	Publish a .zip / .qgs / .qgz project package
acugis maps delete	Delete a map (placeholder)

acugis maps list
acugis maps list --json
acugis maps info nyc
acugis maps open nyc
acugis maps layers nyc
acugis maps versions nyc
acugis maps publish project.zip
acugis maps publish project.qgz --title "City Infrastructure"
acugis maps publish project.zip --update nyc --open

Dashboards (Dashboard Service)

Command	Description
acugis dashboards list	List dashboards (placeholder)
acugis dashboards open	Open a dashboard (placeholder)
acugis dashboards publish	Publish a dashboard (placeholder)

Reports (Jasper)

Command	Description
acugis reports list	List reports (placeholder)
acugis reports run	Run a report (placeholder)
acugis reports schedule	Schedule a report (placeholder)
acugis reports info	Show report metadata (placeholder)

Databases (PostGIS Service)

Command	Description
acugis db list	List databases (placeholder)
acugis db create	Create a database (placeholder)
acugis db clone	Clone a database (placeholder)
acugis db backup	Back up a database (placeholder)
acugis db restore	Restore a database (placeholder)
acugis db delete	Delete a database (placeholder)

GeoETL

Command	Description
acugis etl pipelines	List ETL pipelines (placeholder)
acugis etl run	Run an ETL pipeline (placeholder)
acugis etl import	Import data via ETL (placeholder)
acugis etl status	Show ETL job status (placeholder)

Sync (GeoSync)

Command	Description
acugis sync projects	List sync projects (placeholder)
acugis sync servers	List sync servers (placeholder)
acugis sync status	Show sync status (placeholder)
acugis sync publish	Publish a sync project (placeholder)

Version

acugis version

JSON output

Commands that return data support --json for machine-readable output:

acugis whoami --json
acugis catalog --json
acugis datasets list --json
acugis datasets preview bees --json
acugis maps list --json
acugis maps info nyc --json
acugis maps layers nyc --json

Project layout

acugis/
  cli.py              Main application entry point
  auth.py             Login, logout, whoami
  catalog.py          Platform catalog
  session.py          Config, cookies, HTTP helpers
  util.py             Output formatting
  services/           Per-service command groups
pyproject.toml        Package metadata and entry points
README.md
LICENSE

License

MIT — see LICENSE.