Intensity Metrics

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

Overview

An intensity metric expresses emissions per unit of activity — tCO₂e per litre bottled, per unit produced, per €M of revenue. It has two parts:

A group defines the denominator: a free-text unit (what you divide by) and the emission scopes that make up the numerator.
Each record inside the group holds one period’s quantity. The API returns the resulting value (emissions ÷ quantity) and the delta against the previous period.

The numerator is the whole organization’s emissions. A single-site volume loaded onto a multi-site organization produces a misleading intensity — put the volume on the organization whose emissions actually match it.

Available Commands

Command	Description
`dcy intensity group list`	List intensity metric groups
`dcy intensity group show <id>`	Show one group
`dcy intensity group create`	Create a group (unit + scopes)
`dcy intensity group edit <id>`	Update a group’s unit, name or scopes
`dcy intensity group delete <id>`	Delete a group and all its records
`dcy intensity list <group-id>`	List a group’s records with value and delta
`dcy intensity show <metric-id>`	Show one record
`dcy intensity create`	Add a period’s production volume
`dcy intensity edit <metric-id>`	Update a record’s quantity
`dcy intensity delete <metric-id>`	Delete a record
`dcy intensity org-values`	Every intensity value across all groups

List Groups

dcy intensity group list

Output:

Showing 3 of 3 intensity metric group(s) in Acme Corp
550e8400-... | Millón Litros producidos | scopes=1,2,3 | simple   | active
661f9511-... | Tons sold                | scopes=1,2,3 | simple   | active
772a0622-... | Revenue (€M)             | scopes=1,2   | grouping | active

simple groups hold their own records. grouping groups aggregate child organizations’ groups.

Flags

Flag	Short	Default	Description
`--filter-by`	—	—	Filter groups by name or unit
`--page`	—	`1`	Page number
`--size`	—	`50`	Page size
`--org`	—	—	Organization ID override

Create a Group

dcy intensity group create --unit "Millón Litros producidos" --scopes 1,2,3

Output:

intensity metric group created: Millón Litros producidos (550e8400-...)

Flags

Flag	Short	Default	Description
`--unit`	`-u`	—	Required. Unit shown in the app
`--name`	—	value of `--unit`	Internal name
`--scopes`	—	`1,2,3`	Scopes in the numerator
`--grouping`	—	`false`	Aggregate child organizations’ groups
`--org`	—	—	Organization ID override

--scopes accepts only the combinations the API allows: 1, 2, 3, 1,2, 2,3, 1,2,3. Anything else (e.g. 1,3) is rejected before the request is sent.

Add a Period

dcy intensity create \
  --group 550e8400-... \
  --start 2025-01-01 \
  --end 2025-12-31 \
  --quantity 224.058

Output:

intensity record created: 2025-01-01 -> 2025-12-31, quantity 224.058 (value 0.42)

Flags

Flag	Short	Default	Description
`--group`	`-g`	—	Required. Intensity metric group ID
`--start`	—	—	Required. Period start (`YYYY-MM-DD`)
`--end`	—	—	Required. Period end (`YYYY-MM-DD`)
`--quantity`	`-q`	—	Required. Volume in the group’s unit, greater than 0
`--org`	—	—	Organization ID override

Periods may not overlap other records in the same group, so a group holds either annual records or monthly ones — never both. An overlapping period is rejected with INTENSITY_METRICS_ALEADY_EXISTS_IN_THIS_PERIOD.

Dates are inclusive calendar dates, interpreted as UTC.

List Records in a Group

dcy intensity list 550e8400-...

Output:

Showing 12 of 12 intensity record(s)
a1b2c3d4-... | 2025-01-01 -> 2025-01-31 | quantity=16.22 | value=21.87 | delta=0
b2c3d4e5-... | 2025-02-01 -> 2025-02-28 | quantity=15.12 | value=20.03 | delta=-0.08

Flags

Flag	Short	Default	Description
`--page`	—	`1`	Page number
`--size`	—	`50`	Page size
`--org`	—	—	Organization ID override

Update a Quantity

dcy intensity edit a1b2c3d4-... --quantity 225.1

Periods are immutable — delete the record and create a new one to move it.

Delete

dcy intensity delete a1b2c3d4-... --yes
dcy intensity group delete 550e8400-... --yes

Deleting a group removes every record inside it, so the periods it held stop contributing to dashboards and reports. Both commands prompt for confirmation unless --yes is passed.

All Values at Once

dcy intensity org-values --start 2025-01-01 --end 2025-12-31

Output:

Showing 13 intensity metric value(s)
Millón Litros producidos | 2025-01-01 -> 2025-12-31 | value=0.42 | delta=-3.1
Tons sold                | 2025-01-01 -> 2025-12-31 | value=134.67 | delta=0

Flags

Flag	Short	Default	Description
`--start`	—	—	Period start (`YYYY-MM-DD`), must be paired with `--end`
`--end`	—	—	Period end (`YYYY-MM-DD`), must be paired with `--start`
`--org`	—	—	Organization ID override

This summary endpoint returns values and deltas but not the underlying quantities. Use dcy intensity list <group-id> when you need the volumes.

Typical Workflows

Load a Year of Monthly Volumes

Create the group once, then loop the periods from a CSV of start,end,quantity:

GROUP=$(dcy intensity group create \
  --unit "Millón Litros producidos" --scopes 1,2,3 --format json | jq -r '.id')

while IFS=, read -r start end quantity; do
  dcy intensity create --group "$GROUP" \
    --start "$start" --end "$end" --quantity "$quantity"
done < volumes.csv

volumes.csv

2025-01-01,2025-01-31,16.22
2025-02-01,2025-02-28,15.12
2025-03-01,2025-03-31,17.51

Load the Same Metric Across a Group of Companies

Each subsidiary needs its own group, because the intensity is computed from that organization’s own emissions:

for org in 03684b0b-... 8bf800de-... 1568af1d-...; do
  gid=$(dcy intensity group create --org "$org" \
    --unit "Millón Litros producidos" --scopes 1,2,3 --format json | jq -r '.id')
  echo "$org -> $gid"
done

Audit What’s Loaded

# Every value across all groups, as JSON
dcy intensity org-values --format json | jq -r '.[] | "\(.unit)\t\(.start_date)\t\(.value)"'

# Groups with no records yet
for gid in $(dcy intensity group list --format json | jq -r '.[].id'); do
  n=$(dcy intensity list "$gid" --format json | jq 'length')
  [ "$n" = "0" ] && echo "empty: $gid"
done

Aliases

Command	Alias
`dcy intensity group list`	`dcy intensity group ls`
`dcy intensity list`	`dcy intensity ls`
`dcy intensity delete`	`dcy intensity rm`
`dcy intensity group delete`	`dcy intensity group rm`

Limitations

Parent roll-up cannot be configured from the CLI. Groups can be created with --grouping, but linking a parent grouping to its children’s groups is not exposed by the API yet.
No bulk import command. Load periods with a shell loop as shown above.

Next Steps

Widgets

Add intensity measures to dashboard widgets

Organizations

Inspect the org tree to pick the right organization

Projects

Reporting projects that surface intensity metrics

MCP Intensity Tools

The same operations from an AI assistant

Getting Started

Commands

Examples

Overview

Available Commands

List Groups

Flags

Create a Group

Flags

Add a Period

Flags

List Records in a Group

Flags

Update a Quantity

Delete

All Values at Once

Flags

Typical Workflows

Load a Year of Monthly Volumes

Load the Same Metric Across a Group of Companies

Audit What’s Loaded

Aliases

Limitations

Next Steps

Widgets

Organizations

Projects

MCP Intensity Tools

​Overview

​Available Commands

​List Groups

​Flags

​Create a Group

​Flags

​Add a Period

​Flags

​List Records in a Group

​Flags

​Update a Quantity

​Delete

​All Values at Once

​Flags

​Typical Workflows

​Load a Year of Monthly Volumes

​Load the Same Metric Across a Group of Companies

​Audit What’s Loaded

​Aliases

​Limitations

​Next Steps

Widgets

Organizations

Projects

MCP Intensity Tools

Overview

Available Commands

List Groups

Flags

Create a Group

Flags

Add a Period

Flags

List Records in a Group

Flags

Update a Quantity

Delete

All Values at Once

Flags

Typical Workflows

Load a Year of Monthly Volumes

Load the Same Metric Across a Group of Companies

Audit What’s Loaded

Aliases

Limitations

Next Steps