File-based development

Metabase content like questions and dashboards can be serialized as YAML files. You can edit those YAML files directly, but the most productive workflow is to let an agent do the editing for you — this article focuses on that agent-driven workflow.

The file-based toolkit

We provide a set of tools for using an AI agent to create and edit Metabase content serialized as YAML files.

• The Metabase Representation Format. This is a directory that includes a spec, schemas, and examples for all Metabase entities as YAML files: questions, dashboards, and so on.
• The metabase-representation-format agent skill for working with these YAML files.
• CLI commands and API endpoints to export and import content serialized in YAML.
• MCP server to look up database metadata when creating the YAML files.

Prerequisites

Set up a development Metabase

Set up a Metabase instance to check your work before pushing changes to production. This Metabase should connect to the same data warehouse(s) your production Metabase connects to. A config file will come in handy here.

We also recommend turning off the sample content and usage analytics, so they don’t pollute the data model. If you’re using a docker compose file, add these environment variables:

MB_LOAD_SAMPLE_CONTENT: "false"
MB_INSTALL_ANALYTICS_DATABASE: "false"

For agent-driven development

If you want an agent to do the editing, you also need:

1. The metabase-representation-format skill added to your agent so the agent understands the YAML schemas. See Agent skills.

2. Your agent connected to your Metabase’s MCP server, so it can look up database metadata (table names, fields, and sample values) when writing questions and dashboards. The MCP server exposes tools like search, get_table, and get_table_field_values. See MCP server.

Example agent-driven workflow

Here’s an example workflow for using an agent to create Metabase content as YAML on your local machine, then importing that content into your development and production Metabases.

1. Create a git repo

Initialize a git repo with a README.md and an initial commit.

2. Check out a branch

Create a new branch to track your work.

git checkout -b your-branch-name

3. Export your production Metabase

Always export before editing YAML files locally. If someone has updated a dashboard or question in the Metabase UI since your last export, and you edit and import stale local files, the import will overwrite those in-app changes. Re-export at the start of each editing session if the app may have changed since your last export.

Your agent will also read these serialized YAML files to find info about existing content, so the agent can know what you mean when you ask it to “add the new question to the Handsome collection.”

To export your Metabase:

1. Create an API key.
2. Assign the key to the Admin group.

3. Send a curl request to export data:

   curl \
     -H 'X-API-Key: YOUR_API_KEY' \
     -X POST 'https://your-metabase-url/api/ee/serialization/export?data_model=false' \
     -o metabase_data.tgz
   

   substituting YOUR_API_KEY with your API key and your-metabase-url with the URL of your Metabase instance.

   Be sure to set the data_model=false query parameter excludes the data model from the export, since the data model payload can be large. Instead, your agent will use the MCP server to search for the metadata it needs to generate the YAML files. See Serialization for other export options.

   This command will download the files as a GZIP-compressed Tar file named metabase_data.tgz.

4. Extract the archive:

   tar -xzf metabase_data.tgz
   

Instead of running this curl by hand every time, you can ask your agent to generate an export.sh script that wraps the curl and the tar -xzf extraction, so you can re-export with a single command.

4. Commit the export

Commit the initial exported set of YAML files. If your AI goes off the rails, you can always revert to the original export.

5. Use AI to edit or create new content

Change into the directory with your serialized files and ask your agent to create whatever you want. Make sure your agent actually invokes the skills, otherwise the agent may not get the YAML format right.

Example prompt:

Use the metabase-representation-format skill and the Metabase MCP server to do the following by editing the YAML files in this directory:

1. Create a new collection called "File-based collection".
2. Create a new dashboard called "AI-created dashboard", saved to that collection.
3. Create a question called "AI counts products" that counts the number of products by category.
4. Add that question to the "AI-created dashboard".

Depending on how sophisticated your AI model is, you can also try more ambitious, open-ended requests:

Use the metabase-representation-format skill and the Metabase MCP server to analyze the data in the sample postgresql
database. Look at the orders, people, reviews, and products tables.

Create a dashboard with some questions that gives an overview of how the business is doing.

6. Validate the YAML files

Before importing, check your YAML files against the representation schemas. The metabase-representation-format skill should have the agent run the validator for you, but you can also run it yourself:

npx --yes @metabase/representations validate-schema

You can also set up a workflow to run the validator on pull requests. Here’s an example, saved to .github/workflows/schema-check.yml:

name: Schema Check

on:
  push:
    branches: [main]
  pull_request:

jobs:
  schema-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Validate representation YAML files
        run: npx --yes @metabase/representations validate-schema

That way your team catches schema issues on the PR, before anyone imports the changes into Metabase.

7. Import the changes to your development Metabase

Import your changes to your development Metabase, and check that the import works and the content is as expected.

First, compress your directory of YAML files:

tar -czf metabase_data.tgz metabase_data

Then import that compressed file:

curl -X POST \
  -H 'X-API-Key: YOUR_API_KEY' \
  -F 'file=@metabase_data.tgz' \
  'https://your-metabase-url/api/ee/serialization/import' \
  -o -

The -o - flag writes the import response to stdout, so you can see whether the import succeeded and check any warnings.

Just like with export, you can ask your agent to generate an import.sh script that handles the tar -czf compression and the curl in one shot.

Log in to this Metabase and check that the changes are as you expect.

Did your AI go off the rails?

If you want to undo the agent’s changes, use git to revert your YAML files to the last known-good commit. Don’t try to undo the changes by re-exporting from your production Metabase: re-exporting will overwrite edits you made to existing files, but it won’t delete any new files the agent created, so your directory will still contain those unwanted files.

8. Commit your changes

If all looks good, commit your changes. If you get any errors, give the error info to the agent in the same session and the agent should iron out any issues.

9. Import to your production Metabase

Import your changes via the API, push your changes to a remote git repository and set up remote sync so that your production instance pulls in the changes automatically.

Deleting content

Since imports and exports don’t delete content, you’ll need to delete that content in the Metabase application itself, then update the YAML files as well.

1. Delete the content in your production Metabase (in the app’s UI itself).
2. Export from your production Metabase to your repo.
3. Commit the changes so that the YAML files are updated. That way Metabase won’t recreate the deleted items the next time you import your changes.

Further reading

• MCP server
• Serialization
• Agent skills