Move from Hex

Turn a Hex project into a Querio notebook and board while preserving its SQL, Python logic, inputs and business context.

unshackle's exporter for this tool has early support. Review the migration report before relying on its output.

Already exported? Go straight to Move exported work to Querio.

1. Prepare access

Install unshackle and run the commands below from your analytics Git repository.

• HEX_API_TOKEN, using a workspace read token or a personal token with access to the project. API access requires a Team or Enterprise plan.
• HEX_BASE_URL is optional for single-tenant or regional deployments.
• Set HEX_EXPORT_DIR to project YAML exports for chart settings, inputs and app layout. HEX_SEMANTIC_DIR can include semantic-project exports.

2. Export one report

unshackle check hex --prompt
unshackle inventory hex
unshackle migrate hex --only PROJECT_ID
unshackle todo

Replace PROJECT_ID with the selected item's ID from inventory. The credential prompt saves values to a local, git-ignored .env; keep those values out of agent prompts.

Read migration/report.md for missing dependencies, extraction errors and unfinished translations before continuing.

Using exported files instead

You can import project YAML from Git export and semantic YAML from hex context semantic-project pull:

unshackle init
unshackle import hex project-exports/ semantic/
unshackle build hex
unshackle todo

Only include directories you have exported. Files omit usage and sharing. API-only exports lack chart settings and app layout, and the API returns draft cells that may differ from the published app.

3. Review what needs adapting

• Preserve Python transformations or rewrite them deliberately; they are exported with TODOs.
• Dataframe SQL originally running in DuckDB may need changes for the warehouse's SQL dialect.
• Review Jinja, missing input defaults, multi-series charts and semantic-model joins.

Download a source cell's result as CSV or rerun its SQL. Confirm whether your baseline comes from the draft project or published app, and record input defaults and dates.

4. Rebuild and check it in Querio

Open the repository in Claude Code, Codex or your preferred coding agent. Give it this brief:

Read https://docs.querio.ai/llms/guides/move-bi-workflow/already-unshackled.md.
Use this repository's Hex export to rebuild REPORT_NAME in Querio.
Pay attention to Hex Python cells, dataframe SQL, input defaults and
differences between draft cells and the published app.
Ask me for the target workspace, datasource and a trusted source result.

Replace REPORT_NAME with the report you chose. Follow Move exported work to Querio for CLI authentication, the full agent task, verification and sharing. Check the rebuilt Querio output against your source result before using it as a replacement.

For export settings and the full list of translation gaps, see unshackle's Hex guide.