Widgets - Dcycle Platform Docs

Early Access - The Dcycle CLI is currently available for enterprise customers. Contact us to learn more about access.

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

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

# Short alias
dcy widget ls <project-id>

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

View a widget’s details and configuration:

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

# 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 a widget in a project dashboard. Provide the full config as a JSON file, or build a pivot widget from flags:

From Flags

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

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

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]:

# Simple measure
--measure co2_eq:sum

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

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

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

# 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.).

A shortcut for renaming:

dcy widget rename <project-id> <widget-id> "New Name"

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

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

Results

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

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:

dcy widget results <project-id> <widget-id> --csv

Write to File

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

# 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:

dcy widget catalog

Output:

available categories:
  carbon_footprint
  energy
  wastes
  purchases
  logistics

Drill Into a Category

dcy widget catalog carbon_footprint

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

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

dcy widget filter-options <project-id> <widget-id>

Returns JSON with available hierarchies and their possible values.

Filters

Add or Replace a Hierarchy Filter

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

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:

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:

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

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

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

# 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

# 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

# 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

# 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

# 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

Projects

Create and manage the projects that contain widgets

Facilities

Manage physical locations used in widget dimensions

Invoices

Manage energy invoices that feed widget data

Custom Emission Factors

Upload factors that influence widget calculations

​Overview

​Available Commands

​List Widgets

​Flags

​Show Widget

​Flags

​Create Widget

​From Flags

​From Config File

​Flags

​Widget Types

​Measure Format

​Update Widget

​Rename Widget

​Delete Widget

​Flags

​Results

​CSV Export

​Write to File

​Flags

​Examples

​Catalog

​Drill Into a Category

​Filter Options

​Filters

​Add or Replace a Hierarchy Filter

​Flags

​Remove a Hierarchy Filter

​Flags

​Set Date Range

​Flags

​Intensity Measures

​List Intensity Groups

​Add Intensity Measure

​Flags

​Remove Intensity Measure

​Flags

​Typical Workflows

​Create a Dashboard from Scratch

​Export Data for Analysis

​Add Emission Intensity

​Filter by Scope and Facility

​Clone a Widget’s Config

​Aliases

​Next Steps

Projects

Facilities

Invoices

Custom Emission Factors

Overview

Available Commands

List Widgets

Flags

Show Widget

Flags

Create Widget

From Flags

From Config File

Flags

Widget Types

Measure Format

Update Widget

Rename Widget

Delete Widget

Flags

Results

CSV Export

Write to File

Flags

Examples

Catalog

Drill Into a Category

Filter Options

Filters

Add or Replace a Hierarchy Filter

Flags

Remove a Hierarchy Filter

Flags

Set Date Range

Flags

Intensity Measures

List Intensity Groups

Add Intensity Measure

Flags

Remove Intensity Measure

Flags

Typical Workflows

Create a Dashboard from Scratch

Export Data for Analysis

Add Emission Intensity

Filter by Scope and Facility

Clone a Widget’s Config

Aliases

Next Steps