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

# Widgets

> Manage project dashboard widgets — pivot tables, charts, filters, and intensity measures

<Note>
  **Early Access** - The Dcycle CLI is currently available for enterprise customers.
  [Contact us](/docs/support) to learn more about access.
</Note>

## Overview

Widgets are data visualizations on a project's dashboard. Each widget is a pivot table or chart that slices emissions data by dimensions (rows/columns), aggregates measures, and applies filters. The CLI lets you create, configure, and query widgets programmatically.

### Available Commands

| Command                                              | Description                            |
| ---------------------------------------------------- | -------------------------------------- |
| `dcy widget list <project-id>`                       | List widgets in a project dashboard    |
| `dcy widget show <project-id> <widget-id>`           | Show a widget's details and config     |
| `dcy widget create <project-id>`                     | Create a widget                        |
| `dcy widget update <project-id> <widget-id>`         | Update a widget's config and/or name   |
| `dcy widget rename <project-id> <widget-id> <name>`  | Rename a widget                        |
| `dcy widget delete <project-id> <widget-id>`         | Delete a widget                        |
| `dcy widget results <project-id> <widget-id>`        | Compute a widget's results             |
| `dcy widget catalog [category]`                      | Show available dimensions and measures |
| `dcy widget filter-options <project-id> <widget-id>` | List selectable filter values          |
| `dcy widget filter add`                              | Add or replace a hierarchy filter      |
| `dcy widget filter remove`                           | Remove a hierarchy filter              |
| `dcy widget filter set-date`                         | Set a widget's date range filter       |
| `dcy widget intensity groups`                        | List intensity metric groups           |
| `dcy widget intensity add`                           | Add an intensity measure               |
| `dcy widget intensity remove`                        | Remove an intensity measure            |

***

## List Widgets

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget list <project-id>
```

Output:

```
Showing 3 widget(s)
550e8400-...	pivotTable	Emissions by Scope
661f9511-...	pivotBarChart	Annual Trend
772a0622-...	pivotPieChart	Category Breakdown
```

### Flags

| Flag    | Default | Description              |
| ------- | ------- | ------------------------ |
| `--org` | —       | Organization ID override |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Short alias
dcy widget ls <project-id>

# JSON output
dcy widget list <project-id> --format json | jq '.[].name'
```

***

## Show Widget

View a widget's details and configuration:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget show <project-id> <widget-id>
```

Output:

```
ID: 550e8400-...
Name: Emissions by Scope
Type: pivotTable
Category: carbon_footprint
Config:
{
  "category": "carbon_footprint",
  "rows": ["scope"],
  "columns": ["year"],
  ...
}
```

### Flags

| Flag            | Default | Description                                        |
| --------------- | ------- | -------------------------------------------------- |
| `--config-only` | `false` | Print only the raw config JSON (useful for piping) |
| `--org`         | —       | Organization ID override                           |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Dump config for editing
dcy widget show <project-id> <widget-id> --config-only > widget-config.json

# Short alias
dcy widget get <project-id> <widget-id>
```

***

## Create Widget

Create a widget in a project dashboard. Provide the full config as a JSON file, or build a pivot widget from flags:

### From Flags

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget create <project-id> \
  --name "Emissions by Scope" \
  --category carbon_footprint \
  --rows scope \
  --columns year \
  --measure co2_eq:sum \
  --start 2024-01-01 \
  --end 2024-12-31
```

### From Config File

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget create <project-id> \
  --name "Custom Widget" \
  --config widget.json
```

### Flags

| Flag                | Short | Default      | Description                                                  |
| ------------------- | ----- | ------------ | ------------------------------------------------------------ |
| `--name`            | `-n`  | —            | Widget name (**required**)                                   |
| `--type`            | `-t`  | `pivotTable` | Widget chart type (see table below)                          |
| `--category`        | —     | —            | Pivot category (e.g. `carbon_footprint`, `wastes`, `energy`) |
| `--rows`            | —     | —            | Row dimensions, comma-separated                              |
| `--columns`         | —     | —            | Column dimensions, comma-separated                           |
| `--measure`         | —     | —            | Measure as `id:agg_fn[:unit]` (repeatable)                   |
| `--start`           | —     | —            | Date range start (YYYY-MM-DD)                                |
| `--end`             | —     | —            | Date range end (YYYY-MM-DD)                                  |
| `--year-type`       | —     | —            | Year type: `natural` or `fiscal`                             |
| `--emission-method` | —     | —            | Emission method: `market` or `location`                      |
| `--sort-measure`    | —     | —            | Sort rows by `measure_id[:asc\|desc]`                        |
| `--config`          | —     | —            | Path to a JSON file with the full widget config              |
| `--org`             | —     | —            | Organization ID override                                     |

### Widget Types

| Type             | Description           |
| ---------------- | --------------------- |
| `pivotTable`     | Pivot table (default) |
| `pivotBarChart`  | Bar chart (pivot)     |
| `pivotPieChart`  | Pie chart (pivot)     |
| `pivotLineChart` | Line chart (pivot)    |
| `pivotAreaChart` | Area chart (pivot)    |
| `table`          | Flat table            |
| `barChart`       | Bar chart             |
| `singleValue`    | Single KPI value      |

### Measure Format

Measures are specified as `id:aggregation[:unit]`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Simple measure
--measure co2_eq:sum

# With unit
--measure quantity:sum:kilogram_(kg)

# Multiple measures
--measure co2_eq:sum --measure quantity:sum
```

***

## Update Widget

Update a widget's config, name, or type. Only the flags you pass are changed:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Change name
dcy widget update <project-id> <widget-id> --name "New Name"

# Change date range
dcy widget update <project-id> <widget-id> --start 2025-01-01 --end 2025-12-31

# Replace entire config from file
dcy widget update <project-id> <widget-id> --config updated-widget.json
```

The update command accepts the same flags as create. When using `--config`, do not combine it with individual config flags (`--category`, `--rows`, etc.).

***

## Rename Widget

A shortcut for renaming:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget rename <project-id> <widget-id> "New Name"
```

***

## Delete Widget

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget delete <project-id> <widget-id>
```

Output:

```
Delete widget "Emissions by Scope" (550e8400-...)? [y/N]
widget deleted: Emissions by Scope (550e8400-...)
```

### Flags

| Flag    | Short | Default | Description              |
| ------- | ----- | ------- | ------------------------ |
| `--yes` | `-y`  | `false` | Skip confirmation prompt |
| `--org` | —     | —       | Organization ID override |

<Note>
  The last widget in a dashboard cannot be deleted — the backend does not allow emptying a dashboard.
</Note>

***

## Results

Compute a widget's results the same way the dashboard does:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget results <project-id> <widget-id>
```

Output is the calculated pivot tree as JSON.

### CSV Export

Export the raw dataset as CSV instead of the calculated tree:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget results <project-id> <widget-id> --csv
```

### Write to File

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget results <project-id> <widget-id> --csv --out results.csv
```

### Flags

| Flag    | Default | Description                                   |
| ------- | ------- | --------------------------------------------- |
| `--csv` | `false` | Output the raw dataset as CSV instead of JSON |
| `--out` | —       | Write output to a file instead of stdout      |
| `--org` | —       | Organization ID override                      |

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# JSON results piped to jq
dcy widget results <project-id> <widget-id> | jq '.rows'

# Export CSV for spreadsheet analysis
dcy widget results <project-id> <widget-id> --csv --out emissions-2024.csv

# Compare two widgets
diff <(dcy widget results <pid> <wid-1> --csv) <(dcy widget results <pid> <wid-2> --csv)
```

***

## Catalog

Show available pivot dimensions (hierarchies), measures, and units. Use this to discover valid values for `--category`, `--rows`, `--columns`, and `--measure`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget catalog
```

Output:

```
available categories:
  carbon_footprint
  energy
  wastes
  purchases
  logistics
```

### Drill Into a Category

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget catalog carbon_footprint
```

Returns JSON with the category's available rows, columns, measures, and filters.

***

## Filter Options

List the selectable filter values for a widget's category (used to build `filter add` commands):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget filter-options <project-id> <widget-id>
```

Returns JSON with available hierarchies and their possible values.

***

## Filters

### Add or Replace a Hierarchy Filter

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget filter add <project-id> <widget-id> \
  --hierarchy scope \
  --values "scope 1,scope 2"
```

If a filter on the same hierarchy already exists, it is replaced.

#### Flags

| Flag          | Default | Description                                   |
| ------------- | ------- | --------------------------------------------- |
| `--hierarchy` | —       | Hierarchy ID to filter on (**required**)      |
| `--values`    | —       | Comma-separated values to keep (**required**) |
| `--org`       | —       | Organization ID override                      |

### Remove a Hierarchy Filter

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget filter remove <project-id> <widget-id> --hierarchy scope
```

#### Flags

| Flag          | Default | Description                           |
| ------------- | ------- | ------------------------------------- |
| `--hierarchy` | —       | Hierarchy ID to remove (**required**) |
| `--org`       | —       | Organization ID override              |

### Set Date Range

Replace (or add) the widget's date filter:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget filter set-date <project-id> <widget-id> \
  --start 2024-01-01 \
  --end 2024-12-31
```

#### Flags

| Flag      | Default | Description                          |
| --------- | ------- | ------------------------------------ |
| `--start` | —       | Start date YYYY-MM-DD (**required**) |
| `--end`   | —       | End date YYYY-MM-DD (**required**)   |
| `--org`   | —       | Organization ID override             |

***

## Intensity Measures

Intensity measures divide an emission measure by an organizational metric (revenue, FTE, m², etc.) to produce emission intensity values.

### List Intensity Groups

List the organization's available intensity metric groups:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget intensity groups
```

Output:

```
Showing 3 intensity metric group(s)
550e8400-...	Revenue (EUR)	EUR	scopes=1,2,3
661f9511-...	FTE count	FTE	scopes=1,2,3
772a0622-...	Floor area	m²	scopes=1,2
```

### Add Intensity Measure

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget intensity add <project-id> <widget-id> \
  --numerator co2_eq:sum \
  --group <group-id>
```

#### Flags

| Flag          | Default  | Description                                         |
| ------------- | -------- | --------------------------------------------------- |
| `--numerator` | —        | Numerator measure as `id:agg[:unit]` (**required**) |
| `--group`     | —        | Intensity metric group UUID (**required**)          |
| `--operation` | `divide` | Operation: `divide`, `multiply`, `add`, `subtract`  |
| `--label`     | —        | Display label for the intensity measure             |
| `--org`       | —        | Organization ID override                            |

### Remove Intensity Measure

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy widget intensity remove <project-id> <widget-id> --group <group-id>
```

#### Flags

| Flag      | Default | Description                                          |
| --------- | ------- | ---------------------------------------------------- |
| `--group` | —       | Intensity metric group UUID to remove (**required**) |
| `--org`   | —       | Organization ID override                             |

***

## Typical Workflows

### Create a Dashboard from Scratch

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Find the project
PROJECT=$(dcy project list --format json | jq -r '.[0].id')

# 2. Discover available dimensions
dcy widget catalog carbon_footprint | jq '.rows'

# 3. Create a widget
WIDGET=$(dcy widget create "$PROJECT" \
  --name "Emissions by Scope" \
  --category carbon_footprint \
  --rows scope \
  --columns year \
  --measure co2_eq:sum \
  --start 2024-01-01 \
  --end 2024-12-31 \
  --format json | jq -r '.id')

# 4. View results
dcy widget results "$PROJECT" "$WIDGET"
```

### Export Data for Analysis

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Export all widget data as CSV
dcy widget results <project-id> <widget-id> --csv --out emissions.csv

# Open in spreadsheet
open emissions.csv
```

### Add Emission Intensity

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. List available intensity groups
dcy widget intensity groups --format json | jq '.[] | {id, name, unit}'

# 2. Add intensity measure
dcy widget intensity add <project-id> <widget-id> \
  --numerator co2_eq:sum \
  --group <revenue-group-id> \
  --label "tCO2e per EUR"
```

### Filter by Scope and Facility

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Filter to Scope 1 and 2 only
dcy widget filter add <project-id> <widget-id> \
  --hierarchy scope \
  --values "scope 1,scope 2"

# Check updated results
dcy widget results <project-id> <widget-id> --csv
```

### Clone a Widget's Config

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Export existing config
dcy widget show <project-id> <widget-id> --config-only > template.json

# 2. Create new widget with same config
dcy widget create <project-id> --name "Variant A" --config template.json
```

***

## Aliases

| Command             | Alias            |
| ------------------- | ---------------- |
| `dcy widget list`   | `dcy widget ls`  |
| `dcy widget show`   | `dcy widget get` |
| `dcy widget delete` | `dcy widget rm`  |

## Next Steps

<CardGroup cols={2}>
  <Card title="Projects" icon="clipboard-list" href="/cli/projects">
    Create and manage the projects that contain widgets
  </Card>

  <Card title="Facilities" icon="warehouse" href="/cli/facilities">
    Manage physical locations used in widget dimensions
  </Card>

  <Card title="Invoices" icon="file-invoice" href="/cli/invoices">
    Manage energy invoices that feed widget data
  </Card>

  <Card title="Custom Emission Factors" icon="sliders" href="/cli/custom-ef">
    Upload factors that influence widget calculations
  </Card>
</CardGroup>