Metabase CLI

The Metabase CLI (mb) is a command-line client for Metabase. mb logs in to a Metabase instance and lets you or an AI agent read and write content over the Metabase API: questions, dashboards, collections, transforms, and more.

Looking for the commands built into the Metabase JAR, like migrate or load-from-h2? Check out Metabase JAR commands.

Requirements

• Node.js 20.6 or later, to install the CLI from npm.
• A Metabase instance on version 58 or later. Some command groups need a newer Metabase (for example, browser login needs version 63). The CLI tells you when that’s the case.
• A Pro or Enterprise plan for some command groups. For example, git-sync needs the premium Remote sync feature.

Install the CLI

npm install -g @metabase/cli

The binary is mb.

For commands, run:

mb --help

To update to the latest version later, run mb upgrade.

Authenticate the CLI

Log in once per Metabase instance:

mb auth login --url https://metabase.example.com

The CLI offers to open Metabase in your browser. Sign in with your password or SSO and approve the CLI. The CLI stores a token that refreshes itself, so you never paste a secret. If you’d rather use an API key, pick With an API key at the prompt. If the MB_API_KEY environment variable is set, the CLI uses that key and skips the browser. This MB_API_KEY is read from the machine running the CLI. It’s unrelated to the MB_API_KEY environment variable you can set on your Metabase server, which only guards the /api/notify endpoints.

On Metabase versions before 63, the CLI skips the browser and asks for an API key.

Log in without a prompt

To log in from a script or CI, give the CLI an API key without putting the key on the command line. There are two ways to do that.

Set the MB_API_KEY environment variable (for example, from your CI provider’s secret store) and run:

mb auth login --url https://metabase.example.com --profile default

Or pipe the key on stdin from a file or a secrets manager:

mb auth login --url https://metabase.example.com --profile default < api-key.txt

In both cases, include --profile (or set MB_PROFILE), naming the profile whatever you like. Without it, the CLI still asks for a profile name when run from a terminal, even though it already has the key.

The key must be a Metabase API key. If stdin isn’t a terminal and no key arrives from the flag, stdin, or the environment variable, the CLI stops with “interactive login requires a TTY” rather than prompting.

Check your login status or log out

To see whether you’re logged in, which login method you used, and which Metabase version you’re talking to, run:

mb auth status

To remove stored credentials, run mb auth logout.

Manage more than one Metabase with profiles

Credentials are stored per profile, so you can manage more than one Metabase (like dev and prod Metabases):

mb auth login --profile prod --url https://prod.example.com
mb auth list

Add --profile <name> (or -p <name>) to any command to run it against that instance.

The CLI stores secrets in your operating system’s keychain when it can. Otherwise it warns you and stores them in a plaintext profiles.json file.

Use the CLI with an AI agent

The CLI is built to be driven by an AI coding agent like Claude Code. Instead of running commands yourself, you install a skill and describe what you want in plain language; the agent works out the commands.

The metabase-cli skill

The CLI ships with its own agent skills, so the instructions your agent reads always match the version of the CLI it’s running. The metabase-cli skill you install tells the agent to load those bundled skills with mb skills get.

You can install the skill:

• From the Metabase agent skills repo: npx skills add metabase/agent-skills --skill metabase-cli -a claude-code
• As a Claude Code plugin: /plugin marketplace add metabase/mb-cli, then /plugin install metabase-cli@metabase

Once installed, you can run:

/metabase-cli Create a dashboard summarizing this month's signups by plan.

And your agent will go to work, creating content directly in your Metabase via the mb CLI.

Use the CLI for agent-driven development

Pair the CLI with version control to build content with an agent in a development Metabase, commit the changes, and pull the changes into your production Metabase. Check out Agent-driven development.

Further reading

• Metabase CLI command reference
• CLI analytics
• @metabase/cli on npm
• Agent-driven development
• Agent skills
• Remote sync
• Serialization
• Metabase JAR commands