pilot-protocol · Alexgodoroja · Jul 15, 2026
@@ -46,31 +46,31 @@
   "methods": [
     {
       "name": "duckdb.query",
-      "summary": "Run a SQL statement (or `;`-separated batch) and return an aligned `box` table — the default, human-readable shape. Works in-memory (`database=\":memory:\"`) or against a DuckDB file, and can query CSV/Parquet/JSON files in place, e.g. `SELECT region, sum(amount) FROM '/data/*.parquet' GROUP BY region`. This is `duckdb \u003cdatabase\u003e -box -c \u003csql\u003e`."
+      "summary": "Run a SQL statement (or `;`-separated batch) and return an aligned `box` table — the default, human-readable shape. Works in-memory (`database=\":memory:\"`) or against a DuckDB file, and can query CSV/Parquet/JSON files in place, e.g. `SELECT region, sum(amount) FROM '/data/*.parquet' GROUP BY region`. This is `duckdb <database> -box -c <sql>`."
     },
     {
       "name": "duckdb.query_csv",
-      "summary": "Same as duckdb.query but returns the result set as CSV (header + rows) — the right shape when an agent needs to parse the output. This is `duckdb \u003cdatabase\u003e -csv -c \u003csql\u003e`."
+      "summary": "Same as duckdb.query but returns the result set as CSV (header + rows) — the right shape when an agent needs to parse the output. This is `duckdb <database> -csv -c <sql>`."
     },
     {
       "name": "duckdb.query_json",
-      "summary": "Run SQL and return the result set as a JSON array of row objects — the most directly machine-parseable output. This is `duckdb \u003cdatabase\u003e -json -c \u003csql\u003e`."
+      "summary": "Run SQL and return the result set as a JSON array of row objects — the most directly machine-parseable output. This is `duckdb <database> -json -c <sql>`."
     },
     {
       "name": "duckdb.query_markdown",
-      "summary": "Run SQL and return the result set as a GitHub-flavored Markdown table — handy when the output is going straight into a report or PR comment. This is `duckdb \u003cdatabase\u003e -markdown -c \u003csql\u003e`."
+      "summary": "Run SQL and return the result set as a GitHub-flavored Markdown table — handy when the output is going straight into a report or PR comment. This is `duckdb <database> -markdown -c <sql>`."
     },
     {
       "name": "duckdb.file",
-      "summary": "Execute a `.sql` script file against the database and exit — for multi-statement setups, migrations, or ETL scripts the agent has written to disk. This is `duckdb \u003cdatabase\u003e -f \u003cfile\u003e`."
+      "summary": "Execute a `.sql` script file against the database and exit — for multi-statement setups, migrations, or ETL scripts the agent has written to disk. This is `duckdb <database> -f <file>`."
     },
     {
       "name": "duckdb.tables",
-      "summary": "List every table and view across all attached databases/schemas (name, database, schema, column list) as a `box` table — a quick inventory of what a DuckDB file holds. This is `duckdb \u003cdatabase\u003e -box -c \"SHOW ALL TABLES\"`."
+      "summary": "List every table and view across all attached databases/schemas (name, database, schema, column list) as a `box` table — a quick inventory of what a DuckDB file holds. This is `duckdb <database> -box -c \"SHOW ALL TABLES\"`."
     },
     {
       "name": "duckdb.schema",
-      "summary": "Print the `CREATE` statements for every table, view, and index in the database — the DDL, via DuckDB's `.schema` meta-command. This is `duckdb \u003cdatabase\u003e -no-stdin -cmd \".schema\"`."
+      "summary": "Print the `CREATE` statements for every table, view, and index in the database — the DDL, via DuckDB's `.schema` meta-command. This is `duckdb <database> -no-stdin -cmd \".schema\"`."
     },
     {
       "name": "duckdb.exec",
@@ -106,5 +106,51 @@
       "label": "Website",
       "url": "https://duckdb.org"
     }
-  ]
+  ],
+  "product_demo": {
+    "skill": "io.pilot.duckdb",
+    "title": "Full usage demo",
+    "when_to_use": "When you need an in-process OLAP/SQL engine to query CSV, Parquet or JSON files and crunch analytics locally with zero server — not for concurrent writes or a long-lived shared database.",
+    "metered": false,
+    "quickstart": {
+      "goal": "Run your first query (no provisioning — in-memory)",
+      "command": "pilotctl appstore call io.pilot.duckdb duckdb.query '{\"database\":\":memory:\",\"sql\":\"SELECT 42 AS answer\"}'",
+      "expect": "an aligned box table with one column `answer` and value 42"
+    },
+    "examples": [
+      {
+        "title": "Aggregate a CSV file in place — no import step",
+        "goal": "Group and count straight over a file on disk",
+        "command": "pilotctl appstore call io.pilot.duckdb duckdb.query_json '{\"database\":\":memory:\",\"sql\":\"SELECT country, count(*) AS n FROM read_csv_auto('/data/users.csv') GROUP BY 1 ORDER BY n DESC\"}'",
+        "expect": "JSON array of row objects, e.g. [{\"country\":\"US\",\"n\":120},{\"country\":\"DE\",\"n\":44}]"
+      },
+      {
+        "title": "Create and populate a persistent table",
+        "goal": "Persist data to a .duckdb file on disk",
+        "command": "pilotctl appstore call io.pilot.duckdb duckdb.query '{\"database\":\"/work/sales.duckdb\",\"sql\":\"CREATE TABLE IF NOT EXISTS sales(id INT, amt DECIMAL); INSERT INTO sales VALUES (1,9.99),(2,4.50); SELECT sum(amt) AS total FROM sales\"}'",
+        "expect": "box table with total = 14.49; the sales table survives in /work/sales.duckdb"
+      },
+      {
+        "title": "Read a Parquet file as Markdown",
+        "goal": "Preview columnar data formatted for a report",
+        "command": "pilotctl appstore call io.pilot.duckdb duckdb.query_markdown '{\"database\":\":memory:\",\"sql\":\"SELECT * FROM read_parquet('/data/events.parquet') LIMIT 5\"}'",
+        "expect": "a GitHub-flavored Markdown table of the first 5 rows"
+      },
+      {
+        "title": "List tables in a database",
+        "goal": "See what exists before querying",
+        "command": "pilotctl appstore call io.pilot.duckdb duckdb.tables '{\"database\":\"/work/sales.duckdb\"}'",
+        "expect": "one row per table/view: name, database, schema"
+      }
+    ],
+    "gotchas": [
+      "File paths (read_csv_auto, read_parquet, .duckdb files) resolve inside the app sandbox, not your shell CWD.",
+      "`database` is required on every query — use \":memory:\" for throwaway work or an absolute .duckdb path to persist.",
+      ":memory: databases vanish when the call returns; nothing is saved.",
+      "Single-writer engine: great for analytics, not for many concurrent writers."
+    ],
+    "next": [
+      "io.pilot.duckdb duckdb.help '{}'"
+    ]
+  }
 }
@@ -276,45 +276,6 @@
       "metadata_sha256": "059a5e2b7d3d9d7fa72da563c68d90c242d20ca0cd4e7329a7dc5eb5326e142b",
       "publisher": "ed25519:N1uQkAJ355xY9RSj5Q8/y9Y+PIIjLzPB47PAl1vdw2U="
     },
-    {
-      "id": "io.pilot.duckdb",
-      "version": "1.5.4",
-      "description": "DuckDB 1.5.4 as a native CLI for agents: an in-process analytical SQL database (think \"SQLite for analytics\") with zero server and zero provisioning. Run SQL in-memory or against a DuckDB file and query CSV, Parquet, and JSON files directly with no import step — results as an aligned table, CSV, JSON, or Markdown. Schema/table introspection, run a .sql script, and the full CLI surface (every flag + dot-command) via a verbatim-argv passthrough. Ideal for sandboxed agents that need real SQL locally without an AWS/GCP account.",
-      "display_name": "DuckDB",
-      "vendor": "Pilot Protocol",
-      "license": "MIT",
-      "source_url": "https://github.com/duckdb/duckdb",
-      "bundle_url": "https://pub-f09f9a4ea848491198d48e329ba030e3.r2.dev/bundles/io.pilot.duckdb/1.5.4/io.pilot.duckdb-1.5.4-linux-amd64.tar.gz",
-      "bundle_sha256": "faf00a9211ede5cbe50884e522a472aab76ec7812cf8c6c3c39589f4f7f65a4c",
-      "bundle_size": 5353407,
-      "bundles": {
-        "darwin/arm64": {
-          "bundle_url": "https://pub-f09f9a4ea848491198d48e329ba030e3.r2.dev/bundles/io.pilot.duckdb/1.5.4/io.pilot.duckdb-1.5.4-darwin-arm64.tar.gz",
-          "bundle_sha256": "ae8b1a9f524cecd8d7b942af058dbc7cdd737ff29de7186bad6faff2a6b4940d"
-        },
-        "darwin/amd64": {
-          "bundle_url": "https://pub-f09f9a4ea848491198d48e329ba030e3.r2.dev/bundles/io.pilot.duckdb/1.5.4/io.pilot.duckdb-1.5.4-darwin-amd64.tar.gz",
-          "bundle_sha256": "5825add7eb960111464eca50752b7edc2f658d26cdd51187d7e08a43364c9a62"
-        },
-        "linux/amd64": {
-          "bundle_url": "https://pub-f09f9a4ea848491198d48e329ba030e3.r2.dev/bundles/io.pilot.duckdb/1.5.4/io.pilot.duckdb-1.5.4-linux-amd64.tar.gz",
-          "bundle_sha256": "faf00a9211ede5cbe50884e522a472aab76ec7812cf8c6c3c39589f4f7f65a4c"
-        },
-        "linux/arm64": {
-          "bundle_url": "https://pub-f09f9a4ea848491198d48e329ba030e3.r2.dev/bundles/io.pilot.duckdb/1.5.4/io.pilot.duckdb-1.5.4-linux-arm64.tar.gz",
-          "bundle_sha256": "54471ec4cf95071bba8d3c6f9e2dc134483df47ceaef291b5e6adea6bc89b31d"
-        }
-      },
-      "categories": [
-        "database",
-        "data",
-        "sql",
-        "analytics"
-      ],
-      "metadata_url": "https://raw.githubusercontent.com/pilot-protocol/pilotprotocol/main/catalogue/apps/io.pilot.duckdb/metadata.json",
-      "metadata_sha256": "88700d57d93c9260bf358cd2c7bf79aebdc88cabedd00f2cbe2b1b599f03e38f",
-      "publisher": "ed25519:goaIo9+EvuMcRZnkum08HY83QScUWLRtqe0KG/uGljs="
-    },
     {
       "id": "io.pilot.docker",
       "version": "29.6.1",
@@ -776,6 +737,40 @@
         }
       },
       "publisher": "ed25519:BAsg7bdd2t0V9tFCkXRCWRgIdEuuWtJVEjjZp8HBgEg="
+    },
+    {
+      "id": "io.pilot.duckdb",
+      "version": "1.5.4",
+      "description": "DuckDB 1.5.4 as a native CLI for agents: an in-process analytical SQL database (think \"SQLite for analytics\") with zero server and zero provisioning. Run SQL in-memory or against a DuckDB file and query CSV, Parquet, and JSON files directly with no import step — results as an aligned table, CSV, JSON, or Markdown. Schema/table introspection, run a .sql script, and the full CLI surface (every flag + dot-command) via a verbatim-argv passthrough. Ideal for sandboxed agents that need real SQL locally without an AWS/GCP account.",
+      "bundle_url": "https://pub-f09f9a4ea848491198d48e329ba030e3.r2.dev/bundles/io.pilot.duckdb/1.5.4/io.pilot.duckdb-1.5.4-linux-amd64.tar.gz",
+      "bundle_sha256": "faf00a9211ede5cbe50884e522a472aab76ec7812cf8c6c3c39589f4f7f65a4c",
+      "display_name": "Duckdb",
+      "vendor": "Pilot Protocol",
+      "categories": [],
+      "bundle_size": 5353407,
+      "source_url": "https://github.com/pilot-protocol/app-template/tree/main/submissions/io.pilot.duckdb",
+      "license": "",
+      "metadata_url": "https://raw.githubusercontent.com/pilot-protocol/pilotprotocol/main/catalogue/apps/io.pilot.duckdb/metadata.json",
+      "metadata_sha256": "b89ad3120e03fe29dc69799a3b00015c0bcb2abb98de1c893872e2033e723cf1",
+      "bundles": {
+        "linux/amd64": {
+          "bundle_url": "https://pub-f09f9a4ea848491198d48e329ba030e3.r2.dev/bundles/io.pilot.duckdb/1.5.4/io.pilot.duckdb-1.5.4-linux-amd64.tar.gz",
+          "bundle_sha256": "faf00a9211ede5cbe50884e522a472aab76ec7812cf8c6c3c39589f4f7f65a4c"
+        },
+        "linux/arm64": {
+          "bundle_url": "https://pub-f09f9a4ea848491198d48e329ba030e3.r2.dev/bundles/io.pilot.duckdb/1.5.4/io.pilot.duckdb-1.5.4-linux-arm64.tar.gz",
+          "bundle_sha256": "54471ec4cf95071bba8d3c6f9e2dc134483df47ceaef291b5e6adea6bc89b31d"
+        },
+        "darwin/amd64": {
+          "bundle_url": "https://pub-f09f9a4ea848491198d48e329ba030e3.r2.dev/bundles/io.pilot.duckdb/1.5.4/io.pilot.duckdb-1.5.4-darwin-amd64.tar.gz",
+          "bundle_sha256": "5825add7eb960111464eca50752b7edc2f658d26cdd51187d7e08a43364c9a62"
+        },
+        "darwin/arm64": {
+          "bundle_url": "https://pub-f09f9a4ea848491198d48e329ba030e3.r2.dev/bundles/io.pilot.duckdb/1.5.4/io.pilot.duckdb-1.5.4-darwin-arm64.tar.gz",
+          "bundle_sha256": "ae8b1a9f524cecd8d7b942af058dbc7cdd737ff29de7186bad6faff2a6b4940d"
+        }
+      },
+      "publisher": "ed25519:goaIo9+EvuMcRZnkum08HY83QScUWLRtqe0KG/uGljs="
     }
   ]
 }
@@ -1 +1 @@
-IcWEYl+PRCPCU/osMH3fk+Xop6Hax+htirANCxPmpBcldHjWJwrnTZjBNy5/ueJEvLERAwFBuVrMvcIAv0QXCg==
+Hp4JONIzV0LOB0+J6wZYUmL+a1v87lumO1Mb7GXYyuY5qz57Ag/3BNzPkr47WuZqPRlHzNXpbMTpOtjVTGfIAg==
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		IcWEYl+PRCPCU/osMH3fk+Xop6Hax+htirANCxPmpBcldHjWJwrnTZjBNy5/ueJEvLERAwFBuVrMvcIAv0QXCg==
		Hp4JONIzV0LOB0+J6wZYUmL+a1v87lumO1Mb7GXYyuY5qz57Ag/3BNzPkr47WuZqPRlHzNXpbMTpOtjVTGfIAg==