Feature proposal: `codecarbon badge` — generate a README badge from a local emissions.csv

[davidberenstein1957]

This is a feature proposal, offered for discussion before implementation.

The user problem

Once a run finishes, everything CodeCarbon measured lives in emissions.csv on the machine that produced it. Nobody else ever sees it, and the person who ran it rarely looks again. The cheapest way to make a measurement stick is to put it where open-source projects already curate their signals: the README, next to the CI and coverage badges. A visible number is also what makes maintainers re-measure after a change.

Today there is no CLI command that summarises or reports on an existing emissions.csv at all — the CLI only does config, auth, live monitoring and hardware detection.

Proposed design

A single new command that reads the CSV and writes badge artefacts locally. No network calls, no hosted service, no account:

codecarbon badge [OPTIONS]

  --file PATH                  emissions.csv to read        [default: ./emissions.csv]
  --project TEXT               filter rows by project_name  [default: all rows]
  --select [last|mean|total]   which run(s) to report       [default: last]
  --output-dir PATH            where to write               [default: .]
  --label TEXT                 left-hand badge text         [default: "carbon"]
  --color TEXT                 badge colour                 [default: grey]
  --format [svg|json|markdown|all]                          [default: all]

It writes codecarbon-badge.svg (a flat shields-style badge rendered from a small string template) and codecarbon-badge.json (the documented shields.io endpoint schema, for users who want to publish it themselves, e.g. on GitHub Pages), then prints the markdown snippet to paste into a README.

Supporting module codecarbon/badge.py holds the whole feature: CSV load, aggregation, unit formatting, SVG template, JSON writer.

Why it fits

• The CLI is a plain typer app (codecarbon/cli/main.py); this is one more @codecarbon.command alongside detect.
• The data source is the existing FileOutput CSV, whose schema is EmissionsData — no new output method, no tracker changes.
• No new dependencies: stdlib csv, json and string templating are enough. Text widths are estimated from character count, deliberately avoiding a font-metrics dependency.

Scope boundary, and one honest caveat

A badge turns a private measurement into a public claim, and CodeCarbon numbers are often estimates (TDP-modelled CPU power, country-average carbon intensity). Two consequences for the design:

• Colour-neutral by default. No automatic green/orange/red thresholds. A green badge on a large model is greenwashing, and a fixed gram threshold means nothing across wildly different workloads. Colour only if the user explicitly asks for one.
• The badge reports what the CSV says, nothing more. No trend graphs, no history, no "improvement" claims.

Also deliberately out of scope: a badge output method that fires on every tracker stop (the CSV is the source of truth; regenerate on demand), any hosted endpoint or ingestion service, and a GitHub Action (that is a few lines of YAML in the docs, not code in this repo).

Feedback on the CLI surface and on the colour decision especially welcome before this is built out.