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

Choose an id from the JSONL output. The examples below use combine-small-pie-slices-into-an-others-category.

{
  "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 guideline text, labels, sections, and selected source references.

Cite source references

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

cite --format json returns the public guideline URL, formatted guideline citation, and structured source references.

[
  {
    "id": "combine-small-pie-slices-into-an-others-category",
    "title": "Group small pie slices into an others category",
    "url": "https://chartcoach.dev/guidelines/combine-small-pie-slices-into-an-others-category",
    "guideline_citation": "[Group small pie slices into an others category](https://chartcoach.dev/guidelines/combine-small-pie-slices-into-an-others-category) (`combine-small-pie-slices-into-an-others-category`)",
    "sources": [
      {
        "reference_id": "muth_pie_charts_2018",
        "source_type": "misc",
        "authors_text": "Lisa Charlotte Muth",
        "year": "2018",
        "source_title": "What to consider when creating pie charts",
        "journal": null,
        "booktitle": null,
        "publisher": null,
        "doi": null,
        "url": null,
        "citation": "Lisa Charlotte Muth (2018). What to consider when creating pie charts."
      }
    ]
  }
]

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

Find guidelines covers filters, section text search, SQL joins, and indexed discovery across CLI, Python, and TypeScript.

Cache writes

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

Query a topic

Read one guideline

Cite source references

On this page