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 addAdd or replace a hierarchy filter dcy widget filter removeRemove a hierarchy filter dcy widget filter set-dateSet a widget’s date range filter dcy widget intensity groupsList intensity metric groups dcy widget intensity addAdd an intensity measure dcy widget intensity removeRemove an intensity measure
dcy widget list < project-i d >
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-i d > # JSON output dcy widget list < project-i d > --format json | jq '.[].name'
View a widget’s details and configuration:
dcy widget show < project-i d > < widget-i d >
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-onlyfalsePrint only the raw config JSON (useful for piping) --org— Organization ID override
# Dump config for editing dcy widget show < project-i d > < widget-i d > --config-only > widget-config.json # Short alias dcy widget get < project-i d > < widget-i d >
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-i d > \ --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-i d > \ --name "Custom Widget" \ --config widget.json
Flags Flag Short Default Description --name-n— Widget name (required ) --type-tpivotTableWidget 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 pivotTablePivot table (default) pivotBarChartBar chart (pivot) pivotPieChartPie chart (pivot) pivotLineChartLine chart (pivot) pivotAreaChartArea chart (pivot) tableFlat table barChartBar chart singleValueSingle KPI value
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-i d > < widget-i d > --name "New Name" # Change date range dcy widget update < project-i d > < widget-i d > --start 2025-01-01 --end 2025-12-31 # Replace entire config from file dcy widget update < project-i d > < widget-i d > --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-i d > < widget-i d > "New Name"
dcy widget delete < project-i d > < widget-i d >
Output:
Delete widget "Emissions by Scope" (550e8400-...)? [y/N] widget deleted: Emissions by Scope (550e8400-...)
Flags Flag Short Default Description --yes-yfalseSkip 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-i d > < widget-i d >
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-i d > < widget-i d > --csv
Write to File dcy widget results < project-i d > < widget-i d > --csv --out results.csv
Flags Flag Default Description --csvfalseOutput 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-i d > < widget-i d > | jq '.rows' # Export CSV for spreadsheet analysis dcy widget results < project-i d > < widget-i d > --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:
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.
Filter Options List the selectable filter values for a widget’s category (used to build filter add commands):
dcy widget filter-options < project-i d > < widget-i d >
Returns JSON with available hierarchies and their possible values.
Filters Add or Replace a Hierarchy Filter dcy widget filter add < project-i d > < widget-i d > \ --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-i d > < widget-i d > --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-i d > < widget-i d > \ --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-i d > < widget-i d > \ --numerator co2_eq:sum \ --group < group-i d >
Flags Flag Default Description --numerator— Numerator measure as id:agg[:unit] (required ) --group— Intensity metric group UUID (required ) --operationdivideOperation: divide, multiply, add, subtract --label— Display label for the intensity measure --org— Organization ID override
Remove Intensity Measure dcy widget intensity remove < project-i d > < widget-i d > --group < group-i d >
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-i d > < widget-i d > --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-i d > < widget-i d > \ --numerator co2_eq:sum \ --group < revenue-group-i d > \ --label "tCO2e per EUR"
Filter by Scope and Facility # Filter to Scope 1 and 2 only dcy widget filter add < project-i d > < widget-i d > \ --hierarchy scope \ --values "scope 1,scope 2" # Check updated results dcy widget results < project-i d > < widget-i d > --csv
# 1. Export existing config dcy widget show < project-i d > < widget-i d > --config-only > template.json # 2. Create new widget with same config dcy widget create < project-i d > --name "Variant A" --config template.json
Aliases Command Alias dcy widget listdcy widget lsdcy widget showdcy widget getdcy widget deletedcy 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