Public HubPublic

Package

Package Workflow

Build, validate, pack, and publish rawctx package directories with a strict contract.

Docs homeSearch packagesInstall CLI

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.

Directory

Start with the local package folder

rawctx.yaml and every file listed in models must already exist before pack or publish can work.

my-package/
  rawctx.yaml
  README.md
  models/
    sales_summary.osi.yaml
    customers.osi.yaml

Manifest

Keep the contract small and strict

Today the package format is intentionally narrow: strict SemVer, osi format, and a non-empty models list.

name: "@demo/retail-analytics"
version: "1.0.0"
format: "osi"
source_format: "metricflow"
description: "Retail analytics semantic model"
models:
  - models/sales_summary.osi.yaml
  - models/customers.osi.yaml

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.

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.

Required checks
name: @scope/packageversion: X.Y.Zformat: osimodels: relative paths

Model paths cannot be absolute, cannot contain .., and must resolve to real files inside the package directory.

Archive contents

The builder includes only the manifest, the optional README, the model files named in the manifest, and checksums.sha256.

package/rawctx.yaml
package/README.md
package/models/sales_summary.osi.yaml
package/models/customers.osi.yaml
package/checksums.sha256
Pack vs publish
  • rawctx pack: local archive only, no auth, no registry call.
  • rawctx publish: auth required, registry upload, version completion.
  • rawctx publish --from-dbt: convert plus package plus publish in one command.

Manual flow

Validate, inspect, then publish

Use this when you already have OSI YAML files 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

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 --package-name @your-scope/jaffle-shop --package-version 1.2.3