README.md

June 17, 2026 · View on GitHub

metabase-axi

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 in plans/. Built with specops.

Install

npm install -g metabase-axi      # or: bun add -g metabase-axi

Setup

metabase-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.

Commands

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.

Roadmap

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.

Development

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 source