Package Workflow

Package

Build a package directory first, then choose the right release path

Goal: make it obvious what lives in the package directory, what goes into the archive, and when to use validate, pack, convert, or publish.

Start with the local package folder

rawctx.yaml and every file listed in models must already exist before pack or publish can work. Native MetricFlow packages usually add dbt_project.yml through include.

my-package/
  rawctx.yaml
  README.md
  dbt_project.yml
  models/
    customers.yml
    orders.yml

Manifest

Keep the contract small and strict

The contract stays strict, but it is no longer OSI-only: strict SemVer, format set to osi or metricflow, a non-empty models list, and optional include files for native snapshots.

name: "@demo/jaffle-metrics"
version: "1.0.0"
format: "metricflow"
source_format: "metricflow"
description: "Native MetricFlow package"
models:
  - models/customers.yml
  - models/orders.yml
include:
  - dbt_project.yml

rawctx package work is easier to reason about if you separate the local directory from the uploaded archive. Both pack and publish take the package directory as input; publish rebuilds the archive internally after validation. Package directories can now be either converted OSI or native MetricFlow snapshots.

pack creates a deterministic .rawctx.tar.gz locally. publish does not take that tarball as input; it validates the directory again, builds a temporary archive, calculates the checksum, requests an upload URL, uploads bytes, and completes the version.

README.md is optional, but if it exists it is included in the archive and sent with publish metadata. Legacy install snippets are rewritten from rawctx install to rawctx snapshot-download during publish. Native MetricFlow packages can also carry extra snapshot files such as dbt_project.yml through include.

Required checks

name: @scope/packageversion: X.Y.Zformat: osi|metricflowmodels: relative filesinclude: optional extras

Model paths cannot be absolute, cannot contain .., and must resolve to real files inside the package directory. The same rule applies to include.

Archive contents

The builder includes the manifest, the optional README, every file named in models, any include files, and checksums.sha256.

package/rawctx.yaml
package/README.md
package/dbt_project.yml
package/models/customers.yml
package/models/orders.yml
package/checksums.sha256

Pack vs publish

rawctx pack: local archive only, no auth, no control-plane call.
rawctx publish: auth required, control-plane upload, version completion.
rawctx publish --from-dbt: convert plus package plus publish by default, or native MetricFlow publish when you add --native.

Manual flow

Validate, inspect, then publish

Use this when you already have a package directory and want the clearest directory-to-release path.

rawctx validate ./my-package
rawctx pack ./my-package --output-dir ./dist
rawctx login
rawctx publish ./my-package

Inspect-first dbt flow

Convert before publishing

This is the safest path when the team wants to inspect generated OSI files before the first release.

rawctx convert --from metricflow --to osi ./my-dbt-project --output ./dist/pkg
rawctx validate ./dist/pkg
rawctx pack ./dist/pkg --output-dir ./dist
rawctx login
rawctx publish ./dist/pkg

One-shot dbt flow

Publish directly from dbt

Default publish converts MetricFlow to OSI first. Add --native when you want to preserve the dbt/MetricFlow snapshot as the published package. Use --emit-package when you also want to keep the generated package directory after the publish run.

rawctx login
rawctx publish --from-dbt ./my-dbt-project --emit-package ./dist/pkg
rawctx publish --from-dbt ./my-dbt-project --native --emit-package ./dist/native-pkg
rawctx publish --from-dbt ./my-dbt-project --native --package-name @your-scope/jaffle-shop --package-version 1.2.3