metabase-cli
Command-line client for Metabase. Logs in to an instance in your browser (OAuth, Metabase v62+) or with an API key, and stores credentials securely on your machine.
Supported Metabase versions
The minimum supported server is Metabase v0.58 (major 58). Anything older is unsupported.
Commands that need more than a baseline OSS server declare it — a higher minimum major version or a premium token feature. The server version and token features are detected and cached when you run mb auth login (or mb auth list). For those commands, a preflight check runs before the first request and refuses with an actionable message (exit code 2) when:
- the server is older than the command's minimum version, or
- the command needs a premium feature (e.g.
remote_sync, transforms) that isn't enabled.
Plain OSS commands against a v0.58+ server (the majority) carry no elevated requirement and skip the preflight entirely. When a gated command runs but the server version can't be detected (no cached probe), it proceeds with a warning rather than refusing. To bypass the check for a single run, pass --skip-preflight; to bypass it process-wide (e.g. in CI), set METABASE_CLI_SKIP_PREFLIGHT=1. Both are footguns — only for servers you know are patched.
Install
npm install -g @metabase/cli
mb --help
Or build from source:
bun install
bun run build
node dist/cli.mjs --help
The binary is mb. Examples below use that name.
Quick start
mb auth login --url https://metabase.example.com
mb auth status
Authentication
Credentials are stored per-profile. The default profile is named default. Use --profile <name> to manage additional profiles.
mb auth login
Log in to a Metabase instance and save the credential to a profile. Interactive login offers two methods:
- In your browser (recommended; requires Metabase v62 or newer) — the CLI opens Metabase, you sign in with your password or SSO and approve the CLI, and a short-lived access token plus a rotating refresh token are stored. Tokens refresh automatically; you never paste a secret.
- With an API key — paste a key from Admin settings → Authentication → API keys.
Against a server older than v62 the CLI detects the missing OAuth support and falls back to the API key prompt automatically. Supplying an API key (flag, env, or stdin) always skips the browser flow, so CI and scripts behave exactly as before.
On success the server is probed once — the rendered output shows the user, role (Admin/User), and Metabase version, and the same values are cached in <configDir>/profiles.json so later commands skip re-probing. Failure of either the auth probe (/api/user/current) or the server probe (/api/session/properties) rejects the login; an existing profile keeps its last-known-good credential and gains a lastFailure entry.
| Flag | Description |
|---|
--url <url> | Metabase URL, including any subpath if the instance is hosted under one (https://my.org.com/metabase). Falls back to METABASE_URL, then prompts. |
--api-key <value> | API key. Skips the browser flow. Visible in shell history — pipe on stdin instead. |
--client-id <id> | Pre-registered OAuth client id (only needed when dynamic client registration is disabled on the server). |
--profile <name>, -p | Profile to write to (default: default). |
--skip-verify | Save without contacting the server (no probe, no cache). |
Non-interactive (non-TTY) login requires an API key; resolution order: --api-key → piped stdin → METABASE_API_KEY (first non-empty wins). Without one, non-interactive login fails rather than prompting.
mb auth login # interactive: browser or API key
echo "$MB_KEY" | mb auth login --url https://m.example.com
mb auth login --url https://m.example.com < key.txt
mb auth status
Show whether a profile is authenticated. The output includes the auth method (OAuth or API key) alongside the cached user, role, and server version.
mb auth status
mb auth status --json
mb auth status --profile staging
