@pgsage/cli 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# @pgsage/cli
+
+Command-line interface for pgsage. Wraps `@pgsage/core` and formats results for terminal output.
+
+---
+
+## Usage
+
+```sh
+pgsage query <question> [options]
+```
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Output the full response as JSON | — |
+| `--sql` | Output only the generated SQL | — |
+| `--raw` | Output result rows as a JSON array | — |
+| `--model <m>` | Planner/explainer model | `anthropic/claude-sonnet-4-6` |
+| `--top-k <n>` | Schema chunks to retrieve | `10` |
+| `--row-limit <n>` | Maximum rows to return | `500` |
+| `-v, --version` | Show version | — |
+| `-h, --help` | Show help | — |
+
+---
+
+## Examples
+
+```sh
+# Simple lookup — default table output
+pgsage query "What is the median household income in Providence County, RI?"
+
+# Ranking
+pgsage query "Top 10 counties by total population"
+
+# Cross-category filter
+pgsage query "Counties with median income above \$100k and homeownership below 60%"
+
+# Ambiguous question — surfaces planner assumptions
+pgsage query "Where do rich people live?"
+
+# Pipe SQL to psql
+pgsage query "Top 5 states by Gini index" --sql | psql $DATABASE_URL
+
+# Parse rows with jq
+pgsage query "Median rent in California counties" --raw | jq '.[0]'
+
+# Full structured response
+pgsage query "Which state has the lowest poverty rate?" --json | jq '.answer'
+```
+
+---
+
+## Output Formats
+
+| Flag | What you get |
+|------|-------------|
+| _(default)_ | Coloured table with answer, assumptions, SQL, and row data |
+| `--json` | Complete `QueryResponse` as pretty-printed JSON |
+| `--sql` | Just the generated SQL — pipe-friendly |
+| `--raw` | Result rows as a JSON array — jq-friendly |
+
+---
+
+## Environment
+
+Reads from `.env` at the repo root via `--env-file=../../.env` (set in the binary wrapper). Required variables:
+
+```sh
+DATABASE_URL=postgres://...
+DATABASE_READONLY_URL=postgres://...
+ANTHROPIC_API_KEY=sk-ant-...
+VOYAGE_API_KEY=pa-...
+```
+
+---
+
+## Testing
+
+```sh
+pnpm --filter @pgsage/cli test
+```
+
+16 unit tests covering all four formatters (`formatTable`, `formatJson`, `formatSql`, `formatRaw`).

package/dist/config.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CLI configuration loader.
+ *
+ * Reads connection strings and API keys from environment variables,
+ * constructs pg pools and a VoyageEmbeddingProvider, and returns a
+ * ready-to-use OrchestratorConfig.
+ *
+ * Environment variables:
+ *   DATABASE_URL          — required. read-write connection string.
+ *   DATABASE_READONLY_URL — optional. read-only connection string.
+ *                           Falls back to DATABASE_URL if not set.
+ *   VOYAGE_API_KEY        — required. Voyage AI API key.
+ *   ANTHROPIC_API_KEY     — required. Anthropic API key (read by Mastra).
+ */
+import { type OrchestratorConfig } from "@pgsage/core";
+export interface CliConfig {
+    agentConfig: OrchestratorConfig;
+    /** Close both pools when done. */
+    cleanup: () => Promise<void>;
+}
+export interface CliOptions {
+    model?: string;
+    topK?: number;
+    rowLimit?: number;
+}
+/**
+ * Load CLI configuration from environment variables.
+ * Throws with a human-readable message if a required variable is missing.
+ */
+export declare function loadConfig(options?: CliOptions): CliConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,kBAAkB,CAAC;IAChC,kCAAkC;IAClC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,UAAe,GAAG,SAAS,CAyB9D"}

package/dist/config.js

@@ -0,0 +1,49 @@
+/**
+ * CLI configuration loader.
+ *
+ * Reads connection strings and API keys from environment variables,
+ * constructs pg pools and a VoyageEmbeddingProvider, and returns a
+ * ready-to-use OrchestratorConfig.
+ *
+ * Environment variables:
+ *   DATABASE_URL          — required. read-write connection string.
+ *   DATABASE_READONLY_URL — optional. read-only connection string.
+ *                           Falls back to DATABASE_URL if not set.
+ *   VOYAGE_API_KEY        — required. Voyage AI API key.
+ *   ANTHROPIC_API_KEY     — required. Anthropic API key (read by Mastra).
+ */
+import { createPool, createReadonlyPool, VoyageEmbeddingProvider, } from "@pgsage/core";
+/**
+ * Load CLI configuration from environment variables.
+ * Throws with a human-readable message if a required variable is missing.
+ */
+export function loadConfig(options = {}) {
+    const databaseUrl = requireEnv("DATABASE_URL");
+    const readonlyUrl = process.env["DATABASE_READONLY_URL"] ?? databaseUrl;
+    const voyageApiKey = requireEnv("VOYAGE_API_KEY");
+    requireEnv("ANTHROPIC_API_KEY"); // validated here; Mastra reads it from env
+    const pool = createPool(databaseUrl, { max: 3 });
+    const readonlyPool = createReadonlyPool(readonlyUrl, { max: 3 });
+    const embedder = new VoyageEmbeddingProvider({ apiKey: voyageApiKey });
+    const agentConfig = {
+        pool,
+        readonlyPool,
+        embedder,
+        model: options.model,
+        topK: options.topK,
+        rowLimit: options.rowLimit,
+    };
+    const cleanup = async () => {
+        await Promise.allSettled([pool.end(), readonlyPool.end()]);
+    };
+    return { agentConfig, cleanup };
+}
+function requireEnv(name) {
+    const val = process.env[name];
+    if (!val) {
+        throw new Error(`Missing required environment variable: ${name}\n` +
+            `Set it in your shell or in a .env file and use --env-file.`);
+    }
+    return val;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,uBAAuB,GAExB,MAAM,cAAc,CAAC;AActB;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,UAAsB,EAAE;IACjD,MAAM,WAAW,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,IAAI,WAAW,CAAC;IACxE,MAAM,YAAY,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAClD,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,2CAA2C;IAE5E,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IACjD,MAAM,YAAY,GAAG,kBAAkB,CAAC,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAEjE,MAAM,QAAQ,GAAG,IAAI,uBAAuB,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;IAEvE,MAAM,WAAW,GAAuB;QACtC,IAAI;QACJ,YAAY;QACZ,QAAQ;QACR,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC;IAEF,MAAM,OAAO,GAAG,KAAK,IAAmB,EAAE;QACxC,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,YAAY,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC7D,CAAC,CAAC;IAEF,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AAClC,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,0CAA0C,IAAI,IAAI;YAChD,4DAA4D,CAC/D,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/format.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Output formatters for the pgsage CLI.
+ *
+ * Four output modes:
+ *   table    — default. coloured table with assumptions + SQL footer.
+ *   json     — full QueryResponse serialised as pretty-printed JSON.
+ *   sql      — only the generated SQL, suitable for piping to psql.
+ *   raw      — rows as a JSON array, suitable for jq.
+ */
+import type { QueryResponse } from "@pgsage/core";
+export declare function formatTable(response: QueryResponse): string;
+export declare function formatJson(response: QueryResponse): string;
+export declare function formatSql(response: QueryResponse): string;
+export declare function formatRaw(response: QueryResponse): string;
+export declare function formatError(message: string): string;
+/**
+ * Writes a status message to stderr (so it doesn't pollute stdout piped output).
+ * Returns a stop function that clears the line.
+ */
+export declare function startSpinner(message: string): () => void;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAoBlD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAiE3D;AAoCD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAE1D;AAMD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAEzD;AAMD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAEzD;AAMD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,IAAI,CAmBxD"}

package/dist/format.js

@@ -0,0 +1,153 @@
+/**
+ * Output formatters for the pgsage CLI.
+ *
+ * Four output modes:
+ *   table    — default. coloured table with assumptions + SQL footer.
+ *   json     — full QueryResponse serialised as pretty-printed JSON.
+ *   sql      — only the generated SQL, suitable for piping to psql.
+ *   raw      — rows as a JSON array, suitable for jq.
+ */
+import chalk from "chalk";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Safely stringify any primitive DB value without triggering no-base-to-string. */
+function primitiveString(val) {
+    if (val === null || val === undefined)
+        return "";
+    if (typeof val === "string")
+        return val;
+    if (typeof val === "number" || typeof val === "boolean" || typeof val === "bigint") {
+        return String(val);
+    }
+    return JSON.stringify(val);
+}
+// ---------------------------------------------------------------------------
+// Table output (default)
+// ---------------------------------------------------------------------------
+export function formatTable(response) {
+    const lines = [];
+    if (response.rowCount === 0) {
+        lines.push(chalk.yellow("  No results returned."));
+        appendFooter(lines, response);
+        return lines.join("\n");
+    }
+    // Build column widths
+    const fields = response.fields.length > 0
+        ? response.fields
+        : Object.keys(response.rows[0] ?? {});
+    const widths = fields.map((f) => f.length);
+    for (const row of response.rows) {
+        fields.forEach((f, i) => {
+            const val = primitiveString(row[f]);
+            if (val.length > widths[i])
+                widths[i] = val.length;
+        });
+    }
+    // Cap column widths at 40 chars for readability
+    const cappedWidths = widths.map((w) => Math.min(w, 40));
+    const sep = "─".repeat(cappedWidths.reduce((s, w) => s + w + 3, 1));
+    // Header
+    lines.push(chalk.dim("  " + sep));
+    const headerCells = fields
+        .map((f, i) => chalk.bold(f.padEnd(cappedWidths[i])))
+        .join(chalk.dim(" │ "));
+    lines.push(chalk.dim("  │ ") + headerCells + chalk.dim(" │"));
+    lines.push(chalk.dim("  " + sep));
+    // Rows
+    for (const row of response.rows) {
+        const cells = fields
+            .map((f, i) => {
+            const cellVal = row[f];
+            const val = cellVal === null || cellVal === undefined
+                ? chalk.dim("null")
+                : primitiveString(cellVal);
+            const truncated = val.length > 40 ? val.slice(0, 37) + "..." : val;
+            return truncated.padEnd(cappedWidths[i]);
+        })
+            .join(chalk.dim(" │ "));
+        lines.push(chalk.dim("  │ ") + cells + chalk.dim(" │"));
+    }
+    lines.push(chalk.dim("  " + sep));
+    // Row count / truncation notice
+    if (response.truncated) {
+        lines.push(chalk.yellow(`\n  Showing first ${response.rowCount} rows (result truncated — increase --row-limit to see more).`));
+    }
+    else {
+        lines.push(chalk.dim(`\n  ${response.rowCount} row${response.rowCount === 1 ? "" : "s"}`));
+    }
+    appendFooter(lines, response);
+    return lines.join("\n");
+}
+function appendFooter(lines, response) {
+    // Assumptions
+    if (response.assumptions.length > 0) {
+        lines.push("");
+        lines.push(chalk.cyan("  Assumptions:"));
+        for (const a of response.assumptions) {
+            lines.push(chalk.dim("  · ") + a);
+        }
+    }
+    // Self-correction notice
+    if (response.attempts.length > 0) {
+        lines.push("");
+        lines.push(chalk.dim(`  (Self-corrected after ${response.attempts.length} failed attempt${response.attempts.length === 1 ? "" : "s"}.)`));
+    }
+    // SQL
+    lines.push("");
+    lines.push(chalk.cyan("  SQL:"));
+    const indented = response.sql
+        .split("\n")
+        .map((l) => chalk.dim("  ") + chalk.green(l))
+        .join("\n");
+    lines.push(indented);
+}
+// ---------------------------------------------------------------------------
+// JSON output
+// ---------------------------------------------------------------------------
+export function formatJson(response) {
+    return JSON.stringify(response, null, 2);
+}
+// ---------------------------------------------------------------------------
+// SQL-only output
+// ---------------------------------------------------------------------------
+export function formatSql(response) {
+    return response.sql;
+}
+// ---------------------------------------------------------------------------
+// Raw rows output (JSON array)
+// ---------------------------------------------------------------------------
+export function formatRaw(response) {
+    return JSON.stringify(response.rows, null, 2);
+}
+// ---------------------------------------------------------------------------
+// Error output
+// ---------------------------------------------------------------------------
+export function formatError(message) {
+    return chalk.red("  Error: ") + message;
+}
+// ---------------------------------------------------------------------------
+// Spinner helpers (simple dots — no ora dependency)
+// ---------------------------------------------------------------------------
+/**
+ * Writes a status message to stderr (so it doesn't pollute stdout piped output).
+ * Returns a stop function that clears the line.
+ */
+export function startSpinner(message) {
+    const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    let i = 0;
+    const isTTY = process.stderr.isTTY;
+    if (!isTTY) {
+        process.stderr.write(message + "\n");
+        return () => { };
+    }
+    const timer = setInterval(() => {
+        process.stderr.write(`\r${chalk.cyan(frames[i % frames.length])} ${message}`);
+        i++;
+    }, 80);
+    return () => {
+        clearInterval(timer);
+        process.stderr.write("\r\x1b[K"); // clear line
+    };
+}
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * pgsage CLI — thin wrapper over the @pgsage/core SDK.
+ *
+ * Usage:
+ *   pgsage query "What is the median household income in Rhode Island?"
+ *   pgsage query "Top 10 counties by population" --json
+ *   pgsage query "Show unemployment in Wayne County, MI" --sql
+ *   pgsage query "Counties with high income and low homeownership" --raw
+ *
+ * Environment variables (set in shell or .env file):
+ *   DATABASE_URL          — required
+ *   DATABASE_READONLY_URL — optional (falls back to DATABASE_URL)
+ *   VOYAGE_API_KEY        — required
+ *   ANTHROPIC_API_KEY     — required
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG"}

package/dist/index.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * pgsage CLI — thin wrapper over the @pgsage/core SDK.
+ *
+ * Usage:
+ *   pgsage query "What is the median household income in Rhode Island?"
+ *   pgsage query "Top 10 counties by population" --json
+ *   pgsage query "Show unemployment in Wayne County, MI" --sql
+ *   pgsage query "Counties with high income and low homeownership" --raw
+ *
+ * Environment variables (set in shell or .env file):
+ *   DATABASE_URL          — required
+ *   DATABASE_READONLY_URL — optional (falls back to DATABASE_URL)
+ *   VOYAGE_API_KEY        — required
+ *   ANTHROPIC_API_KEY     — required
+ */
+import { Command } from "commander";
+import chalk from "chalk";
+import { createAgent } from "@pgsage/core";
+import { loadConfig } from "./config.js";
+import { formatTable, formatJson, formatSql, formatRaw, formatError, startSpinner, } from "./format.js";
+// ---------------------------------------------------------------------------
+// Version (read from package.json at startup)
+// ---------------------------------------------------------------------------
+// Using a hardcoded version avoids needing JSON import assertions,
+// which have inconsistent support across Node/TS versions.
+const VERSION = "0.1.0";
+// ---------------------------------------------------------------------------
+// Program definition
+// ---------------------------------------------------------------------------
+const program = new Command();
+program
+    .name("pgsage")
+    .description("Schema-aware SQL agent — ask natural-language questions against your Postgres database.")
+    .version(VERSION, "-v, --version");
+program
+    .command("query <question>")
+    .description("Ask a natural-language question and get SQL results.")
+    .option("--json", "Output the full response as JSON (overrides other format flags)")
+    .option("--sql", "Output only the generated SQL — no execution, no results")
+    .option("--raw", "Output result rows as a JSON array")
+    .option("--model <model>", "Planner model to use (default: anthropic/claude-sonnet-4-6)")
+    .option("--top-k <n>", "Number of schema chunks to retrieve (default: 10)", parseInt)
+    .option("--row-limit <n>", "Maximum rows to return (default: 500)", parseInt)
+    .action(async (question, opts) => {
+    let cleanup;
+    try {
+        // Load config (validates env vars)
+        const config = loadConfig({
+            model: opts.model,
+            topK: opts.topK,
+            rowLimit: opts.rowLimit,
+        });
+        cleanup = config.cleanup;
+        // If --sql flag: plan only, don't execute
+        if (opts.sql) {
+            const stop = startSpinner("Planning query…");
+            try {
+                const agent = createAgent(config.agentConfig);
+                // We can't get SQL-only from the current agent interface (it always
+                // executes), so we run the full query but only print the SQL.
+                const response = await agent.query(question);
+                stop();
+                process.stdout.write(formatSql(response) + "\n");
+            }
+            catch (err) {
+                stop();
+                throw err;
+            }
+            return;
+        }
+        // Full query
+        const stop = startSpinner("Thinking…");
+        try {
+            const agent = createAgent(config.agentConfig);
+            const response = await agent.query(question);
+            stop();
+            if (opts.json) {
+                process.stdout.write(formatJson(response) + "\n");
+            }
+            else if (opts.raw) {
+                process.stdout.write(formatRaw(response) + "\n");
+            }
+            else {
+                process.stdout.write("\n" + formatTable(response) + "\n\n");
+            }
+        }
+        catch (err) {
+            stop();
+            throw err;
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(formatError(message) + "\n");
+        process.exitCode = 1;
+    }
+    finally {
+        await cleanup?.();
+    }
+});
+// ---------------------------------------------------------------------------
+// Help output styling
+// ---------------------------------------------------------------------------
+program.addHelpText("after", `
+${chalk.bold("Examples:")}
+  ${chalk.dim("$")} pgsage query "What is the median household income in Providence County, RI?"
+  ${chalk.dim("$")} pgsage query "Top 10 counties by population" --json
+  ${chalk.dim("$")} pgsage query "Show unemployment in Wayne County, Michigan" --sql
+  ${chalk.dim("$")} pgsage query "Counties with income above $100k and homeownership below 60%" --raw
+
+${chalk.bold("Environment variables:")}
+  DATABASE_URL           Read-write Postgres connection string (required)
+  DATABASE_READONLY_URL  Read-only connection string (optional, falls back to DATABASE_URL)
+  VOYAGE_API_KEY         Voyage AI API key (required)
+  ANTHROPIC_API_KEY      Anthropic API key (required)
+
+${chalk.bold("Tip:")}
+  Put your env vars in a .env file and run with:
+  ${chalk.dim("$")} node --env-file=.env $(which pgsage) query "..."
+`);
+// ---------------------------------------------------------------------------
+// Parse and run
+// ---------------------------------------------------------------------------
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@pgsage/cli",
+  "version": "0.1.0",
+  "description": "CLI wrapper for the pgsage SDK: npx pgsage query \"...\"",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "pgsage": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hownowbrowncow/pgsage.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/hownowbrowncow/pgsage/tree/main/packages/cli",
+  "bugs": "https://github.com/hownowbrowncow/pgsage/issues",
+  "keywords": [
+    "postgres",
+    "sql",
+    "ai",
+    "cli",
+    "pgsage",
+    "natural-language",
+    "text-to-sql"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^6.0.0",
+    "commander": "^15.0.0",
+    "pg": "8.23.0",
+    "@pgsage/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.2.0",
+    "@types/pg": "8.23.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.11"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests"
+  }
+}