An AXI-compliant CLI for Metabase — built for agents.
metabase-axi wraps the Metabase HTTP API in an agent-ergonomic CLI: token-efficient
TOON output, schema introspection so you can write correct
queries, capped result previews with full-data export to a file, and named instance
profiles so you never query the wrong deployment by accident.
It leads with the analyst workflow — run SQL/MBQL, execute saved questions, introspect schema, search content, and browse dashboards/collections from the terminal.
Status: early development (Tier 1 — query & explore — is shipped; see the Roadmap). The spec is the source of truth — see
specs/— and work-in-flight is tracked inplans/. Built with specops.
npm install -g metabase-axi # or: bun add -g metabase-aximetabase-axi auth add prod --url https://metabase.example.org --api-key mb_...Mint an API key in Metabase admin (Settings → API keys). Credentials are stored in
~/.config/metabase-axi/config.json; METABASE_URL + METABASE_API_KEY (or
METABASE_USERNAME/METABASE_PASSWORD) override the file for CI/cron. Verify with
metabase-axi doctor.
| Command | What |
|---|---|
metabase-axi |
Home view: active instance + recent content + suggestions |
metabase-axi query <sql> |
Run native SQL or MBQL; preview + export |
metabase-axi card list|view|run |
List, inspect, and execute saved questions |
metabase-axi db list|schema |
List databases; introspect tables/fields |
metabase-axi search <q> |
Find cards, dashboards, collections, tables |
metabase-axi dashboard list|view |
List and inspect dashboards |
metabase-axi collection list |
Browse the collection tree |
metabase-axi auth|doctor |
Credentials + health |
metabase-axi setup hooks |
Install the SessionStart ambient hook |
Run metabase-axi --help for the full command list, or metabase-axi <command> --help for
any command's usage.
Capability is rolled out in tiers, analyst-first. Reads come before writes by design —
see specs/principles.md.
| Tier | Scope | Status |
|---|---|---|
| 1 — Query & explore | Run SQL/MBQL, execute & inspect saved questions, schema introspection (incl. table/field descriptions), search, browse dashboards & collections, export to file | ✅ Shipped |
| 2 — Authoring | Create & edit cards, dashboards, and collections | 🔜 Planned |
| 3 — Operations | Users, permission groups, settings, instance health/audit | 🔜 Planned |
| 4 — Deferred | Pulses/alerts, public & embed links, comments, timelines, revisions, Enterprise endpoints | ⏳ Later |
All write operations (Tier 2+) mutate a shared, often production instance — they land
deliberately, behind explicit instance selection. See
specs/architecture.md for the full surface.
asdf install # bun + nodejs per .tool-versions
bun install
bun run build # tsc -> dist/
bun run test # vitest
bun run dev -- query "SELECT 1" # run from sourceMIT © Jarvus Innovations