Chartwright

Chartwright is a command-line tool that manages Apache Superset dashboards as code: one JSON spec file per dashboard, covering its charts and how each is drawn, its filters, layout, text, colours and styling, and naming the datasets it reads. Chartwright creates or updates the dashboard on your Superset instances from the spec, reports where the live dashboard differs from it, and can generate a spec from a dashboard that already exists. Specs can be written by hand or by an AI agent, and both go through identical validation before anything changes in Superset.

Sundown: example dashboard built using Chartwright.

You can	Instead of (Superset up to 6.1.0, cited to source)	How it works
● Move dashboards between dev, staging, prod or another instance, including ones built in the UI	Re-importing dashboard exports in the UI, which update the dashboard but not the charts already in it (#34879, fixed after 6.1.0, not yet released)	MOVE-BETWEEN-INSTANCES.md
● Clone any dashboard onto another dataset, team or tenant	Editing exported files, or copying the dashboard and re-pointing each chart at the new dataset by hand (Stack Overflow, #20090)	CLONE-A-DASHBOARD.md
● Describe a dashboard, or a change to one chart, to an AI agent and have it built, checked and updated in place, without learning Superset's editor	Learning the chart editor, where tasks can take "hours of searching" (Hacker News), or Superset's MCP tools, which create a new dashboard on every build and can only add charts to an existing one (#39864)	AI-AGENTS.md
● Lay out rows, columns and tabs by drawing them as text, and keep heights you adjust in Superset	Nesting columns inside rows in the editor to place a tall chart beside two stacked ones (2019, 2026)	LAYOUT-GUIDE.md
● Review dashboard changes as a readable diff in a pull request, and check them in CI before they go live	Exports full of instance-specific ids, which don't diff or merge cleanly in git (#30190), and no settled way to deploy dashboards through CI/CD (Stack Overflow, unanswered)	DEPLOY-FROM-GIT.md
● Roll back any change, chart settings included, from a backup saved automatically before every apply	Remembering to export before each change, then re-importing, which restores the dashboard but not its charts' settings (#34879, fixed after 6.1.0, not yet released); re-importing deleted assets can also fail (#44309)	HISTORY-AND-ROLLBACK.md
● Rebuild your dashboards on a new Superset version from the same specs	Checking and repairing charts by hand when an upgrade leaves them blank in the editor (#32725)	SUPERSET-VERSIONS.md
● Create dashboards from code without reverse-engineering Superset's JSON	Working out the undocumented layout JSON, position_json (#32970)	DASHBOARDS-FROM-CODE.md

Install

pip install chartwright            # Python 3.11 or newer

# OPTIONAL
pip install "chartwright[mcp]"     # adds the MCP server for AI clients, chartwright-mcp
pip install "chartwright[visual]"  # for chartwright save-queries (CSV reports on built charts);
                                   # then run: playwright install chromium

Try it on your Superset

A dev or test instance is ideal. Add a profile to ~/.config/chartwright/profiles.toml; it names the instance and where the password comes from, never the password itself:

[dev]  # <profile> identifier
base_url = "https://superset-dev.example.com"
username = "chartwright"
password_env = "SUPERSET_DEV_PASSWORD"

Export the password variable, then:

# Build and update a dashboard
chartwright validate spec.json                      # check the spec offline
chartwright check spec.json --profile <profile>     # find every missing dataset, column or metric
chartwright plan spec.json --profile <profile>      # show what apply would change
chartwright apply spec.json --profile <profile>     # build or update the dashboard, then query every chart
chartwright restore backup.zip --profile <profile>  # roll back to the backup taken before an apply

# Start from a dashboard you already have
chartwright decompile <slug> --profile <profile> -o spec.json  # a spec for a copy of it
chartwright adopt <slug> --profile <profile> -o spec.json      # manage it where it is
chartwright absorb spec.json --profile <profile>               # copy heights set in Superset into the spec

# Design review
chartwright brief                                             # sizing and layout guidance for writing a spec
chartwright advise spec.json                                  # review the design; --fix applies the safe fixes
chartwright explain spec.json                                 # where each filled-in setting came from
chartwright redesign <slug> --profile <profile> -o spec.json  # decompile, review and fix in one step

# Other
chartwright schema                                      # the spec's JSON Schema
chartwright compile spec.json -o bundle.zip             # build the import file offline
chartwright standards check specs/                      # team standards (also show, assign, apply)
chartwright save-queries spec.json --profile <profile>  # optional [visual]: makes CSV reports work
chartwright calibrate                                   # suggest default heights from what absorb copied

chartwright <command> --help lists each command's options.

Requirements and limits

• Sign-in: a Superset user with database or LDAP login, or Preset API tokens; Chartwright doesn't sign in through SSO or OAuth. On an instance that uses SSO, ask your admin for an account that has a Superset password. All testing uses the Admin role.
• Datasets: datasets and database connections stay in Superset; create them on each instance first. A spec names each dataset by its database connection and table, so where connection names differ between instances, keep one copy of the spec per instance.
• Ownership: Chartwright changes only dashboards it built or that you adopted, so give each team its own slug prefix. To manage a UI-made dashboard where it is, run chartwright adopt; it names every setting the first apply will reset, before you apply.
• Edits: each apply writes the spec over the dashboard and undoes edits made in the UI, and takes a chart added there off the dashboard (the chart itself stays in Superset's Charts list); make lasting changes, and add new charts, in the spec. To keep chart heights you set by dragging in Superset, run chartwright absorb first; it copies them into the spec.
• Status: version 0.6.0, beta. CI builds on real Superset 4.1.4, 5.0.0 and 6.1.0 on every pull request (how it's tested).

Every limit, with what to do instead: Limits.

Every capability and command: FEATURES.md · How it's tested: VERIFICATION.md · Superset's behaviour, cited to source: CONTRACTS.md · Compared with preset-cli, sup and Terraform: COMPARISON.md · Design rules: DESIGN-BRAIN.md

Changelog · Stability · Contributing · Apache-2.0 (LICENSE, NOTICE)

---

Apache Superset and Superset are trademarks of the Apache Software Foundation. No endorsement by the ASF is implied.