Adoption playbook

Browse, adopt, and publish with confidence.

rawctx is designed around a trust-first workflow. Read provenance, preview structure, confirm installability, and only then move into download or publish.

Browse packagesInstall CLI

Three journeys

Keep the product flow decision-oriented

These docs mirror the product: browse first, adopt only when the package qualifies, and publish once ownership and validation are clear.

Browse

Search, inspect, and preview packages before any download or authentication step.

Use web or CLI to compare source, origin, schema shape, and recent activity.

Adopt

Move only native packages into direct rawctx download workflows.

Indexed packages stay preview-only and point back to the upstream owner instead of pretending to be downloadable.

Publish

Validate first, then publish with a package name and version you own.

Claim indexed packages only when you are ready to republish them natively under your own scope.

Package lanes

native means rawctx can hand off directly to snapshot-download. indexed means structure is previewable, but ownership and download stay upstream.

Authentication boundary

Public search, info, preview, and many downloads do not need login. Login is reserved for publish, claim, favorites, settings, or private tenant access.

Automation and Python

The CLI and Python SDK share the same public-first model, so notebooks and scripts can use the same query and download flow you see on the web.

Browse

Inspect what a package is before deciding what to do with it

Goal: search the registry, open the package detail, and confirm whether the package is native, indexed, recent, and relevant to the business question.

Start on the public path. Search by package name, source system, or business concept. On web, the detail page exposes origin, preview, and installability before you move into README or graph.

Caution: if a package is marked Preview only, treat it as a structure review path, not a rawctx download candidate.

python3 -m pip install --upgrade rawctx
rawctx search "shopify revenue" --sort downloads
rawctx info @scope/name

Adopt

Use the right handoff for native and indexed packages

Goal: download native packages directly, or move from an indexed preview back to the upstream source with full awareness of ownership.

Native package

Adopt through rawctx

Use rawctx when the package detail shows a native installable path.

rawctx snapshot-download @scope/name
rawctx snapshot-download @scope/name@1.2.3
rawctx download @scope/name models/sample.osi.yaml

Indexed package

Review structure, then go upstream

Use preview to inspect the structure, then follow the source link because download does not belong to rawctx for that package.

rawctx info @dbt-hub/jaffle-shop
# open the source link from the package detail page
# claim only when you are ready to publish a native version

Publish

Validate first, publish second

Goal: make package quality explicit before the registry becomes the distribution path.

Publishing stays linear: validate, pack, publish. If your starting point is an indexed package, claim it first and republish it natively under your own scope.

Caution: do not treat claim as a cosmetic step. Claim exists to separate preview discovery from genuine ownership and native release.

rawctx validate ./my-package --format auto --json
rawctx pack ./my-package --output-dir ./dist --json
rawctx publish ./my-package

rawctx claim @dbt-hub/jaffle-shop
rawctx publish --from-dbt . --package-name @your-scope/jaffle-shop

Python

Carry the same trust-first flow into notebooks and scripts

Goal: keep CLI and SDK behavior aligned so automation uses the same search and download semantics as the web UI.

Notebook shell

Public-first commands

Use --json when the result needs to feed another notebook cell or script step.

!rawctx search "semantic model" --sort downloads --json
!rawctx info @scope/name --json
!rawctx snapshot-download @scope/name --json

Python SDK

Sync and async clients

Use the convenience API for straightforward automation, or the async client when the caller already owns the event loop.

import asyncio
import rawctx

packages = rawctx.search("semantic model", sort="downloads")
package = rawctx.info("@scope/name")
snapshot_dir = rawctx.snapshot_download("@scope/name")

async def main():
    async with rawctx.AsyncRawctxClient() as client:
        return await client.search("semantic model", sort="recent")

asyncio.run(main())

Errors

Keep failure handling explicit

Goal: make it clear whether the issue is auth, installability, validation, or cache state instead of relying on ambiguous CLI text.

Common CLI cases
  • Authentication required: the current action needs publish, claim, favorites, settings, or private access.
  • preview-only package cannot be downloaded: inspect the preview or move to the upstream source.
  • version already exists: bump the version and publish again.
Typed Python errors
RawctxErrorUsageErrorAuthRequiredErrorRegistryErrorValidationErrorOfflineCacheMissError