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

# Charts

> Define and manage saved charts. Charts are visualizations that aggregate metrics over time with bucketing, filters, and groupings.

## Schema introspection

Every command below with arguments supports two read-only flags for tooling and AI agents:

* `--show-file-schema`: print the JSON Schema for the full request object (the format `--filename` accepts).
* `--show-argument-schema <flag-name>`: print the JSON Schema for one argument's value. Pass the kebab flag name **without** the leading `--` (e.g. `name`, not `--name`).

Both write pure JSON to stdout and never call the API. They cannot be combined with any other command-specific flag.

## `list`

List charts

Retrieve all charts in the current scope.

### Usage

```sh theme={null}
honeyhive charts list
```

## `create`

Create a new chart

### Usage

```sh theme={null}
honeyhive charts create [options]
```

### Options

| Flag            | Type   | Required | Description                                                                                |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `--metric`      | string | yes      | Name of the metric to visualize                                                            |
| `--name`        | string | yes      | Display name for the chart                                                                 |
| `--bucketing`   | string | no       | Time bucket granularity for aggregation Allowed: `minute`, `hour`, `day`, `week`, `month`. |
| `--date-range`  | json   | no       | Time range to query                                                                        |
| `--description` | string | no       | Description of what the chart shows                                                        |
| `--func`        | string | no       | Aggregation function to apply (e.g. sum, avg, median, min, max)                            |
| `--group-by`    | string | no       | Field to group results by                                                                  |
| `--owner-id`    | string | no       | ID of the user who owns this chart                                                         |
| `--query`       | json   | no       | Filters to apply to the chart data                                                         |

Also supports `--show-file-schema`, `--show-argument-schema <flag-name>`, and `--filename`. See [Schema introspection](#schema-introspection) for details.

## `get`

Get a chart

Retrieve a single chart by id.

### Usage

```sh theme={null}
honeyhive charts get [options]
```

### Options

| Flag         | Type   | Required | Description                                    |
| ------------ | ------ | -------- | ---------------------------------------------- |
| `--chart-id` | string | yes      | The unique identifier of the chart to retrieve |

Also supports `--show-file-schema`, `--show-argument-schema <flag-name>`, and `--filename`. See [Schema introspection](#schema-introspection) for details.

## `update`

Update a chart

Update a chart's editable fields. Only fields included in the request body are modified.

### Usage

```sh theme={null}
honeyhive charts update [options]
```

### Options

| Flag            | Type   | Required | Description                                                                                |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `--chart-id`    | string | yes      | The unique identifier of the chart to update                                               |
| `--bucketing`   | string | no       | Time bucket granularity for aggregation Allowed: `minute`, `hour`, `day`, `week`, `month`. |
| `--date-range`  | json   | no       | Time range to query                                                                        |
| `--description` | string | no       | Description of what the chart shows                                                        |
| `--func`        | string | no       | Aggregation function to apply (e.g. sum, avg, median, min, max)                            |
| `--group-by`    | string | no       | Field to group results by                                                                  |
| `--metric`      | string | no       | Name of the metric to visualize                                                            |
| `--name`        | string | no       | Display name for the chart                                                                 |
| `--owner-id`    | string | no       | ID of the user who owns this chart                                                         |
| `--query`       | json   | no       | Filters to apply to the chart data                                                         |

Also supports `--show-file-schema`, `--show-argument-schema <flag-name>`, and `--filename`. See [Schema introspection](#schema-introspection) for details.

## `delete`

Delete a chart

### Usage

```sh theme={null}
honeyhive charts delete [options]
```

### Options

| Flag         | Type   | Required | Description                                  |
| ------------ | ------ | -------- | -------------------------------------------- |
| `--chart-id` | string | yes      | The unique identifier of the chart to delete |

Also supports `--show-file-schema`, `--show-argument-schema <flag-name>`, and `--filename`. See [Schema introspection](#schema-introspection) for details.