Catalog CLI

chartcoach catalog opens one Guideline Catalog per command. Structured read and inspection commands emit JSON by default.

Install and inspect one guideline

uv tool install chartcoach

GUIDELINE_ID="directly-label-series-instead-of-using-a-color-key"

chartcoach catalog describe
chartcoach catalog list \
  --contains "direct labels" \
  --limit 5
chartcoach catalog read "$GUIDELINE_ID"
chartcoach catalog cite "$GUIDELINE_ID"

--source sets the catalog source and overrides CHARTCOACH_SOURCE. When both are absent, the command opens the official selected catalog. Use an exact release.json location when several commands must retain one release digest.

Commands

Run chartcoach catalog COMMAND --help for exact arguments and options.

Machine output

JSON data goes to standard output. Errors, warnings, and recovery instructions go to standard error.

Pass --format table for readable tabular output. read, cite, and search also accept --format markdown. manifest emits Markdown. Pass catalog read --role ROLE to retain one section role. Repeat --role to retain additional roles.

catalog sql rejects multiple statements and statements other than SELECT. Its DuckDB connection has external access disabled. A successful empty query exits 0 and returns an empty result.

Search an index

Set CATALOG_SOURCE to an indexed release and PROFILE to a name reported by catalog describe --source "$CATALOG_SOURCE". Full-text search uses its LanceDB table and keeps embedding providers idle:

uvx --from "chartcoach[index]" \
  chartcoach catalog search \
  --source "$CATALOG_SOURCE" \
  --profile "$PROFILE" \
  --mode fts \
  --where "role = 'section.advice'" \
  --limit 5 \
  "direct labels"

--profile can come from CHARTCOACH_INDEX_PROFILE. The limit counts search document hits before guideline deduplication. Each preview is at most 360 characters and reports whether it was shortened. Profile IDs are flat release-scoped handles. catalog describe --profile NAME reports the embedding binding, distance_metric, and python_requirements.

Vector and hybrid modes embed the query text through the function declared by the profile. Install the exact python_requirements shown by catalog describe --profile NAME. A fresh CLI process can set LanceDB registry variables from a caller-owned JSON file:

{
  "provider-key": "secret-value"
}

chartcoach catalog search \
  --source "$CATALOG_SOURCE" \
  --profile "$PROFILE" \
  --mode vector \
  --embedding-vars ./embedding-vars.json \
  "direct labels"

Create embedding-vars.json with the variable names required by your profile and real credentials. Restrict access to the file and keep it out of version control. The file maps LanceDB registry variable names to string values. chartcoach excludes its values from results, errors, and release artifacts. Embedding providers control their own diagnostic logs.

Build and publish

catalog build creates a compiled bundle from authored Markdown. Release commands require chartcoach[curation].

catalog release validate DIRECTORY checks local files. For published validation, set CATALOG_STORE to the object-store URI and RELEASE_DIGEST to the intended release digest:

chartcoach catalog release validate --store "$CATALOG_STORE"
chartcoach catalog release validate --store "$CATALOG_STORE" --digest "$RELEASE_DIGEST"
chartcoach catalog release validate --store "$CATALOG_STORE" --expect-digest "$RELEASE_DIGEST"

--store downloads fresh artifacts into temporary files and validates the selected catalog against its published descriptor. --digest chooses an exact candidate. --expect-digest checks the selected catalog and fails if its digest differs. Choose a local directory or --store. --expect-digest and --digest are mutually exclusive. Validation uses stored vectors, so embedding providers and credentials are not required.

release publish --dry-run prints object paths. release select --dry-run validates fresh candidate bytes and prints the selection target. Selection writes catalog.json after the same validation. Curate and publish documents the complete lifecycle.