metabasecli

Command-line interface for Metabase API operations.

Terminology

• Cards = Questions/Queries in the Metabase UI (metabase cards, metabase queries, metabase questions are aliases)
• Dashboards = Dashboards
• Collections = Collections (folders for organizing cards and dashboards)
• Databases = Connected data sources

Flag Placement

Always place flags after the full command path, not between metabase and the command group. This ensures command prefix matching works correctly for permissions.

# Correct:
metabase databases list --profile prod --json
metabase cards run 123 --limit 100

# Wrong:
metabase -p prod databases list

Global Flags

Flag	Description
-p, --profile	Named profile to use (default: "default")
-v, --verbose	Enable verbose output
--json	JSON output (available on most commands)

JSON Output Format

All commands support --json. Output wraps as:

• Success: {"success": true, "data": {...}, "meta": {"timestamp": "...", "api_calls": N}}
• Error: {"success": false, "error": {"code": "...", "message": "..."}}

Error codes: NOT_FOUND, AUTHENTICATION_ERROR, SESSION_EXPIRED, PERMISSION_DENIED, API_ERROR, VALIDATION_ERROR.

Authentication

metabase auth status            # Check current auth status
metabase auth login              # Interactive login
metabase auth login --url https://metabase.example.com --method api_key
metabase auth token              # Print session token (for piping)
metabase auth logout             # Clear stored session

Search

metabase search "revenue"                              # Search all entities
metabase search "revenue" --models card                # Cards only
metabase search "revenue" --models dashboard           # Dashboards only
metabase search "revenue" --collection-id 42           # Within collection
metabase search "revenue" --database-id 1              # Filter by database
metabase search "revenue" --archived                   # Search archived items
metabase search "revenue" --created-by 5               # By creator user ID
metabase search "revenue" --limit 10                   # Limit results (default 50)

Valid --models values: card, dashboard, collection, database, table, dataset, segment, metric, action.

Resolve URLs

Parse Metabase URLs into entity details:

metabase resolve 'https://metabase.example.com/question/123'
metabase resolve 'https://metabase.example.com/dashboard/456-my-dashboard'
metabase resolve '/collection/789'
metabase resolve '/browse/databases/1'

Databases

metabase databases list                                # List all databases
metabase databases list --include-tables               # Include table info
metabase databases get 1                               # Database details
metabase databases get 1 --include-tables              # With tables
metabase databases get 1 --include-fields              # With tables and fields
metabase databases metadata 1                          # Full metadata (all tables and fields)
metabase databases metadata 1 --include-hidden         # Include hidden tables/fields
metabase databases schemas 1                           # List schemas

Collections

Browse Collections

metabase collections tree                              # Collection hierarchy
metabase collections tree --search "analytics"         # Filter by name
metabase collections tree --search "analytics" -L 3    # Show 3 levels deep (default 1)
metabase collections tree --include-archived           # Include archived
metabase collections get 42                            # Collection details
metabase collections get root                          # Root collection
metabase collections items 42                          # Items in collection
metabase collections items root                        # Items in root
metabase collections items 42 --models card            # Cards only
metabase collections items 42 --models dashboard       # Dashboards only
metabase collections items 42 --archived               # Archived items
metabase collections items 42 --sort-by last_edited_at --sort-dir desc

Valid --models for items: card, dashboard, collection, dataset, pulse. Valid --sort-by: name, last_edited_at, last_edited_by, model.

Manage Collections

metabase collections create --name "My Collection" --parent-id 42
metabase collections create --name "Top Level" --description "A description"
metabase collections update 42 --name "New Name"
metabase collections update 42 --parent-id 10          # Move to different parent
metabase collections archive 42                        # Archive (soft delete)

Cards (Questions/Queries)

Browse Cards

metabase cards list --filter mine                      # My cards
metabase cards list --filter bookmarked                # Bookmarked
metabase cards list --filter archived                  # Archived
metabase cards list --collection-id 42                 # By collection
metabase cards list --filter database --database-id 1  # By database
metabase cards get 123                                 # Full card details with query definition

At least one filter is required: --filter, --collection-id, or --database-id.

Valid --filter: mine, bookmarked, archived, database, table, using_model.

Run Cards

Execute a saved question and get results:

metabase cards run 123                                 # Run card (default limit 2000 rows)
metabase cards run 123 --limit 100                     # Limit rows
metabase cards run 123 --parameters '{"date": "2024-01-01"}'  # With parameters
metabase cards run 123 --json                          # JSON output

Results are exported to /tmp/metabase-<timestamp>/.

Import/Export Cards

metabase cards import --file card.json                 # Create new card from JSON
metabase cards import --file card.json --id 123        # Update existing card
metabase cards import --file card.json --collection-id 42  # Override target collection
metabase cards import --file card.json --database-id 1 # Override target database
cat card.json | metabase cards import --file -          # From stdin

For JSON format details and creating cards from scratch, see references/creating-cards-and-dashboards.md.

Delete Cards

metabase cards archive 123                             # Archive (soft delete)
metabase cards delete 123                              # Permanent delete (with confirmation)
metabase cards delete 123 --force                      # Skip confirmation

Dashboards

Browse Dashboards

metabase dashboards list --collection-id 42            # List in collection (required filter)
metabase dashboards get 456                            # Dashboard with dashcard definitions
metabase dashboards get 456 --include-cards            # Include full card definitions

Export Dashboards

metabase dashboards export 456                         # Export dashboard + all referenced cards

Exports to /tmp/metabase-<timestamp>/ with:

• dashboard-456.json — dashboard layout with dashcard placements (card_id references only)
• card-<id>.json — one per referenced card (full card definition for context)

Import Dashboards

Dashboard import only handles the layout. Cards must already exist — create them first with metabase cards import.

metabase dashboards import --file dashboard.json                  # Create new dashboard
metabase dashboards import --file dashboard.json --id 456         # Update existing
metabase dashboards import --file dashboard.json --collection-id 42  # Override collection
cat dashboard.json | metabase dashboards import --file -          # From stdin

For creating cards and dashboards from scratch, see references/creating-cards-and-dashboards.md.

Revisions

metabase dashboards revisions 456                      # List revisions
metabase dashboards revert 456 789                     # Revert to revision 789

Delete Dashboards

metabase dashboards archive 456                        # Archive (soft delete)
metabase dashboards delete 456                         # Permanent delete (with confirmation)
metabase dashboards delete 456 --force                 # Skip confirmation