Il catalogo Open Data della Ragioneria Generale dello Stato da terminale: ricerca offline, righe filtrate per nome di colonna leggibile e opere pubbliche cercabili per CUP, CIG o codice fiscale.
OpenBDAP pubblica migliaia di dataset di finanza pubblica dietro un'API CKAN con conteggi sbagliati e un OData con nomi di colonna offuscati e senza elenco. Questa CLI allinea il catalogo in un archivio SQLite locale con 'allinea', ci costruisce sopra una ricerca full-text su titolo e descrizione, e traduce i nomi leggibili delle colonne negli identificativi che il servizio pretende. Comandi come dossier, opere e serie fanno in un colpo cio' che oggi richiede una manciata di chiamate costruite a mano.
Prima di iniziare
cerca, serie, mop, novita, cup, cig, dossier e opere leggono un archivio SQLite locale: popolalo con openbdap-pp-cli allinea (qualche minuto per i 3857 dataset del catalogo, o --tema <tema> per un sottoinsieme). campi usa un secondo indice, che si costruisce con openbdap-pp-cli campi --aggiorna --tema <tema>. I comandi che interrogano il portale dal vivo senza passare dall'archivio sono catalogo, dati, gruppi, tag, licenze, scarica, colonne, righe e conta.
Quick Start
# verifica che il portale risponda
openbdap-pp-cli doctor --dry-run
# allinea il catalogo nell'archivio locale: serve a cerca, serie, mop, novita e campi
openbdap-pp-cli allinea
# cerca offline su titolo e descrizione
openbdap-pp-cli cerca "opere pubbliche"
# capisci le colonne prima di estrarre le righe
openbdap-pp-cli colonne bda1676b-62ab-44b7-8f9a-ca93b8534488
# il quadro completo di un'opera dal CUP
openbdap-pp-cli dossier I77H11000120009
Unique Features
These capabilities aren't available in any other tool for this API.
Opere pubbliche trasversali
-
dossier — Il quadro completo di un'opera pubblica a partire dal CUP: progetto, pagamenti, gare, partecipanti, piano dei costi e soggetti titolari.
Usalo quando ti serve tutto su un'opera e hai solo il CUP, invece di cinque chiamate OData con filtri diversi.
openbdap-pp-cli dossier I77H11000120009 --agent
-
opere — Le opere pubbliche in capo a un ente, a partire dal suo codice fiscale, con il totale reale.
Usalo per capire quante e quali opere risultano a un'amministrazione.
openbdap-pp-cli opere --cf 80208450587 --agent
-
mop — Quale dataset MOP interrogare per ogni regione e ruolo, con il relativo identificativo OData.
Usalo prima di una ricerca mirata sulle opere pubbliche, per sapere dove cercare.
openbdap-pp-cli mop --regione Sicilia --agent
-
cig — La gara e i partecipanti a partire dal codice CIG.
Usalo quando parti da un CIG invece che da un CUP.
openbdap-pp-cli cig 12345678AB --agent
Catalogo che si capisce
-
serie — Le annualita', le mensilita' e le regioni disponibili di una stessa serie di dataset.
Usalo per sapere se esiste l'annualita' che ti serve senza scorrere il catalogo.
openbdap-pp-cli serie "Pagamenti Bilancio dello Stato" --agent
-
novita — I dataset il cui ultimo aggiornamento cade nella finestra indicata.
Usalo per sapere cosa e' cambiato di recente senza riscaricare il catalogo.
openbdap-pp-cli novita --da 30d --agent
-
campi — In quali dataset esiste un campo, con l'identificativo pronto da usare nei filtri.
Usalo quando sai quale campo ti serve ma non in quale dataset vive.
openbdap-pp-cli campi "codice fiscale" --agent
Recipes
Allineare il catalogo prima di ogni ricerca offline
openbdap-pp-cli allinea
Popola l'archivio SQLite locale su cui lavorano cerca, serie, mop e novita.
Trovare i dataset di un tema e un anno
openbdap-pp-cli cerca SIOPE --anno 2024 --agent
Cerca offline nell'archivio locale con i filtri derivati dai titoli.
Estrarre righe filtrate senza conoscere gli identificativi di colonna
openbdap-pp-cli righe bda1676b-62ab-44b7-8f9a-ca93b8534488 --dove "Codice CUP=I77H11000120009" --csv
Il nome leggibile viene tradotto nell'identificativo che il servizio pretende.
Il quadro di un'opera, campi essenziali
openbdap-pp-cli dossier I77H11000120009 --agent --select cup,progetto
Riduce il documento alle sole chiavi di primo livello che servono all'agente.
Contare le opere di un ente
openbdap-pp-cli opere --cf 80208450587 --solo-conteggio
Usa il conteggio reale del servizio invece di scaricare le righe.
Costruire l'indice dei campi e cercarci dentro
openbdap-pp-cli campi --aggiorna --tema 172_opere-pubbliche
L'indice degli schemi si popola su richiesta: senza questo passaggio 'campi' non trova nulla.
Usage
Run openbdap-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data such as data.db |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
OPENBDAP_CONFIG_DIR, OPENBDAP_DATA_DIR, OPENBDAP_STATE_DIR, or OPENBDAP_CACHE_DIR
--home <dir> for this invocationOPENBDAP_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export OPENBDAP_HOME=/srv/openbdap
openbdap-pp-cli doctor
Under OPENBDAP_HOME=/srv/openbdap, the four dirs resolve to /srv/openbdap/config, /srv/openbdap/data, /srv/openbdap/state, and /srv/openbdap/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"openbdap": {
"command": "openbdap-pp-mcp",
"env": {
"OPENBDAP_HOME": "/srv/openbdap"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as OPENBDAP_DATA_DIR overrides an explicit --home for that kind. Use OPENBDAP_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting OPENBDAP_HOME does not move files back to platform defaults, and doctor cannot find files left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. Run openbdap-pp-cli doctor --fail-on warn to check path warnings in automation.
Commands
catalogo
Dataset del catalogo OpenBDAP
openbdap-pp-cli catalogo dettaglio - Metadati di un dataset (solo per UUID: i nomi non sono risolvibili)openbdap-pp-cli catalogo elenco - Elenca gli identificativi di tutti i dataset del catalogoopenbdap-pp-cli catalogo ricerca - Ricerca testuale lato portale (il campo count non e' affidabile e fq viene ignorato)
dati
Dati tabellari dei dataset via OData
openbdap-pp-cli dati colonne - Colonne del dataset: nome leggibile, nome fisico, identificativo da usare nei filtri, tipo, cardinalita' e valori distintiopenbdap-pp-cli dati conta - Conta le righe del dataset, rispettando il filtroopenbdap-pp-cli dati metadati - Metadati OData del dataset (ultimo aggiornamento, stato)openbdap-pp-cli dati misure - Misure numeriche dichiarate dal datasetopenbdap-pp-cli dati righe - Righe del dataset, con filtri OData
gruppi
Temi (gruppi) del catalogo
openbdap-pp-cli gruppi dettaglio - Dettaglio di un tema, con gli UUID dei dataset che contieneopenbdap-pp-cli gruppi elenco - Elenca i temi del catalogo
licenze
Licenze usate nel catalogo
openbdap-pp-cli licenze - Elenca le licenze
scarica
Scaricamento integrale dei dataset in CSV
openbdap-pp-cli scarica <id> - Scarica l'intero dataset in CSV (separatore punto e virgola)
tag
Parole chiave del catalogo
openbdap-pp-cli tag - Elenca le parole chiave
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
openbdap-pp-cli recall <query> - Look up cached resources for a query before running discoveryopenbdap-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)openbdap-pp-cli learnings list - Inspect taught rowsopenbdap-pp-cli learnings forget <query> - Undo a teachopenbdap-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectopenbdap-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsopenbdap-pp-cli teach-pattern - Install a query/resource template up frontopenbdap-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set OPENBDAP_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of openbdap-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
openbdap-pp-cli catalogo dettaglio --id d032b3a2-2b70-4193-a0c8-cb7eb69f8710
# JSON for scripting and agents
openbdap-pp-cli catalogo dettaglio --id d032b3a2-2b70-4193-a0c8-cb7eb69f8710 --json
# Filter to specific fields
openbdap-pp-cli catalogo dettaglio --id d032b3a2-2b70-4193-a0c8-cb7eb69f8710 --json --select id,name,title
# Dry run — show the request without sending
openbdap-pp-cli catalogo dettaglio --id d032b3a2-2b70-4193-a0c8-cb7eb69f8710 --dry-run
# Agent mode — JSON + compact + no prompts in one flag
openbdap-pp-cli catalogo dettaglio --id d032b3a2-2b70-4193-a0c8-cb7eb69f8710 --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select <field>[,<field>...] returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit confirmation -
--agent does not imply --yes; pass --yes separately only after the target, arguments, and side effects are clear
- Piped input -
feedback --stdin legge una nota dallo standard input; questa CLI non ha comandi che scrivono sul portale
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 1 unexpected error, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.
I comandi in italiano non usano il codice 3 per "nessun risultato": restituiscono 0 con una lista vuota e, quando la causa e' l'archivio locale non popolato, una nota che dice quale comando lanciare.
Health Check
openbdap-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Run openbdap-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/openbdap-pp-cli/config.toml; --home, OPENBDAP_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Usa
catalogo elenco o cerca per vedere gli identificativi disponibili
API-specific
- Il servizio OData risponde 500 — Stai usando l'UUID del dataset al posto dell'identificativo OData: prendilo da 'catalogo dettaglio'.
- L'estrazione delle righe va in timeout — Riduci la pagina: oltre 5000 righe per chiamata il servizio non risponde.
- La ricerca sul portale restituisce conteggi incoerenti — Usa 'cerca', che interroga l'archivio locale: il campo count dell'API e' inaffidabile.
- Il download CSV non parte — L'indirizzo http non funziona, serve https: la CLI lo forza gia'.
- cerca, serie, mop, novita, cup, cig, dossier o opere non restituiscono nulla — L'archivio locale e' vuoto: lancia 'openbdap-pp-cli allinea'. La risposta lo dice anche nel campo nota.
- campi non trova il campo cercato — L'indice degli schemi si popola a parte: lancia 'openbdap-pp-cli campi --aggiorna --tema 172_opere-pubbliche'.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press