Getting started

Run chartcoach with uvx, query the Default Catalog, read a guideline, and cite its sources.

Run chartcoach as a one-off CLI with uvx. The first catalog command reads the Default Catalog and prints guideline rows.

Install uv from the Astral installation guide, then check that the CLI resolves:

uvx chartcoach@latest --help

Package version

Examples use chartcoach@latest for one-off access. Pin the package when output must stay tied to one catalog release.

Query a topic

uvx chartcoach@latest catalog query --contains "pie chart" --limit 3 --format jsonl

You should see one JSON object per row. The first row is the id used below.

{"id":"combine-small-pie-slices-into-an-others-category","title":"Group small pie slices into an others category","description":"For pie charts with many small slices, use grouped slices on the chart to improve readability and mitigate clutter from tiny wedges and many labels for readers.","labels":["purpose:refine","basis:heuristic","chart:pie-donut","lever:encoding","group-cardinality:many","quality:readability","polish:declutter"]}

Use table for terminal reading. Use json, jsonl, or csv when another program reads stdout.

Read one guideline

uvx chartcoach@latest catalog read combine-small-pie-slices-into-an-others-category \
  --source-detail minimal \
  --format json

read returns the guideline text, labels, sections, and selected source metadata.

Cite its sources

uvx chartcoach@latest catalog cite combine-small-pie-slices-into-an-others-category \
  --format json

cite returns the public guideline URL and structured source references.

[
  {
    "id": "combine-small-pie-slices-into-an-others-category",
    "url": "https://chartcoach.dev/guidelines/combine-small-pie-slices-into-an-others-category",
    "sources": [
      {
        "reference_id": "muth_chart_types_guide_2025",
        "source_title": "A friendly guide to choosing a chart type",
        "doi": null,
        "url": null
      }
    ]
  }
]

Use markdown when a person will read citation output. Use json or jsonl when an agent needs guideline ids, source keys, titles, and locator fields.

Cache writes

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

Query a topic

Read one guideline

Cite its sources

On this page