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

# Intensity Metrics

> Manage production volumes that emissions are divided by, to track emissions per unit

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

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

<Warning>
  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.
</Warning>

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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              |

<Note>
  `--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.
</Note>

***

## Add a Period

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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                                 |

<Warning>
  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`.
</Warning>

Dates are inclusive calendar dates, interpreted as UTC.

***

## List Records in a Group

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy intensity edit a1b2c3d4-... --quantity 225.1
```

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

***

## Delete

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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                                 |

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

***

## Typical Workflows

### Load a Year of Monthly Volumes

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```

```text title="volumes.csv" theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

<CardGroup cols={2}>
  <Card title="Widgets" icon="chart-line" href="/cli/widgets">
    Add intensity measures to dashboard widgets
  </Card>

  <Card title="Organizations" icon="sitemap" href="/cli/organizations">
    Inspect the org tree to pick the right organization
  </Card>

  <Card title="Projects" icon="folder" href="/cli/projects">
    Reporting projects that surface intensity metrics
  </Card>

  <Card title="MCP Intensity Tools" icon="robot" href="/mcp/intensity-metrics">
    The same operations from an AI assistant
  </Card>
</CardGroup>