rawctx 0.3.8

rawctx CLI scaffold

rawctx CLI

Python CLI and SDK for rawctx Hub.

Detailed package workflow guide:

• ../docs/guides/package-workflow.md

Commands

User:

• rawctx login [--registry URL] [--id-token JWT] [--token-name NAME] [--expires-in-days N] [--no-browser] [--json]
• rawctx logout [--local-only] [--json]
• rawctx search [QUERY] [--format F] [--source-format F] [--origin all|native|indexed] [--domain D] [--source S] [--tags CSV] [--sort recent|downloads|stars] [--page N] [--size N] [--json] [--offline] [--registry URL]
• rawctx info PACKAGE_REF [--json] [--offline] [--registry URL]
• rawctx download PACKAGE_REF MODEL_PATH [--local-dir DIR] [--stdout] [--offline] [--force] [--json] [--registry URL]
• rawctx snapshot-download PACKAGE_REF [--local-dir DIR] [--offline] [--force] [--json] [--registry URL]
• rawctx validate [TARGET] [--format auto|manifest|osi] [--show-dataset-measures] [--json]
• rawctx pack [TARGET_DIR] [--output-dir DIR] [--json]
• rawctx convert --from metricflow --to osi INPUT_PATH --output DIR [--package-name @scope/name] [--package-version X.Y.Z] [--overwrite] [--json]
• rawctx publish [TARGET_DIR] [--registry URL]
• rawctx publish --from-dbt DBT_PROJECT_DIR [--emit-package DIR] [--package-name @scope/name] [--package-version X.Y.Z] [--registry URL]

Maintainer:

• rawctx claim PACKAGE_REF [--json] [--registry URL]

Ops:

• rawctx index dbt --seed-file PATH [--only owner/name] [--limit N] [--dry-run] [--json] [--registry URL]
• rawctx index git --repo owner/name --source-ref REF --package-version X.Y.Z [--package-name NAME] [--scope SCOPE] [--model-glob GLOB ...] [--dry-run] [--json] [--registry URL]

Notebook / Code

Search uses the public Hub index first so CLI and SDK results match the web search experience. If a search returns no public matches and you have a token configured, rawctx retries with authenticated search.

Notebook shell style:

!rawctx search "semantic model" --sort downloads --json
!rawctx info @scope/name --json
!rawctx snapshot-download @scope/name --json
!rawctx download @scope/name models/sample.osi.yaml --json
!rawctx validate ./my-package --json

Python API:

import rawctx

result = rawctx.search("semantic model", registry="https://api.rawctx.dev", sort="downloads")
pkg = rawctx.info("@scope/name", registry="https://api.rawctx.dev")
model = rawctx.load("@scope/name", registry="https://api.rawctx.dev")
prompt = rawctx.to_prompt(
    "@scope/name",
    datasets=["expense_reports", "users"],
    max_tokens=2000,
    registry="https://api.rawctx.dev",
)
print(model.datasets)        # ['users', 'trips', 'expense_reports']
print(model.measures)        # [Measure(name='total_amount', ...)]
print(model.dimensions)      # [Dimension(name='currency_code', ...)]
print(model.relationships)   # [Relationship(name='user_trips', ...)]
print(prompt)
print(pkg["model_paths"])
snapshot_dir = rawctx.snapshot_download("@scope/name", registry="https://api.rawctx.dev")
osi_path = rawctx.download("@scope/name", "models/sample.osi.yaml", registry="https://api.rawctx.dev")
validation = rawctx.validate("./my-package")

Async Python API:

import asyncio
import rawctx

async def main():
    async with rawctx.AsyncRawctxClient(registry="https://api.rawctx.dev") as client:
        result = await client.search("semantic model", sort="recent")
        model = await client.load("@scope/name")
        prompt = await client.to_prompt("@scope/name", datasets=["expense_reports", "users"])
        snapshot_dir = await client.snapshot_download("@scope/name")
        return result, model, prompt, snapshot_dir

asyncio.run(main())

Download behavior:

• download fetches one OSI YAML file listed in manifest.models
• snapshot-download materializes the full extracted package tree
• When using snapshot-download --local-dir, prefer a new or empty directory. --force only replaces an existing rawctx snapshot directory and refuses to wipe the current working directory or unrelated folders.
• indexed packages remain preview-only and cannot be downloaded directly

Convert Workflow

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

Publish directly from dbt:

rawctx publish --from-dbt ./my-dbt-project --emit-package ./dist/pkg

Auth Flow (Auto + Fallback)

1. Run rawctx login.
2. CLI opens or prints the OAuth URL from POST /api/auth/login and falls back to the legacy GitHub endpoint if needed.
3. Complete login in the browser.
4. CLI automatically polls OAuth session status and captures id_token when the registry supports it.
5. CLI calls POST /api/auth/token and stores the API token in ~/.rawctx/config.yaml.

Manual fallback:

• rawctx login --id-token '<JWT>'

Config and Environment

Config file (default): ~/.rawctx/config.yaml

registry: "https://api.rawctx.dev"
auth:
  token: "rxctx_..."
  token_id: "uuid"
  token_name: "rawctx-cli"
  issued_at: "2026-02-28T00:00:00+00:00"
profile:
  username: "owner"

Environment overrides:

• RAWCTX_CONFIG (config path)
• RAWCTX_REGISTRY (registry URL)
• RAWCTX_TOKEN (auth token)

Priority: CLI option > env var > config > default.

Offline Mode

--offline is supported for:

• search
• info
• download
• snapshot-download

Cache paths:

• index: ~/.rawctx/cache/packages.json
• archives: ~/.rawctx/cache/archives/@scope/name/<version>.rawctx.tar.gz
• snapshots: ~/.rawctx/packages/@scope/name/<version>/