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

# Dashboards

> Create and manage dashboards and widgets with the Coval CLI

Dashboards provide customizable views for monitoring evaluation results. Each dashboard contains widgets that display charts, tables, or text.

## List Dashboards

```bash theme={null}
coval dashboards list [OPTIONS]
```

| Option        | Type   | Default | Description       |
| ------------- | ------ | ------- | ----------------- |
| `--filter`    | string | —       | Filter expression |
| `--page-size` | number | 50      | Results per page  |
| `--order-by`  | string | —       | Sort order        |

**Output columns:** ID, NAME, CREATED, UPDATED

```bash theme={null}
coval dashboards list
```

## Get Dashboard

```bash theme={null}
coval dashboards get <dashboard_id>
```

| Argument       | Type   | Required | Description      |
| -------------- | ------ | -------- | ---------------- |
| `dashboard_id` | string | **Yes**  | The dashboard ID |

```bash theme={null}
coval dashboards get db_abc123
```

## Create Dashboard

```bash theme={null}
coval dashboards create [OPTIONS]
```

| Option          | Type    | Required | Description                                                                                                                                                                                      |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--name`        | string  | **Yes**  | Display name                                                                                                                                                                                     |
| `--description` | string  | No       | Free-text description                                                                                                                                                                            |
| `--favorite`    | boolean | No       | Pass `--favorite true` to mark the dashboard as a favorite, `--favorite false` to unmark it                                                                                                      |
| `--default`     | boolean | No       | Pass `--default true` to make this the organization's default dashboard (unsets any other default). If omitted, the first dashboard created in an organization automatically becomes the default |
| `--position`    | number  | No       | Ordering position (`>= 0`). Omit to append to the end                                                                                                                                            |
| `--config`      | string  | No       | Free-form JSON config: a JSON string or `@filepath`                                                                                                                                              |

```bash theme={null}
coval dashboards create \
  --name "Production Metrics" \
  --description "Latency and quality overview" \
  --default true
```

## Update Dashboard

```bash theme={null}
coval dashboards update <dashboard_id> [OPTIONS]
```

| Argument       | Type   | Required | Description                |
| -------------- | ------ | -------- | -------------------------- |
| `dashboard_id` | string | **Yes**  | The dashboard ID to update |

| Option          | Type    | Description                                                                                        |
| --------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `--name`        | string  | New display name                                                                                   |
| `--description` | string  | New description (empty string clears it)                                                           |
| `--favorite`    | boolean | Pass `--favorite true` to mark the dashboard as a favorite, `--favorite false` to unmark it        |
| `--default`     | boolean | Pass `--default true` to make this the organization's default dashboard (unsets any other default) |
| `--position`    | number  | New ordering position (`>= 0`)                                                                     |
| `--config`      | string  | Replacement JSON config or `@filepath`. Fully replaces the stored config                           |

```bash theme={null}
# Rename and make this the default dashboard
coval dashboards update db_abc123 --name "Staging Metrics" --default true
```

<Note>
  PATCH semantics: omitted options are left unchanged. To clear a value, send an empty string for
  `--description` or an empty object (`--config '{}'`). Replacing `--config` overwrites any UI-managed
  keys such as saved date preferences.
</Note>

## Delete Dashboard

```bash theme={null}
coval dashboards delete <dashboard_id>
```

| Argument       | Type   | Required | Description                |
| -------------- | ------ | -------- | -------------------------- |
| `dashboard_id` | string | **Yes**  | The dashboard ID to delete |

```bash theme={null}
coval dashboards delete db_abc123
```

***

## Widgets

Widgets are visual components that live inside a dashboard. All widget commands are nested under `coval dashboards widgets`.

### List Widgets

```bash theme={null}
coval dashboards widgets list <dashboard_id> [OPTIONS]
```

| Argument       | Type   | Required | Description             |
| -------------- | ------ | -------- | ----------------------- |
| `dashboard_id` | string | **Yes**  | The parent dashboard ID |

| Option        | Type   | Default | Description      |
| ------------- | ------ | ------- | ---------------- |
| `--page-size` | number | 50      | Results per page |

**Output columns:** ID, NAME, TYPE, GRID, CREATED

```bash theme={null}
coval dashboards widgets list db_abc123
```

### Get Widget

```bash theme={null}
coval dashboards widgets get <dashboard_id> <widget_id>
```

| Argument       | Type   | Required | Description             |
| -------------- | ------ | -------- | ----------------------- |
| `dashboard_id` | string | **Yes**  | The parent dashboard ID |
| `widget_id`    | string | **Yes**  | The widget ID           |

```bash theme={null}
coval dashboards widgets get db_abc123 wgt_xyz789
```

### Create Widget

```bash theme={null}
coval dashboards widgets create <dashboard_id> [OPTIONS]
```

| Argument       | Type   | Required | Description             |
| -------------- | ------ | -------- | ----------------------- |
| `dashboard_id` | string | **Yes**  | The parent dashboard ID |

| Option     | Type   | Required | Description                                         |
| ---------- | ------ | -------- | --------------------------------------------------- |
| `--name`   | string | **Yes**  | Widget display name                                 |
| `--type`   | string | **Yes**  | Widget type (see below)                             |
| `--config` | string | No       | JSON config string or `@filepath` to read from file |
| `--grid-w` | number | No       | Grid width                                          |
| `--grid-h` | number | No       | Grid height                                         |
| `--grid-x` | number | No       | Grid X position                                     |
| `--grid-y` | number | No       | Grid Y position                                     |

### Widget Types

| Type    | Description                            |
| ------- | -------------------------------------- |
| `chart` | Line, bar, or area chart visualization |
| `table` | Tabular data display                   |
| `text`  | Static text or markdown content        |

```bash theme={null}
# Create a chart widget
coval dashboards widgets create db_abc123 \
  --name "Score Trends" \
  --type chart \
  --config '{"metric_id": "met_001"}' \
  --grid-w 6 \
  --grid-h 4

# Create a widget with config from a file
coval dashboards widgets create db_abc123 \
  --name "Detailed Report" \
  --type table \
  --config @widget-config.json
```

### Update Widget

```bash theme={null}
coval dashboards widgets update <dashboard_id> <widget_id> [OPTIONS]
```

| Argument       | Type   | Required | Description             |
| -------------- | ------ | -------- | ----------------------- |
| `dashboard_id` | string | **Yes**  | The parent dashboard ID |
| `widget_id`    | string | **Yes**  | The widget ID to update |

| Option     | Type   | Description                    |
| ---------- | ------ | ------------------------------ |
| `--name`   | string | New display name               |
| `--type`   | string | New widget type                |
| `--config` | string | New JSON config or `@filepath` |
| `--grid-w` | number | New grid width                 |
| `--grid-h` | number | New grid height                |
| `--grid-x` | number | New grid X position            |
| `--grid-y` | number | New grid Y position            |

```bash theme={null}
coval dashboards widgets update db_abc123 wgt_xyz789 \
  --grid-w 12 --grid-h 6
```

### Delete Widget

```bash theme={null}
coval dashboards widgets delete <dashboard_id> <widget_id>
```

| Argument       | Type   | Required | Description             |
| -------------- | ------ | -------- | ----------------------- |
| `dashboard_id` | string | **Yes**  | The parent dashboard ID |
| `widget_id`    | string | **Yes**  | The widget ID to delete |

```bash theme={null}
coval dashboards widgets delete db_abc123 wgt_xyz789
```