unshackle moves your metrics, dashboards and permissions out of a BI tool and into files in a Git repository you own.

What you get

What unshackle can't translate faithfully is marked TODO(unshackle), with the original formula next to it. It doesn't guess.

How it works

1. Extract: reads definitions through your tool's API, or from files you download.
2. Translate: writes the files above. Nothing changes in your BI tool.
3. Report: migration/report.md shows, per dashboard, what was translated and what blocks the rest.
4. Check: compares the migrated queries with your tool's own numbers.

Get started

You need Python 3.11 or later and access to your BI tool.

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

• Repo layout: every folder and file unshackle writes
• Contributing · Security · Changelog
• The name: why a BI migration tool is named after Shackleton

Apache 2.0. Built and maintained by Querio.