unshackle moves your metrics, dashboards and permissions out of a BI tool and into files in a Git repository you own.
What you get
| You had in your BI tool | You get in your repo |
|---|
| Metrics, measures, calculated fields | Metrics in Apache Ossie, an open semantic-layer format (semantic/) |
| Dashboards | Jupyter notebooks: one SQL query and one chart per tile (notebooks/) |
| Tables and data sources | Table and column descriptions (catalog/) |
| Permissions, row-level security | Cedar policies and SQL row filters (policies/) |
| Descriptions, glossaries | Markdown (knowledge/) |
What unshackle can't translate faithfully is marked TODO(unshackle), with the
original formula next to it. It doesn't guess.
How it works
- Extract: reads definitions through your tool's API, or from files you download.
- Translate: writes the files above. Nothing changes in your BI tool.
- Report:
migration/report.md shows, per dashboard, what was translated and what blocks the rest.
- Check: compares the migrated queries with your tool's own numbers.
Get started
You need Python 3.11+ and access to your BI tool. Use pip inside a virtual environment (system Python
often refuses it outside one), or uv tool install unshackle for a global command.
pip install unshackle # or: uv tool install unshackle
cd your-analytics-repo
unshackle check <tool> --prompt # asks for credentials, saves them to .env (git-ignored)
unshackle migrate <tool>
Then:
unshackle run # run the notebooks; see which tiles return data
unshackle verify # compare migrated numbers with your tool's
unshackle todo # list what's left to finish
unshackle tools <tool> says where to find each credential.
Supported tools
Maturity: Most complete: the most translated and tested. Real projects: also tested on
open-source projects people built. Saved exports: tested on exports over a fictional dataset.
Early: the basics; expect more TODOs.
Each tool's page covers connecting, what you get, what's left to finish and how to check the numbers.
API or files
API gets the most: definitions, dashboards people built in the tool, usage,
sharing, and for most tools the SQL the tool itself runs.
Files work when you can't get API credentials. They carry less (usually no usage
or sharing, and for Looker and Omni no user-built dashboards); the report lists
what's missing.
unshackle import <tool> <files or folder>
unshackle build <tool>
Data that lives only in your BI tool
Tableau extracts, Excel and CSV files have no warehouse behind them. migrate asks
whether to copy that data to data/ (git-ignored) so the notebooks can run on it
locally. Copying .hyper extracts needs Tableau's Hyper API, a large download:
pip install "unshackle[hyper]".
Check the numbers
unshackle verify runs the cases in migration/parity/ against your warehouse and
compares them with the source tool's numbers. For Tableau, unshackle verify --init tableau
writes the cases from Tableau's own view data. For other tools, write them by hand:
see the verify guide.
How it's tested
- Against numbers, not snapshots. Most tests build a migration from a saved export, run the
generated SQL in DuckDB on a fictional dataset, and compare the result with the same numbers
computed independently, following the source tool's own rules.
- About 1,270 tests run offline:
uv pip install -e ".[dev]" && pytest.
unshackle verify does the same on your data: migrated SQL against your tool's own numbers.
unshackle is built with Claude Code; every change goes through
those tests.
With a coding agent
unshackle runs fine on its own. If you use a coding agent (Claude Code, Codex,
Cursor), point it at the repo: AGENTS.md explains the layout, and the guides in
migration/skills/ walk it through finishing each kind of TODO.
Try it without a BI tool
git clone https://github.com/Querio-App/unshackle && cd unshackle
uv venv && uv pip install -e ".[dev]"
./examples/tableau-demo/run.sh /tmp/acme
The demo migrates a saved Tableau export into /tmp/acme and checks a dashboard's
numbers against Tableau's.
More
Apache 2.0. Built and maintained by Querio.
