# Installation

> Chartory charts install from a shadcn registry. Free charts come from the public registry. The 100 free charts (MIT) need no token. Paid items need one: the licence key from your purchase email, or a token you create in Account · Access. Add it to .env, point components.json at the @chartory registry, then add a chart by its slug.

**Let your agent install it.** Skip the steps below: connect the Chartory MCP server and let your agent install charts. [Start with MCP](https://usechartory.com/docs/agents)

## Before you start

- A React project where the **shadcn CLI** runs. It reads components.json.
- For paid items, a **registry token**: the licence key from your Code or Complete email, or one you create in Account · Access (AI Ops · Code buyers create one there). The 100 free charts need none.

## 1. Add your token

Use the licence key from your purchase email, or create a token in Account · Access. Keep it out of git.

.env:

```
CHARTORY_TOKEN=••••••••
```

## 2. Add the registry

Tell shadcn where @chartory lives and send the token with every request. For free charts the URL alone is enough: leave out the headers block.

components.json:

```json
"registries": {
  "@chartory": {
    "url": "https://usechartory.com/r/{name}.json",
    "headers": {
      "Authorization": "Bearer ${CHARTORY_TOKEN}"
    }
  }
}
```

## 3. Add a chart

Every chart has one slug, the same in Figma, in code and in the URL.

```bash
npx shadcn add @chartory/waterfall
```

## 4. Use it

Import chartory.css once in your global CSS: it holds the Hearth tokens for light and dark (with Code or Complete, add @chartory/signal: chartory-signal.css after it, and the Signal module imported once). Props are named like the Figma variants: size and legend; collection picks Signal.

usage.tsx:

```tsx
/* globals.css, once */
@import "../chartory.css";
@import "../chartory-signal.css"; /* Signal: Code and Complete */

// layout.tsx, once (Signal: Code and Complete)
import "@/lib/chartory/charts/signal"

import { Waterfall } from "@/components/chartory/waterfall"

<Waterfall size="m" legend />
<Waterfall size="m" collection="signal" />
```

**Note: Where your token goes.** Only in .env. components.json reads it as ${CHARTORY_TOKEN}; never paste the token itself there.

## Install several

List the slugs in one command; shared parts install once.

```bash
npx shadcn add @chartory/waterfall @chartory/bump @chartory/donut
```

## Get the latest release

Run the add command again with **--overwrite** to replace a chart with its newest version.

```bash
npx shadcn add @chartory/waterfall --overwrite
```

## Troubleshooting

| You see | Do this |
| --- | --- |
| 401 from the registry | The token is missing, mistyped, regenerated or revoked. Copy a current one from Account · Access into .env. |
| 403 from the registry | Your plan doesn't include this item. Compare plans or upgrade from your account. |
| @chartory is not found | Add the @chartory registry to components.json. |
| A chart looks scaled | Pass a size instead of resizing it: xs, s, m or l. |
| A chart draws without colour | Import chartory.css in your global CSS. |
| The CLI asks for CHARTORY_TOKEN | Free charts need no token: leave out the headers block, or add the token to .env. |

## Other ways

- **Your coding agent** installs charts through MCP. See Agents: MCP and llms.txt.
- **Free charts** (100 types, Hearth, MIT licensed; source at github.com/chartory/charts) install from the public registry with the command on each chart page. **Signal** (Code and Complete): npx shadcn add @chartory/signal, then import "@/lib/chartory/charts/signal" once (your root layout) and chartory-signal.css after chartory.css.
- **Sector packs and dashboards** (Complete): @chartory/sector-fintech adds the sector's charts, widgets, dashboard and sample datasets; @chartory/dashboard-fintech adds the dashboard alone.
- **The AI Ops template** (AI Ops · Code or Complete): in a new Next.js app with a src directory, delete src/app/page.tsx, then run npx shadcn add @chartory/ai-ops.
- **Interactive widgets** (Code and Complete): add -interactive to a slug, for example @chartory/waterfall-interactive, for the period menu, date range picker and tooltips.
- **The Figma file** opens from the link in your purchase email.