CLI

Query, read, cite, validate, build, index, and export chartcoach catalog instances from the terminal.

The chartcoach CLI reads the package-pinned Default Catalog when --source is omitted. The examples use uvx so the command can run without a separate tool install.

Install uv from the Astral installation guide. Use uvx chartcoach@latest --help and uvx chartcoach@latest catalog --help to inspect the live command tree.

Use Querying for task examples across CLI, Python, and TypeScript.

Command groups

Task	Commands
Inspect	`overview`, `labels`, `roles`, `schema`, `values`
Discover	`list`, `query`, `sql`, `find`
Evidence	`read`, `cite`
Cache	`cache path`, `cache list`, `cache versions`, `cache pull`, `cache clear`
Index	`index create`
Build	`validate`, `build`, `export duckdb`

Output formats

Row-oriented commands support table, json, jsonl, and csv unless the command has a narrower contract. Search also supports compact and markdown.

Use JSONL for agent candidate rows:

uvx chartcoach@latest catalog query --label chart:bar:use --limit 5 --format jsonl
uvx chartcoach@latest catalog read compare-percentages-with-bars-not-pies \
  --source-detail minimal \
  --format json
uvx chartcoach@latest catalog cite compare-percentages-with-bars-not-pies \
  --format json

Query and search rows are candidates. Use ids copied from query, find, or list. Do not generate ids from titles.

Inspect queryable tables before writing SQL against a new catalog.

Extras

Need	Extra	One-off selector
Base query, read, cite, SQL	none	`uvx chartcoach@latest ...`
Indexed `catalog find`	`index`	`uvx --from 'chartcoach[index]@latest' chartcoach ...`
MCP SQL server	`mcp`	`uvx --from 'chartcoach[mcp]@latest' chartcoach ...`
MCP search server	`mcp,index`	`uvx --from 'chartcoach[mcp,index]@latest' chartcoach ...`

Sources

Pass --source or set CHARTCOACH_SOURCE when a command should read a custom catalog.

uvx chartcoach@latest catalog validate --source ./dist/catalog
CHARTCOACH_SOURCE=./dist/catalog uvx chartcoach@latest catalog overview

Accepted sources include bundle directories, authored folders, standalone entries.parquet files, and release metadata URLs.

The Cataloging scheme defines the Default Catalog, locator forms, release metadata, and cache layout.

Command recovery

uvx is missing

Install uv, then open a new shell so the uvx executable is on PATH.

find is missing

Indexed discovery needs the index extra:

uvx --from 'chartcoach[index]@latest' chartcoach catalog find \
  --mode fts \
  "overplotted scatter plots"

unknown guideline id

List or query ids first, then pass the exact id to read or cite. Do not derive ids from titles.

Artifact cache

Cache commands inspect and manage chartcoach-owned release artifacts:

uvx chartcoach@latest catalog cache path
uvx chartcoach@latest catalog cache versions --format jsonl
uvx chartcoach@latest catalog cache list

Use cache pull to warm a release and cache clear to remove cached artifacts. Pass --catalog-only when a warm cache only needs metadata.json, MANIFEST.md, and entries.parquet.

Catalog.open() and first CLI catalog reads download package-pinned artifacts. Indexed search downloads an index archive. Set CHARTCOACH_CACHE_DIR to isolate writes.

Indexed discovery

Indexed commands require the index extra. Use --from so uvx creates a run environment with that extra:

uvx --from 'chartcoach[index]@latest' chartcoach catalog find \
  --mode fts \
  --limit 3 \
  --format compact \
  "overplotted scatter plot with too many points"

When --source and --index are omitted, find resolves the package-pinned LanceDB index for the Default Catalog. The first indexed command downloads and extracts the index. Default indexed examples use --mode fts, so no embedding credential is needed.

The MCP server has a separate configuration boundary. catalog find can resolve the default cached index, but mcp serve registers search only when the server is configured with --index or CHARTCOACH_INDEX. See MCP.

Build a caller-owned local index for custom catalog sources:

uvx --from 'chartcoach[index]@latest' chartcoach catalog index create \
  --index ./chartcoach-index

Use CHARTCOACH_INDEX or --index to point commands at a caller-owned index. Indexed search returns candidate ids, so read exact records before citing them.

Build and export

Validate an authored folder, build a bundle, or export DuckDB tables:

uvx chartcoach@latest catalog validate --source ./catalog-source
uvx chartcoach@latest catalog build --source ./catalog-source --out ./dist/catalog
uvx chartcoach@latest catalog export duckdb \
  --out ./chartcoach-catalog.duckdb

On this page