# wcc command line

> WestCoast Charts 1.1.5, release, public Core release, on npm. HTML: https://westcoast-charts.com/docs/cli/ · Index for agents: https://westcoast-charts.com/llms.txt · Source: agent tools repository, commit dc96bce82bc43568dad175caf12127675bd8689e

> **Public agent tools 0.2.3, tested with Library 1.1.5; available from the versioned GitHub release and npm. Install the public Core runtime separately; Premium requires its separately supplied complete runtime. The website browser runs the library directly.**

> Website reference for agent tools 0.2.3. The currently recorded tested library pairing is 1.1.5; the latest verified public Core distribution is 1.1.5. Core 1.1.5 is published through the verified release channels. Run `wcc version --json` or read `wcc://version` to identify your installed runtime. This website derives the reference heading and distribution guidance from its release manifest while preserving the pinned source document. Historical output below retains its original version and values; it is not proof of a newer release.

## Install CLI and MCP

Public agent tools 0.2.3, tested with Library 1.1.5; available from the versioned GitHub release and npm. The command below installs both the current Core runtime and the tools. Premium is a separately supplied runtime; it is not included in either public archive. Premium customers replace the Core installation command with their private complete library package; see the Premium setup section in the MCP guide.

```sh
npm install west-coast-charts@1.1.5
npm install west-coast-charts-agent@0.2.3
npx --no-install wcc --help
npx --no-install wcc-mcp --help
```

[Agent-tool source and release](https://github.com/Lokumbus/west-coast-charts-agent). Agent archive SHA-256: `ca2c7af4a00d69f2d463d310139480aca8cef4e06163897d86b1ed90da4e7865`. Read `wcc://version` after connecting to verify the resolved library, validator and description providers.

**Machine-readable contract:** `wcc schema`. It validates against https://clispec.dev/schema/v0.3.json, and `wcc --help --json` prints the same document. Narrow it to one command with `wcc schema chart render`.

**Global flags** go before or after the command:
- `-o/--output auto|text|json|ndjson`. `auto` gives text on a TTY and JSON when piped.
- `--json` is an alias for `-o json`.
- `-q/--quiet`, `-h/--help`, `--version`.

**SPEC** is one of: a file path, `-` (stdin), `example:<id>`, or nothing, in which case stdin is read when it is not a TTY. On a TTY, a missing SPEC is a usage error, because wcc never prompts.

| command | effects | output | notes |
|---|---|---|---|
| `chart render SPEC` | read_only | opaque `image/svg+xml` / `image/png` | stdout carries only the artifact. PNG to a TTY is refused. |
| `chart export SPEC --out FILE [--yes]` | idempotent | `{path,format,bytes,sha256,changed,meta,table?}` | Same bytes give `changed:false`. A different existing file prompts on a TTY; without one it exits 6 with hint `… --yes`. |
| `chart validate SPEC` | read_only | `{ok,validator,errors,warnings}` | The report is printed on stdout even when invalid. Invalid specs exit 2 with an envelope. |
| `chart table SPEC` | read_only | `wcc-describe/1` | Schema-valid object, no extra keys. With the 1.1 library this is the full `chart.describe()` model (aggregates, scales, extrema; stacked charts add per-category totals and a `Total` column). The matching describe module is required; JSON callers get `meta.tableSource: "describe"` from `chart export --with-table`. |
| `options schema [PATH] [--depth N]` | read_only | JSON Schema 2020-12 | alias `schema get PATH` |
| `types list [--tier]` | read_only | `{items,total}` | |
| `examples list [--type --tag --premium --free]` | read_only | `{items,total}` | |
| `examples get ID [--spec-only]` | read_only | example or bare spec | |
| `skills show` (also bare `skills`) | read_only | opaque `text/markdown` | |
| `skills install [DIR] [--force]` | idempotent | `{path,changed,sha256}` | An edited file exits 5 with hint `… --force` |
| `errors` | read_only | `{items}` | exit codes |
| `version` | read_only | versions | |
| `schema [COMMAND…]` | read_only | clispec v0.3 doc | |

**Render flags:**
- `--data FILE`, `--format svg|png`, `--width`, `--height`
- `--seed N` (default 1), `--scale`, `--background`
- `--theme light|dark`, `--validate strict|warn|off`
- `--font-set inter-4.1|liberation-sans-2.1.5` (aliases `inter`, `liberation`; default `inter-4.1`). An unknown set is a usage error (exit 2).
- `--license-key-file FILE`
- `--evaluation` (opt-in preview: premium types render without a key, with the "unlicensed" watermark; `meta.licensed` false)
- `--license-key` exists but is hidden and prints a warning.

Licence key sources, first one present wins (no fallthrough, like the browser library, where a per-chart `chart.licenseKey` beats the global `setLicenseKey`):

1. `--license-key-file FILE` (or the hidden `--license-key`)
2. `chart.licenseKey` in the spec
3. env `WCC_LICENSE_KEY`

If the chosen key is invalid, the `license` error (`details.reason: license_invalid`) names the source in the message and in `details.keySource` (`option`, `spec` or `env`); it does not try the next source. `meta.licenseKeySource` reports the source used on success. Keys are never echoed into output, warnings or errors.

**Fonts.** Output uses the frozen `inter-4.1` set (Inter 4.1, SIL OFL; Liberation Sans as fallback family). An earlier curated browser-parity record reported 18 examples within 1 px of headless Chromium for marks and labels. That historical result is not a certification of the current target: the recorded RC7 acceptance run passed 127 functional tests, with zero skips, and did not repeat a universal browser-parity audit. The comparison script remains [packages/render-core/scripts/parity.js](https://github.com/Lokumbus/west-coast-charts-agent/blob/dc96bce82bc43568dad175caf12127675bd8689e/packages/render-core/scripts/parity.js) (source-repository test; not included in the installed archive). The headless viewport equals the chart width, so responsive breakpoints see the chart size. See `packages/render-core/fonts/FONTS.md` for font provenance and measurement details.

**Exit codes:**

| code | kind |
|---|---|
| 0 | ok |
| 1 | internal |
| 2 | usage, schema |
| 3 | not_found |
| 4 | license (`details.reason`: `license_required` or `license_invalid`) |
| 5 | conflict |
| 6 | confirmation_required |

In structured mode the last stderr line is `{"error":{kind,message,hint,details?,exit_code,retryable}}`. In text mode it is `wcc: error: … / hint: …`. wcc never emits ANSI.

## Examples
```sh
wcc examples get line-basic --spec-only > chart.json
wcc chart validate chart.json
wcc chart render chart.json > chart.svg
wcc chart export chart.json --out chart.png --scale 2
cat chart.json | wcc chart render --format png > chart.png
wcc chart table chart.json -o text
wcc options schema plotOptions.bar --depth 2
WCC_LICENSE_KEY=… wcc chart render example:sankey-budget > sankey.svg
wcc skills install .agents/skills
```

### Recorded output (2026-10-28 documentation snapshot; library 1.1.1-rc.7)

The following preserved output predates the 0.2.2 / 1.1.1 target. It is an example, not a version or acceptance proof for the 0.2.2 / 1.1.1 pair.

A typo in a layer type. The report goes to stdout, the envelope to stderr, exit code 2:

```text
$ wcc chart validate dashboard.json
1 error(s)
  error plotOptions.radialColumn.layers[0].type: plotOptions.radialColumn.layers[0].type is "donught"; allowed: "pie", "donut", "radialBar", "heatmap", "polarArea", "gauge", "sunburst", "chord", "matrix", "arc", "nestedDonut", "goals", "wave".  -> Did you mean "donut"?
wcc: error: plotOptions.radialColumn.layers[0].type is "donught"; allowed: "pie", "donut", "radialBar", "heatmap", "polarArea", "gauge", "sunburst", "chord", "matrix", "arc", "nestedDonut", "goals", "wave".
  hint: Did you mean "donut"?
```

The verification table of a stacked column chart:

```text
$ wcc chart table stacked.json -o text
Stacked column chart with 2 series: A, B. 2 data points per series. Values range from 1 to 4. Category totals range from 4 (Q1) to 6 (Q2).

Category  A  B  Total
Q1        1  3  4
Q2        2  4  6
```