Import from Hex

Hex is a great partner to dbt, and this importer is not meant to replace it. It keeps a copy of your Hex work in dbt Charts' open format, in git next to your dbt project, so CI can catch model changes that would break it, lineage covers it, and AI agents can read exactly what it computes. See Why import.

This walkthrough moves one published Hex app into a dbt Charts board. Read Import from other BI tools first for the overall flow.

1. Create a Hex API token

1. In Hex, open Settings → API keys and choose New API key.
2. Give it read access to the projects you want to move, and copy it.

A token belongs to one workspace. Put it in your gitignored .env:

HEX_API_TOKEN='...'

Hex Cloud users need nothing else. On a single-tenant or self-hosted Hex, set HEX_BASE_URL to that instance's API address, including /api/v1:

HEX_BASE_URL='https://hex.acme.com/api/v1'

A full project URL carries its own origin, but --list has no URL to borrow from, so it needs HEX_BASE_URL there.

2. Find the project

Copy the project URL from your browser, or list what the token can see:

set -a; . ./.env; set +a; dct import hex --list

Each line shows the project id, when it was last published (or unpublished), and its title.

3. Import the project

set -a; . ./.env; set +a; dct import hex https://app.hex.tech/acme/hex/<project id>

The command writes ./hex-<project id>/. Use --out for another folder and --force to refresh an existing bundle.

The importer reads the published app, not the notebook draft. Publish the version you want to move first, and run it once so Hex has charts to render.

What you get

Path	From Hex
project.hex.yaml	Hex's project export: cells, chart specs, input parameters, and the app layout
outline.md	App tabs and cells in layout order, with chart encodings and inputs
queries/	The SQL of each SQL cell
png/	One render per chart cell placed in the app, from the latest completed run
source.json	The fetch record

Hex differs from the other tools in three ways:

• No whole-app screenshot. Hex renders individual chart cells only, so png/ holds one image per chart. Add your own screenshot of the app to png/ if you want the agent to see the full layout.
• No values in kpi/. Hex has no API for a cell's result, so kpi/ is empty. Before migrating, note the headline numbers from the app (or add a kpi/<cell>.csv per metric cell) so the agent has numbers to check parity against.
• Renders need a completed run. If the token cannot list the project's runs, or the project has never run, the bundle is still written and outline.md names each missing render under Not fetched.

4. Migrate it

Migrate ./hex-<project id> into a dbt Charts board.

See Migrate the bundle for what the agent does.

Hex-specific notes

• Python cells do not migrate as code. dbt Charts boards run SQL. The outline marks each Python cell UNMIGRATED; the agent rewrites its logic as SQL where it can, or leaves a note on the chart naming what is missing.
• Input parameters become variables. Each input cell and its default are in the outline, and carry over as a board control.
• Chained cells. The outline records the dataframe each SQL cell produces, so the agent can trace a chart back through the chain to its warehouse query.

Troubleshooting

Message	Fix
HEX_API_TOKEN is not set	Load your .env in the same command
... is not a Hex project URL or project id	Copy the URL from the project, or use the UUID from --list
Every chart under Not fetched with HTTP 403	The token cannot list the project's runs; use a token that can, or add screenshots to png/ yourself