Metadata-Version: 2.4
Name: rawctx
Version: 0.3.2
Summary: rawctx CLI scaffold
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.28.1
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: ruamel.yaml>=0.18.6

# rawctx CLI

Python CLI and SDK for rawctx Hub.

## 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:

```python
!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:

```python
import rawctx

result = rawctx.search("semantic model", registry="https://api.rawctx.dev", sort="downloads")
pkg = rawctx.info("@scope/name", registry="https://api.rawctx.dev")
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:

```python
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")
        snapshot_dir = await client.snapshot_download("@scope/name")
        return result, 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
- `indexed` packages remain preview-only and cannot be downloaded directly

## Convert Workflow

```bash
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:

```bash
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`

```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>/`
