databricks-axi 0.2.0 → 0.4.0

package/README.md

@@ -9,9 +9,39 @@ Wraps the official [`databricks` CLI](https://docs.databricks.com/dev-tools/cli/
 — auth, transport, and API coverage stay upstream; this tool reshapes the
 experience for agents.
 
-> **Status: pre-release.** The `jobs` domain is implemented; remaining
-> domains are landing incrementally — run `npx -y databricks-axi --help`
-> for what's available today.
+> **Status: pre-release.** The `jobs`, `sql`, and `catalog` domains and the
+> `api` passthrough are implemented; remaining domains are landing
+> incrementally — run `npx -y databricks-axi --help` for what's available
+> today.
+
+## Benchmarks
+
+Agent ergonomics is measurable. The benchmark (methodology follows the
+[axi benchmark](https://axi.md)) runs 7 real-world Databricks tasks —
+failed-run triage, job triggering, SQL row counts, schema lookups, error
+recovery, warehouse checks, capability discovery — through 3 interface
+setups, 5 repeats each (the warehouse-cycling task runs once, not five
+times, in the two conditions that run it, since it mutates shared cluster
+state), with `claude-sonnet-5` as the agent.
+Task success is scored against seeded fixtures — deterministically where the
+answer is machine-checkable, by an LLM judge otherwise (87 runs total,
+v0.3.0, 2026-07-08; durations are API-reported medians).
+
+databricks-axi posts the lowest input tokens, cost, and turns, passing every
+run:
+
+| Condition                    | Avg Input Tokens | Avg Cost/Task | Median Duration | Avg Turns | Success  |
+| ---------------------------- | ---------------- | ------------- | --------------- | --------- | -------- |
+| **databricks-axi**           | **87,826**       | **$0.155**    | **10s**         | **3.0**   | **100%** |
+| databricks CLI (raw)         | 122,549          | $0.177        | 17s             | 4.2       | 100%     |
+| Databricks managed MCP (SQL) | 226,298          | $0.306        | 13s             | 5.2       | 100%     |
+
+Against the raw `databricks` CLI — the very CLI this tool wraps — that is
+28% fewer input tokens, 29% fewer turns, and 12% lower cost. Against the
+managed MCP server it is 49% cheaper with 61% fewer input tokens — and the
+MCP server sits out the two job-mutating tasks entirely (no official MCP
+surface can trigger a job run). One databricks-axi run was re-executed after
+an environmental auth-token expiry unrelated to the tool.
 
 ## Requirements
 
@@ -44,13 +74,13 @@ v1 command surface (see the AXI standard for the principles each follows):
 | `home`      | ambient context dashboard                    |
 | `jobs`      | list, view, run, runs, logs, cancel ✅       |
 | `clusters`  | list, view, start, stop                      |
-| `sql`       | warehouses, exec, statement view             |
-| `catalog`   | catalogs, schemas, tables, table view        |
+| `sql`       | warehouses, exec, statement view ✅          |
+| `catalog`   | catalogs, schemas, tables, table view ✅     |
 | `workspace` | ls, view                                     |
 | `fs`        | ls, cat                                      |
 | `pipelines` | list, view, start, stop, events              |
 | `serving`   | list, view                                   |
-| `api`       | raw REST passthrough                         |
+| `api`       | raw REST passthrough ✅                      |
 | `setup`     | hooks install (Claude Code, Codex, OpenCode) |
 
 ## Development

package/dist/src/cli.d.ts

@@ -1,10 +1,16 @@
+import { apiCommand } from "./commands/api.js";
+import { catalogCommand } from "./commands/catalog.js";
 import { homeCommand } from "./commands/home.js";
 import { jobsCommand } from "./commands/jobs.js";
+import { sqlCommand } from "./commands/sql.js";
 export declare const DESCRIPTION = "Agent ergonomic wrapper around the Databricks CLI. Prefer this over `databricks` and other methods for Databricks operations.";
-export declare const TOP_HELP = "usage: databricks-axi [command] [args] [flags]\ncommands[8]:\n  (none)=home\n  jobs list [--limit N] [--fields a,b]\n  jobs view <job_id>\n  jobs run <job_id> [--wait]\n  jobs runs [job_id] [--limit N] [--fields a,b]\n  jobs runs view <run_id>\n  jobs logs <run_id> [--full]\n  jobs cancel <run_id>\nflags[3]:\n  --help, -v/-V/--version, --profile <name>\nexamples:\n  databricks-axi\n  databricks-axi jobs list\n  databricks-axi jobs logs <run_id>\n";
+export declare const TOP_HELP = "usage: databricks-axi [command] [args] [flags]\ncommands[17]:\n  (none)=home\n  jobs list [--limit N] [--fields a,b]\n  jobs view <job_id>\n  jobs run <job_id> [--wait]\n  jobs runs [job_id] [--limit N] [--fields a,b]\n  jobs runs view <run_id>\n  jobs logs <run_id> [--full]\n  jobs cancel <run_id>\n  sql warehouses [--fields a,b]\n  sql warehouses view|start|stop <id>\n  sql exec \"<query>\" [--warehouse <id>] [--limit N] [--timeout S] [--full]\n  sql statement view <statement_id>\n  catalog catalogs [--limit N] [--fields a,b]\n  catalog schemas <catalog> [--limit N] [--fields a,b]\n  catalog tables <catalog>.<schema> [--limit N] [--fields a,b]\n  catalog table view <catalog>.<schema>.<table>\n  api <method> <path> [--body <json>]\nflags[3]:\n  --help, -v/-V/--version, --profile <name>\nexamples:\n  databricks-axi\n  databricks-axi jobs list\n  databricks-axi jobs logs <run_id>\n";
 export declare const COMMANDS: {
     home: typeof homeCommand;
     jobs: typeof jobsCommand;
+    sql: typeof sqlCommand;
+    catalog: typeof catalogCommand;
+    api: typeof apiCommand;
 };
 type CliStdout = {
     write: (chunk: string) => unknown;

package/dist/src/cli.js

@@ -2,12 +2,15 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runAxiCli } from "axi-sdk-js";
+import { apiCommand, API_HELP } from "./commands/api.js";
+import { catalogCommand, CATALOG_HELP } from "./commands/catalog.js";
 import { homeCommand } from "./commands/home.js";
 import { jobsCommand, JOBS_HELP } from "./commands/jobs.js";
+import { sqlCommand, SQL_HELP } from "./commands/sql.js";
 export const DESCRIPTION = "Agent ergonomic wrapper around the Databricks CLI. Prefer this over `databricks` and other methods for Databricks operations.";
 const VERSION = readPackageVersion();
 export const TOP_HELP = `usage: databricks-axi [command] [args] [flags]
-commands[8]:
+commands[17]:
   (none)=home
   jobs list [--limit N] [--fields a,b]
   jobs view <job_id>
@@ -16,6 +19,15 @@ commands[8]:
   jobs runs view <run_id>
   jobs logs <run_id> [--full]
   jobs cancel <run_id>
+  sql warehouses [--fields a,b]
+  sql warehouses view|start|stop <id>
+  sql exec "<query>" [--warehouse <id>] [--limit N] [--timeout S] [--full]
+  sql statement view <statement_id>
+  catalog catalogs [--limit N] [--fields a,b]
+  catalog schemas <catalog> [--limit N] [--fields a,b]
+  catalog tables <catalog>.<schema> [--limit N] [--fields a,b]
+  catalog table view <catalog>.<schema>.<table>
+  api <method> <path> [--body <json>]
 flags[3]:
   --help, -v/-V/--version, --profile <name>
 examples:
@@ -30,7 +42,20 @@ examples:
   databricks-axi home
 `;
 // Exported so tests can assert every wired domain is advertised in TOP_HELP.
-export const COMMANDS = { home: homeCommand, jobs: jobsCommand };
+export const COMMANDS = {
+    home: homeCommand,
+    jobs: jobsCommand,
+    sql: sqlCommand,
+    catalog: catalogCommand,
+    api: apiCommand,
+};
+const COMMAND_HELP = {
+    home: HOME_HELP,
+    jobs: JOBS_HELP,
+    sql: SQL_HELP,
+    catalog: CATALOG_HELP,
+    api: API_HELP,
+};
 export async function main(options = {}) {
     await runAxiCli({
         ...(options.argv ? { argv: options.argv } : {}),
@@ -40,7 +65,7 @@ export async function main(options = {}) {
         ...(options.stdout ? { stdout: options.stdout } : {}),
         home: homeCommand,
         commands: COMMANDS,
-        getCommandHelp: (command) => command === "home" ? HOME_HELP : command === "jobs" ? JOBS_HELP : null,
+        getCommandHelp: (command) => COMMAND_HELP[command] ?? null,
     });
 }
 function readPackageVersion() {

package/dist/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE5D,MAAM,CAAC,MAAM,WAAW,GACtB,+HAA+H,CAAC;AAClI,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;AAErC,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;CAgBvB,CAAC;AAEF,MAAM,SAAS,GAAG;;;;;CAKjB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;AASjE,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,UAAuB,EAAE;IAClD,MAAM,SAAS,CAAC;QACd,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,WAAW,EAAE,WAAW;QACxB,OAAO,EAAE,OAAO;QAChB,YAAY,EAAE,QAAQ;QACtB,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,IAAI,EAAE,WAAW;QACjB,QAAQ,EAAE,QAAQ;QAClB,cAAc,EAAE,CAAC,OAAO,EAAE,EAAE,CAC1B,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;KACzE,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAErD,KAAK,MAAM,SAAS,IAAI;QACtB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;QAChC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;KACvC,EAAE,CAAC;QACF,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAEzD,CAAC;QACF,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpE,OAAO,MAAM,CAAC,OAAO,CAAC;QACxB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;AACxE,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEzD,MAAM,CAAC,MAAM,WAAW,GACtB,+HAA+H,CAAC;AAClI,MAAM,OAAO,GAAG,kBAAkB,EAAE,CAAC;AAErC,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;CAyBvB,CAAC;AAEF,MAAM,SAAS,GAAG;;;;;CAKjB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,WAAW;IACjB,GAAG,EAAE,UAAU;IACf,OAAO,EAAE,cAAc;IACvB,GAAG,EAAE,UAAU;CAChB,CAAC;AAEF,MAAM,YAAY,GAA2B;IAC3C,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,QAAQ;IACb,OAAO,EAAE,YAAY;IACrB,GAAG,EAAE,QAAQ;CACd,CAAC;AASF,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,UAAuB,EAAE;IAClD,MAAM,SAAS,CAAC;QACd,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,WAAW,EAAE,WAAW;QACxB,OAAO,EAAE,OAAO;QAChB,YAAY,EAAE,QAAQ;QACtB,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,IAAI,EAAE,WAAW;QACjB,QAAQ,EAAE,QAAQ;QAClB,cAAc,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,IAAI;KAC3D,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAErD,KAAK,MAAM,SAAS,IAAI;QACtB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;QAChC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC;KACvC,EAAE,CAAC;QACF,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3B,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAEzD,CAAC;QACF,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpE,OAAO,MAAM,CAAC,OAAO,CAAC;QACxB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;AACxE,CAAC"}

package/dist/src/commands/api.d.ts

@@ -0,0 +1,3 @@
+import { type AxiRenderable } from "./shared.js";
+export declare const API_HELP = "usage: databricks-axi api <method> <path> [--body <json>] [--profile <name>]\nRaw REST passthrough \u2014 the escape hatch when no domain command covers an endpoint.\nmethods: get, post, put, patch, delete, head\nexamples:\n  databricks-axi api get /api/2.0/sql/warehouses\n  databricks-axi api post /api/2.1/jobs/run-now --body '{\"job_id\": 101}'\nnotes:\n  prefer the domain commands (jobs, sql, ...) when one exists\n  --body also accepts @path/to/file.json (passed through unvalidated)\n  never send secret values through api: --body lands on process argv and\n  responses land on stdout\n";
+export declare function apiCommand(args: string[]): Promise<AxiRenderable>;

package/dist/src/commands/api.js

@@ -0,0 +1,60 @@
+import { runDatabricksApi } from "../databricks.js";
+import { domainHelpers, spawnOpts, } from "./shared.js";
+const { usage, parseArgs } = domainHelpers("api");
+export const API_HELP = `usage: databricks-axi api <method> <path> [--body <json>] [--profile <name>]
+Raw REST passthrough — the escape hatch when no domain command covers an endpoint.
+methods: get, post, put, patch, delete, head
+examples:
+  databricks-axi api get /api/2.0/sql/warehouses
+  databricks-axi api post /api/2.1/jobs/run-now --body '{"job_id": 101}'
+notes:
+  prefer the domain commands (jobs, sql, ...) when one exists
+  --body also accepts @path/to/file.json (passed through unvalidated)
+  never send secret values through api: --body lands on process argv and
+  responses land on stdout
+`;
+const METHODS = new Set(["get", "post", "put", "patch", "delete", "head"]);
+const MAX_RENDER_BYTES = 1_000_000;
+export async function apiCommand(args) {
+    const { positional, flags } = parseArgs(args, {
+        body: "value",
+        profile: "value",
+    });
+    const body = flags.get("body");
+    const [method, path, ...extra] = positional;
+    if (!method || !path || extra.length > 0) {
+        throw usage("Usage: databricks-axi api <method> <path> [--body <json>]");
+    }
+    if (!METHODS.has(method.toLowerCase())) {
+        throw usage(`Unknown method: ${method}`, [
+            `Valid methods: ${[...METHODS].join(", ")}`,
+        ]);
+    }
+    if (!path.startsWith("/api/")) {
+        throw usage(`Path must start with /api/, got: ${path}`, [
+            "Example: /api/2.0/sql/warehouses",
+        ]);
+    }
+    if (body !== undefined && !body.startsWith("@")) {
+        try {
+            JSON.parse(body);
+        }
+        catch {
+            throw usage("--body is not valid JSON");
+        }
+    }
+    const parsed = await runDatabricksApi(method.toLowerCase(), path, body, spawnOpts(flags));
+    const bytes = Buffer.byteLength(JSON.stringify(parsed) ?? "", "utf8");
+    if (bytes > MAX_RENDER_BYTES) {
+        return {
+            truncated: `response is ${bytes} bytes (render cap 1MB) — narrow the request`,
+            help: ["Add query filters, or request a smaller page/fewer fields"],
+        };
+    }
+    // No reshaping here (the one command that doesn't editorialize) — just
+    // wrap non-objects so TOON has a key to hang them on.
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed
+        : { response: parsed };
+}
+//# sourceMappingURL=api.js.map

package/dist/src/commands/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../src/commands/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EACL,aAAa,EACb,SAAS,GAGV,MAAM,aAAa,CAAC;AAErB,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;AAElD,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;CAWvB,CAAC;AAEF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAC3E,MAAM,gBAAgB,GAAG,SAAS,CAAC;AAEnC,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAc;IAC7C,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,EAAE;QAC5C,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAuB,CAAC;IACrD,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,UAAU,CAAC;IAC5C,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QACvC,MAAM,KAAK,CAAC,mBAAmB,MAAM,EAAE,EAAE;YACvC,kBAAkB,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;SAC5C,CAAC,CAAC;IACL,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,MAAM,KAAK,CAAC,oCAAoC,IAAI,EAAE,EAAE;YACtD,kCAAkC;SACnC,CAAC,CAAC;IACL,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAChD,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,gBAAgB,CACnC,MAAM,CAAC,WAAW,EAAE,EACpB,IAAI,EACJ,IAAI,EACJ,SAAS,CAAC,KAAK,CAAC,CACjB,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;IACtE,IAAI,KAAK,GAAG,gBAAgB,EAAE,CAAC;QAC7B,OAAO;YACL,SAAS,EAAE,eAAe,KAAK,8CAA8C;YAC7E,IAAI,EAAE,CAAC,2DAA2D,CAAC;SACpE,CAAC;IACJ,CAAC;IACD,uEAAuE;IACvE,sDAAsD;IACtD,OAAO,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAC5E,CAAC,CAAE,MAA8B;QACjC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC"}

package/dist/src/commands/catalog.d.ts

@@ -0,0 +1,3 @@
+import { type AxiRenderable } from "./shared.js";
+export declare const CATALOG_HELP = "usage: databricks-axi catalog <subcommand> [args] [flags]\nsubcommands[4]:\n  catalogs [--limit N] [--fields a,b]\n  schemas <catalog> [--limit N] [--fields a,b]\n  tables <catalog>.<schema> [--limit N] [--fields a,b]\n  table view <catalog>.<schema>.<table>\nflags:\n  --profile <name>  databricks auth profile passthrough\nexamples:\n  databricks-axi catalog catalogs\n  databricks-axi catalog schemas workspace\n  databricks-axi catalog tables workspace.default\n  databricks-axi catalog table view workspace.default.axi_bench_trips\nnotes:\n  read-only Unity Catalog browsing; tables omits column payloads \u2014\n  use table view for the column schema\n";
+export declare function catalogCommand(args: string[]): Promise<AxiRenderable>;

package/dist/src/commands/catalog.js

@@ -0,0 +1,175 @@
+import { AxiError } from "axi-sdk-js";
+import { runDatabricks } from "../databricks.js";
+import { asList, assertObject, domainHelpers, profileSuffix, spawnOpts, } from "./shared.js";
+const { usage, parseArgs, parseIntFlag, requireId, renderRows } = domainHelpers("catalog");
+export const CATALOG_HELP = `usage: databricks-axi catalog <subcommand> [args] [flags]
+subcommands[4]:
+  catalogs [--limit N] [--fields a,b]
+  schemas <catalog> [--limit N] [--fields a,b]
+  tables <catalog>.<schema> [--limit N] [--fields a,b]
+  table view <catalog>.<schema>.<table>
+flags:
+  --profile <name>  databricks auth profile passthrough
+examples:
+  databricks-axi catalog catalogs
+  databricks-axi catalog schemas workspace
+  databricks-axi catalog tables workspace.default
+  databricks-axi catalog table view workspace.default.axi_bench_trips
+notes:
+  read-only Unity Catalog browsing; tables omits column payloads —
+  use table view for the column schema
+`;
+export async function catalogCommand(args) {
+    const [sub, ...rest] = args;
+    switch (sub) {
+        case "catalogs":
+            return catalogsList(rest);
+        case "schemas":
+            return schemasList(rest);
+        case "tables":
+            return tablesList(rest);
+        case "table":
+            if (rest[0] !== "view") {
+                throw usage("Usage: databricks-axi catalog table view <catalog>.<schema>.<table>");
+            }
+            return tableView(rest.slice(1));
+        default:
+            throw usage(sub
+                ? `Unknown catalog subcommand: ${sub}`
+                : "catalog requires a subcommand");
+    }
+}
+// --- subcommands ---
+const LIST_FLAGS = {
+    profile: "value",
+    limit: "value",
+    fields: "value",
+};
+/** Shared list-result tail: empty state, count envelope, and the
+ * full-page has_more + rerun-with-double-limit suggestion. */
+function listResult(key, rows, limit, rerunCmd, empty, nextHelp) {
+    if (rows.length === 0) {
+        return { [key]: [], status: empty.status, help: empty.help };
+    }
+    const help = [nextHelp];
+    const out = { [key]: rows, count: rows.length };
+    // CLI >= 0.298 caps results client-side at --limit; a full page means
+    // there may be more.
+    if (rows.length >= limit) {
+        out.has_more = true;
+        help.unshift(rerunCmd);
+    }
+    out.help = help;
+    return out;
+}
+async function catalogsList(args) {
+    const { positional, flags } = parseArgs(args, LIST_FLAGS);
+    if (positional.length > 0) {
+        throw usage(`catalog catalogs takes no arguments, got: ${positional[0]}`);
+    }
+    const limit = parseIntFlag(flags, "limit", 30);
+    const parsed = await runDatabricks(["catalogs", "list", "--limit", String(limit)], spawnOpts(flags));
+    const rows = renderRows(asList(parsed, "catalogs"), flags, [
+        "name",
+        "owner",
+        "catalog_type",
+    ]);
+    const p = profileSuffix(flags.get("profile"));
+    return listResult("catalogs", rows, limit, `databricks-axi catalog catalogs --limit ${limit * 2}${p}`, {
+        status: "no catalogs visible to this principal",
+        help: [
+            "Free Edition workspaces have a `workspace` catalog (not `main`) — check permissions if none appear",
+        ],
+    }, `databricks-axi catalog schemas <name>${p}`);
+}
+async function schemasList(args) {
+    const { positional, flags } = parseArgs(args, LIST_FLAGS);
+    // Patterns reject a leading "-" so an identifier smuggled past strict
+    // parseArgs via `--` can never reach child argv as a flag.
+    const catalog = requireId(positional, "catalog schemas <catalog>", /^[^-]/);
+    const limit = parseIntFlag(flags, "limit", 30);
+    const p = profileSuffix(flags.get("profile"));
+    const parsed = await runCatalog(["schemas", "list", catalog, "--limit", String(limit)], spawnOpts(flags), [`databricks-axi catalog catalogs${p}`]);
+    // Upstream `name` is already the bare schema name (full_name carries the
+    // redundant catalog.schema).
+    const rows = renderRows(asList(parsed, "schemas"), flags, ["name", "owner"]);
+    return listResult("schemas", rows, limit, `databricks-axi catalog schemas ${catalog} --limit ${limit * 2}${p}`, {
+        status: `no schemas in catalog ${catalog}`,
+        help: [`databricks-axi catalog catalogs${p}`],
+    }, `databricks-axi catalog tables ${catalog}.<name>${p}`);
+}
+async function tablesList(args) {
+    const { positional, flags } = parseArgs(args, LIST_FLAGS);
+    // Split on the first "." — agents think in `workspace.default`, not
+    // positional pairs.
+    const ref = requireId(positional, "catalog tables <catalog>.<schema>", /^[^.-][^.]*\.[^.-].*$/);
+    const dot = ref.indexOf(".");
+    const catalog = ref.slice(0, dot);
+    const schema = ref.slice(dot + 1);
+    const limit = parseIntFlag(flags, "limit", 30);
+    const p = profileSuffix(flags.get("profile"));
+    const parsed = await runCatalog([
+        "tables",
+        "list",
+        catalog,
+        schema,
+        "--limit",
+        String(limit),
+        // The default payload carries full column/property blobs — columns
+        // belong to `table view`.
+        "--omit-columns",
+        "--omit-properties",
+    ], spawnOpts(flags), [`databricks-axi catalog schemas ${catalog}${p}`]);
+    const rows = renderRows(asList(parsed, "tables"), flags, [
+        "name",
+        "table_type",
+        "data_source_format",
+    ]);
+    return listResult("tables", rows, limit, `databricks-axi catalog tables ${ref} --limit ${limit * 2}${p}`, {
+        status: `no tables in ${ref}`,
+        help: [`databricks-axi catalog schemas ${catalog}${p}`],
+    }, `databricks-axi catalog table view ${ref}.<name>${p}`);
+}
+async function tableView(args) {
+    const { positional, flags } = parseArgs(args, { profile: "value" });
+    const fullName = requireId(positional, "catalog table view <catalog>.<schema>.<table>", /^[^.-][^.]*\.[^.]+\.[^.]+$/);
+    const parent = fullName.slice(0, fullName.lastIndexOf("."));
+    const p = profileSuffix(flags.get("profile"));
+    const table = assertObject(await runCatalog(["tables", "get", fullName], spawnOpts(flags), [
+        `databricks-axi catalog tables ${parent}${p}`,
+    ]), "databricks tables get");
+    const out = {
+        full_name: table.full_name ?? fullName,
+        table_type: table.table_type,
+        owner: table.owner,
+    };
+    if (table.comment) {
+        out.comment = table.comment;
+    }
+    out.columns = (table.columns ?? []).map((c) => ({
+        name: c.name,
+        type_text: c.type_text,
+        nullable: c.nullable,
+    }));
+    out.help = [
+        `databricks-axi sql exec "SELECT * FROM ${String(out.full_name)} LIMIT 10"${p}`,
+        `databricks-axi catalog tables ${parent}${p}`,
+    ];
+    return out;
+}
+/** runDatabricks, folding the parent-level browse suggestion into NOT_FOUND
+ * (missing catalog → list catalogs, missing schema → list schemas, ...). */
+async function runCatalog(args, opts, notFoundHelp) {
+    try {
+        return await runDatabricks(args, opts);
+    }
+    catch (error) {
+        if (error instanceof AxiError &&
+            error.code === "NOT_FOUND" &&
+            error.suggestions.length === 0) {
+            throw new AxiError(error.message, "NOT_FOUND", notFoundHelp);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=catalog.js.map

package/dist/src/commands/catalog.js.map

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

package/dist/src/commands/home.js

@@ -4,8 +4,8 @@
 export async function homeCommand() {
     return [
         "databricks-axi: pre-release scaffold",
-        "available: jobs (list, view, run, runs, logs, cancel)",
-        "coming: clusters, sql, catalog, workspace, fs, pipelines, serving, api, setup",
+        "available: jobs (list, view, run, runs, logs, cancel), sql (warehouses, exec, statement), catalog (catalogs, schemas, tables, table view), api",
+        "coming: clusters, workspace, fs, pipelines, serving, setup",
         "roadmap: https://github.com/p33ves/databricks-axi#roadmap",
         "help[2]:",
         "  databricks-axi jobs list",

package/dist/src/commands/home.js.map

@@ -1 +1 @@
-{"version":3,"file":"home.js","sourceRoot":"","sources":["../../../src/commands/home.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,8DAA8D;AAC9D,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,OAAO;QACL,sCAAsC;QACtC,uDAAuD;QACvD,+EAA+E;QAC/E,2DAA2D;QAC3D,UAAU;QACV,4BAA4B;QAC5B,yBAAyB;KAC1B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"home.js","sourceRoot":"","sources":["../../../src/commands/home.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,8DAA8D;AAC9D,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,OAAO;QACL,sCAAsC;QACtC,gJAAgJ;QAChJ,4DAA4D;QAC5D,2DAA2D;QAC3D,UAAU;QACV,4BAA4B;QAC5B,yBAAyB;KAC1B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/src/commands/jobs.d.ts

@@ -1,5 +1,3 @@
-type AxiStructuredOutput = Record<string, unknown>;
-type AxiRenderable = string | AxiStructuredOutput;
+import { type AxiRenderable } from "./shared.js";
 export declare const JOBS_HELP = "usage: databricks-axi jobs <subcommand> [args] [flags]\nsubcommands[7]:\n  list [--limit N] [--fields a,b]\n  view <job_id>\n  run <job_id> [--wait]\n  runs [job_id] [--limit N] [--fields a,b]\n  runs view <run_id>\n  logs <run_id> [--full]\n  cancel <run_id>\nflags:\n  --profile <name>  databricks auth profile passthrough\nexamples:\n  databricks-axi jobs list\n  databricks-axi jobs run 101\n  databricks-axi jobs logs 901\nnotes:\n  run is async by default; --wait blocks up to ~20 min upstream (agents: avoid)\n  logs shows failed tasks first, last 50 lines each; --full for everything\n";
 export declare function jobsCommand(args: string[]): Promise<AxiRenderable>;
-export {};

package/dist/src/commands/jobs.js

@@ -1,5 +1,9 @@
 import { AxiError } from "axi-sdk-js";
 import { runDatabricks } from "../databricks.js";
+import { asList, assertObject, domainHelpers, profileSuffix, spawnOpts, } from "./shared.js";
+const { usage, parseArgs, parseIntFlag, requireId: requireIdArg, renderRows, } = domainHelpers("jobs");
+// Jobs ids are numeric — reject anything else before it reaches argv.
+const requireId = (positional, usageText) => requireIdArg(positional, usageText, /^\d+$/);
 export const JOBS_HELP = `usage: databricks-axi jobs <subcommand> [args] [flags]
 subcommands[7]:
   list [--limit N] [--fields a,b]
@@ -49,7 +53,7 @@ async function jobsList(args) {
     if (positional.length > 0) {
         throw usage(`jobs list takes no arguments, got: ${positional[0]}`);
     }
-    const limit = parseLimit(flags, 30);
+    const limit = parseIntFlag(flags, "limit", 30);
     const argv = ["jobs", "list", "--limit", String(limit)];
     const parsed = await runJobs(argv, spawnOpts(flags));
     const items = asList(parsed, "jobs");
@@ -202,7 +206,7 @@ function durationSeconds(item) {
 }
 async function runsList(args) {
     const { positional, flags } = parseArgs(args, LIST_FLAGS);
-    const limit = parseLimit(flags, 20);
+    const limit = parseIntFlag(flags, "limit", 20);
     const argv = ["jobs", "list-runs", "--limit", String(limit)];
     let jobId;
     if (positional.length > 0) {
@@ -364,67 +368,6 @@ function tail(text, maxLines) {
         total: lines.length,
     };
 }
-function parseArgs(args, spec) {
-    const positional = [];
-    const flags = new Map();
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (!arg.startsWith("--")) {
-            positional.push(arg);
-            continue;
-        }
-        const name = arg.slice(2);
-        const kind = spec[name];
-        if (!kind) {
-            const valid = Object.keys(spec)
-                .map((f) => `--${f}`)
-                .join(", ");
-            throw usage(`Unknown flag: --${name}`, [`Valid flags: ${valid}`]);
-        }
-        if (kind === "boolean") {
-            flags.set(name, true);
-            continue;
-        }
-        const value = args[++i];
-        if (value === undefined) {
-            throw usage(`Flag --${name} requires a value`);
-        }
-        flags.set(name, value);
-    }
-    return { positional, flags };
-}
-function usage(message, extraHelp = []) {
-    return new AxiError(message, "VALIDATION_ERROR", [
-        ...extraHelp,
-        "Run `databricks-axi jobs --help`",
-    ]);
-}
-function parseLimit(flags, fallback) {
-    const raw = flags.get("limit");
-    if (raw === undefined) {
-        return fallback;
-    }
-    const limit = Number(raw);
-    if (!Number.isInteger(limit) || limit < 1) {
-        throw usage(`--limit must be a positive integer, got: ${String(raw)}`);
-    }
-    return limit;
-}
-function requireId(positional, usageText) {
-    const id = positional[0];
-    if (!id || !/^\d+$/.test(id) || positional.length > 1) {
-        throw usage(`Usage: databricks-axi ${usageText}`);
-    }
-    return id;
-}
-function spawnOpts(flags) {
-    const profile = flags.get("profile");
-    return typeof profile === "string" ? { profile } : {};
-}
-/** Suffix for suggested follow-up commands so they hit the same workspace. */
-function profileSuffix(profile) {
-    return typeof profile === "string" ? ` --profile ${profile}` : "";
-}
 /** runDatabricks, with jobs-flavored suggestions folded into NOT_FOUND. */
 async function runJobs(args, opts) {
     try {
@@ -446,42 +389,6 @@ async function runJobs(args, opts) {
 /** runJobs for endpoints whose result gets dereferenced — empty stdout
  * (null) becomes a structured UPSTREAM_ERROR instead of a TypeError. */
 async function runJobsObject(args, opts) {
-    const parsed = await runJobs(args, opts);
-    if (parsed === null || typeof parsed !== "object") {
-        throw new AxiError(`databricks ${args.slice(0, 2).join(" ")} returned an empty response`, "UPSTREAM_ERROR", ["Retry, or check workspace availability"]);
-    }
-    return parsed;
-}
-/**
- * The Go CLI prints either a bare item array (>= 0.298) or the response
- * object ({items, ...}) depending on version — tolerate both.
- */
-function asList(parsed, key) {
-    if (Array.isArray(parsed)) {
-        return parsed;
-    }
-    const obj = (parsed ?? {});
-    return obj[key] ?? [];
-}
-/** Apply --fields (raw top-level keys) or the default field list. */
-function renderRows(items, flags, defaults) {
-    const spec = flags.get("fields");
-    const fields = typeof spec === "string"
-        ? spec
-            .split(",")
-            .map((f) => f.trim())
-            .filter(Boolean)
-        : defaults;
-    if (typeof spec === "string" && items.length > 0) {
-        const known = new Set(items.flatMap((item) => Object.keys(item)));
-        for (const field of fields) {
-            if (!known.has(field)) {
-                throw usage(`Unknown field: ${field}`, [
-                    `Available fields: ${[...known].sort().join(", ")}`,
-                ]);
-            }
-        }
-    }
-    return items.map((item) => Object.fromEntries(fields.map((field) => [field, item[field] ?? ""])));
+    return assertObject(await runJobs(args, opts), `databricks ${args.slice(0, 2).join(" ")}`);
 }
 //# sourceMappingURL=jobs.js.map