CLI

Central does not ship a first-party CLI binary. The federation sibling package ../cli provides the Python Typer command acugis (version 0.2.0 at the reviewed revision). It authenticates against Central and calls selected Central HTTP endpoints.

Install and general usage are documented in ../cli/README.md.

Central endpoint map

REST	CLI	Status
POST /login	acugis login <url>	Implemented (interactive username/password; persists acugis_session)
GET /api/me	acugis whoami	Implemented (also used to verify login)
GET /api/me + bearer	acugis login <url> --token <pat>	Implemented (stores token in config or uses ACUGIS_TOKEN)
GET /api/catalog	acugis catalog	Implemented
GET /api/catalog	acugis search <query>	Implemented (Central catalog + optional GeoSync enrichment)
GET /api/catalog	acugis datasets list	Implemented (filters catalog type=dataset)
GET /api/catalog	acugis maps list	Implemented (filters catalog maps)
local config + cookies	acugis logout	Implemented (clears local config/token/cookies; does not call Central /logout)
—	acugis version	CLI package version only

Central APIs without CLI commands

No acugis command currently maps these Central routes:

• /api/health
• /api/portal/cards and all /api/admin/portal/*
• /api/me/tokens create/list/revoke (tokens are created in Central Account UI or raw HTTP)
• All /api/admin/users|groups|resources|permissions* routes
• Stub /api/maps|/api/reports|/api/forms|/api/datasets collections
• HTML portal pages

Other acugis service groups (datasets info/download, maps publish, dashboards, reports, db, etl, sync) target sibling services, not Central’s own admin/portal APIs.

Auth environment for CLI

Variable / file	Purpose
ACUGIS_URL / ACUGIS_BASE_URL	Platform base URL
ACUGIS_TOKEN	PAT override (agp_...)
~/.config/acugis/config.json	Saved base URL and optional token
~/.config/acugis/cookies.txt	Saved acugis_session after password login

Realistic examples

# Password session against a platform that fronts Central at /
acugis login https://app.example.test
acugis whoami
acugis whoami --json

acugis catalog
acugis catalog --json
acugis search roads --type map

# PAT automation without writing credentials (CI)
export ACUGIS_URL=https://app.example.test
export ACUGIS_TOKEN=agp_xxxxxxxx
acugis whoami
acugis catalog

# Explicit token login (writes token into config.json)
acugis login https://app.example.test --token agp_xxxxxxxx

acugis logout

Create the PAT in Central Account → Personal Access Tokens (POST /api/me/tokens) before token login.

Notes verified from source

• Password login posts form fields to Central /login, then verifies with /api/me.
• Token login never creates a session cookie; it sets Authorization: Bearer.
• acugis logout only clears local state; live Central sessions remain until TTL expiry or an explicit GET/POST /logout.
• Catalog warnings emitted by Central are printed by acugis catalog / search.