pp-istat

# ISTAT EsploraDAti — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `istat-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer: ```bash npx -y @mvanhorn/printing-press-library install istat --cli-only ``` 2. Verify: `istat-pp-cli --version` 3. Ensure `$GOPATH/bin` (or `$HOME/go/bin`) is on `$PATH`. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer): ```bash go install github.com/mvanhorn/printing-press-library/library/developer-tools/istat/cmd/istat-pp-cli@latest ``` If `--version` reports "command not found" after install, the install step did not put the binary on `$PATH`. Do not proceed with skill commands until verification succeeds. istat-pp-cli mirrors the Italian national statistics catalog locally so you can search, explore, and download data without burning your 5-request/minute quota. One sync command unlocks instant full-text search across 4849 datasets, dimension inspection, and filtered time series download in JSON, CSV, or native SDMX-XML. ## When to Use This CLI Use this CLI when you need to query ISTAT Italian statistics data programmatically, build data pipelines from official Italian national statistics, or enable AI agents to answer questions about Italian economic, demographic, or social indicators. ## Anti-triggers Do not use this CLI for: - Do not use for Eurostat or other EU statistics (use eurostat-pp-cli or similar) - Do not use for real-time market data - Do not use for ISTAT microdata (requires separate ISTAT access) ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Local state that compounds - **`search`** — Search all 4849 ISTAT datasets instantly from a local SQLite mirror. _Use this before any data query to find the exact dataflow ID without burning API quota._ ```bash istat-pp-cli search prezzi consumatori --json ``` - **`sync`** — Download all 4849 dataflows and their structural metadata to local SQLite. _Run this once to unlock all offline operations._ ```bash istat-pp-cli sync ``` - **`show`** — Show dimensions, measures, and codelist values for any ISTAT dataset. _Use this before get to understand what filters are available._ ```bash istat-pp-cli show 101_1033_DF_DCSP_MACELLAZIONI_1 --json ``` ### Agent-native plumbing - **`get`** — Download time series data with dimension filters, last-N observations, and date ranges. _Use this to pull ISTAT time series into your data pipeline in one command._ ```bash istat-pp-cli get 101_1033_DF_DCSP_MACELLAZIONI_1 --filter FREQ=M,REF_AREA=IT --last 24 --format csv ``` - **`availability`** — Discover which dimension values actually have data before downloading. _Use this when building filter strings to avoid empty responses._ ```bash istat-pp-cli availability 101_1033_DF_DCSP_MACELLAZIONI_1 --json ``` ## Command Reference **availability** — Manage availability - `istat-pp-cli availability <agencyID> <resourceID> <version> <key> <componentID>` — See which data would match a query, without actually retrieving these data. **data** — Manage data - `istat-pp-cli data <agencyID> <resourceID> <version> <key>` — Data queries allow **retrieving statistical data**. **metadata** — Manage metadata - `istat-pp-cli metadata get` — These queries enable clients to find metadatasets by the identification of the metadataset - `istat-pp-cli metadata get-metadataflow` — These queries enable clients to find metadatasets by the collection (metadataflow) - `istat-pp-cli metadata get-structure` — These queries enable clients to request all metadata sets which are reported against one or more structures. **schema** — Manage schema - `istat-pp-cli schema <agencyID> <resourceID> <version>` — Data validity queries (aka schema queries) allow retrieving **the definition of data validity for a certain context**. **structure** — Manage structure - `istat-pp-cli structure get` — Structure queries allow **retrieving structural metadata**. - `istat-pp-cli structure get-itemschemetype` — Item queries extend structure queries by allowing to retrieve items in item schemes such as particular codes in a ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash istat-pp-cli which "<capability in your own words>" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. ## Recipes ### Find and download CPI data ```bash istat-pp-cli search prezzi consumatori && istat-pp-cli get 101_1033_DF_DCSP_MACELLAZIONI_1 --filter FREQ=M,REF_AREA=IT --last 24 --format csv ``` Search for CPI datasets then download 24 months of monthly Italian CPI data as CSV. ### Inspect a dataset structure ```bash istat-pp-cli show 101_1033_DF_DCSP_MACELLAZIONI_1 --json --select dimensions ``` Get the dimension list and codelist values for the CPI dataset as JSON. ### Check data availability ```bash istat-pp-cli availability 101_1033_DF_DCSP_MACELLAZIONI_1 --agent ``` Discover which dimension values have data before building a query. ## Auth Setup No authentication required. Run `istat-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color --yes`. - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash istat-pp-cli availability 101_1033_DF_DCSP_MACELLAZIONI_1 --agent ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Read-only** — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": <data> } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Agent Feedback When you (or the agent) notice something off about this CLI, record it: ``` istat-pp-cli feedback "the --since flag is inclusive but docs say exclusive" istat-pp-cli feedback --stdin < notes.txt istat-pp-cli feedback list --json --limit 10 ``` Entries are stored locally at `~/.local/share/istat-pp-cli/feedback.jsonl`. They are never POSTed unless `ISTAT_FEEDBACK_ENDPOINT` is set AND either `--send` is passed or `ISTAT_FEEDBACK_AUTO_SEND=true`. Default behavior is local-only. Write what *surprised* you, not a bug report. Short, specific, one line: that is the part that compounds. ## Output Delivery Every command accepts `--deliver <sink>`. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported: | Sink | Effect | |------|--------| | `stdout` | Default; write to stdout only | | `file:<path>` | Atomically write output to `<path>` (tmp + rename) | | `webhook:<url>` | POST the output body to the URL (`application/json` or `application/x-ndjson` when `--compact`) | Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr. ## Named Profiles A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern. ``` istat-pp-cli profile save briefing --json istat-pp-cli availability 101_1033_DF_DCSP_MACELLAZIONI_1 istat-pp-cli profile list --json istat-pp-cli profile show briefing istat-pp-cli profile delete briefing --yes ``` Explicit flags always win over profile values; profile values win over defaults. `agent-context` lists all available profiles under `available_profiles` so introspecting agents discover them at runtime. ## Exit Codes | Code | Meaning | |------|---------| | 0 | Success | | 2 | Usage error (wrong arguments) | | 3 | Resource not found | | 5 | API error (upstream issue) | | 7 | Rate limited (wait and retry) | | 10 | Config error | ## Argument Parsing Parse `$ARGUMENTS`: 1. **Empty, `help`, or `--help`** → show `istat-pp-cli --help` output 2. **Starts with `install`** → ends with `mcp` → MCP installation; otherwise → see Prerequisites above 3. **Anything else** → Direct Use (execute as CLI command with `--agent`) ## MCP Server Installation 1. Install the MCP server: ```bash go install github.com/mvanhorn/printing-press-library/library/developer-tools/istat/cmd/istat-pp-mcp@latest ``` 2. Register with Claude Code: ```bash claude mcp add istat-pp-mcp -- istat-pp-mcp ``` 3. Verify: `claude mcp list` ## Direct Use 1. Check if installed: `which istat-pp-cli` If not found, offer to install (see Prerequisites at the top of this skill). 2. Match the user query to the best command from the Unique Capabilities and Command Reference above. 3. Execute with the `--agent` flag: ```bash istat-pp-cli <command> [subcommand] [args] --agent ``` 4. If ambiguous, drill into subcommand help: `istat-pp-cli <command> --help`.