> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formo.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Charts

> Create, list, query, move, duplicate, reorder, update, and delete charts within dashboard boards using the Formo CLI.

The `formo charts` command group manages charts within dashboard boards. Every chart command is scoped to a board with `--board-id`.

## `formo charts list`

List charts for a board. Returns lightweight summaries by default; pass `--results` to execute each chart’s query and include full results.

<Note>
  Requires `boards:read` scope on your API key.
</Note>

| Option       | Type      | Required | Description                                                                         |
| ------------ | --------- | -------- | ----------------------------------------------------------------------------------- |
| `--board-id` | `string`  | ✅        | Board ID to list charts from                                                        |
| `--results`  | `boolean` | ❌        | Execute each chart’s query and include results (slower; hits the analytics backend) |
| `--page`     | `number`  | ❌        | Page number, 1-indexed                                                              |
| `--size`     | `number`  | ❌        | Page size                                                                           |

```bash theme={null}
formo charts list --board-id board_abc123 --size 25
```

***

## `formo charts meta`

List lightweight chart metadata for a board without query results.

<Note>
  Requires `boards:read` scope on your API key.
</Note>

```bash theme={null}
formo charts meta --board-id board_abc123
```

***

## `formo charts get <chartId>`

Get a single chart by ID.

<Note>
  Requires `boards:read` scope on your API key.
</Note>

```bash theme={null}
formo charts get chart_abc123 --board-id board_abc123
```

***

## `formo charts query <chartId>`

Execute a saved chart query after substituting `{{date_from}}` and `{{date_to}}`.

<Note>
  Requires `boards:read` scope and a chart query that uses both date variables.
</Note>

| Option        | Type     | Required | Description                       |
| ------------- | -------- | -------- | --------------------------------- |
| `--board-id`  | `string` | ✅        | Board ID the chart belongs to     |
| `--date-from` | `string` | ✅        | Date variable value, `YYYY-MM-DD` |
| `--date-to`   | `string` | ✅        | Date variable value, `YYYY-MM-DD` |

```bash theme={null}
formo charts query chart_abc123 --board-id board_abc123 --date-from 2026-04-01 --date-to 2026-04-30
```

***

## `formo charts create`

Create a chart from typed flags or a raw JSON body.

<Note>
  Requires `boards:write` scope on your API key.
</Note>

### Options

| Option          | Type     | Required | Description                                                                                        |
| --------------- | -------- | -------- | -------------------------------------------------------------------------------------------------- |
| `--board-id`    | `string` | ✅        | Board ID to add the chart to                                                                       |
| `--body`        | `string` | ❌        | Raw JSON chart body. Typed flags override matching keys.                                           |
| `--title`       | `string` | ❌        | Chart title                                                                                        |
| `--description` | `string` | ❌        | Optional chart description                                                                         |
| `--chart-type`  | `enum`   | ❌        | `table`, `number`, `funnel`, `bar`, `line`, `area`, `pie`, `stacked`, `user_paths`, or `retention` |
| `--query`       | `string` | ❌        | SQL query for SQL-backed charts                                                                    |
| `--x-axis`      | `string` | ❌        | Column used as the x-axis                                                                          |
| `--y-axis`      | `string` | ❌        | Comma-separated or JSON array of y-axis columns                                                    |
| `--group-by`    | `string` | ❌        | Column used to group or stack series                                                               |
| `--steps`       | `string` | ❌        | JSON array of funnel step objects                                                                  |
| `--settings`    | `string` | ❌        | JSON chart settings. User Paths require `anchors`; retention requires an `entryFilter` key.        |

Provide either `--body` or typed chart fields such as `--title`, `--chart-type`, and `--query`.

### Examples

```bash theme={null}
# Create a line chart from typed flags
formo charts create \
  --board-id board_abc123 \
  --title "Daily active users" \
  --chart-type line \
  --query "SELECT toDate(timestamp) AS date, countDistinct(address) AS users FROM events GROUP BY date ORDER BY date" \
  --x-axis date \
  --y-axis users

# Create from raw JSON
formo charts create \
  --board-id board_abc123 \
  --body '{"title":"Recent events","chart_type":"table","query":"SELECT * FROM events LIMIT 10"}'

# Create an open-ended User Paths chart; omit --query
formo charts create \
  --board-id board_abc123 \
  --title "Post-connect paths" \
  --chart-type user_paths \
  --settings '{"anchors":[{"type":"event","event":"connect"}],"maxSteps":5,"nodesPerStep":3}'
```

***

## `formo charts update <chartId>`

Update an existing chart. You can pass partial typed fields; the CLI fetches the current chart and sends the full body required by the API.

<Note>
  Requires `boards:write` scope on your API key.
</Note>

```bash theme={null}
formo charts update chart_abc123 --board-id board_abc123 --title "Updated chart name"
```

The same typed options as `create` are available.

***

## `formo charts move <chartId>`

Move a chart to another board.

<Note>
  Requires `boards:write` scope on your API key.
</Note>

```bash theme={null}
formo charts move chart_abc123 --board-id source_board --target-board-id target_board
```

***

## `formo charts duplicate <chartId>`

Duplicate a chart within its board. The CLI returns the new chart ID.

<Note>
  Requires `boards:write` scope on your API key.
</Note>

```bash theme={null}
formo charts duplicate chart_abc123 --board-id board_abc123
```

***

## `formo charts reorder`

Reorder charts in a board.

<Note>
  Requires `boards:write` scope on your API key.
</Note>

```bash theme={null}
formo charts reorder --board-id board_abc123 --chart-ids chart_a,chart_b,chart_c
```

`--chart-ids` may be comma-separated text or a JSON array.

***

## `formo charts delete <chartId>`

Delete a chart.

<Note>
  Requires `boards:write` scope on your API key.
</Note>

```bash theme={null}
formo charts delete chart_abc123 --board-id board_abc123
```

<Warning>
  Deleting a chart is permanent.
</Warning>