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

# Custom Emission Factors

> Upload organization-specific emission factors from CSV files

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

## Overview

Upload organization-specific emission factors to override standard database values. Custom factors improve accuracy when you have supplier-provided data. Factors are grouped by category and support both simple (CO2e only) and advanced (CO2 + CH4 + N2O) tags.

### Available Commands

| Command                            | Description                                    |
| ---------------------------------- | ---------------------------------------------- |
| `dcy custom-ef upload [file.csv]`  | Upload custom emission factors from CSV        |
| `dcy custom-ef delete-bulk <file>` | Bulk delete custom emission groups from a file |

***

## Generate Template

Download a CSV template with the required column format:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy custom-ef upload --template
```

Output:

```
template generated: custom_ef_template.csv
```

The template includes all supported columns with example data rows covering electricity, heat, and waste categories.

### Required Columns

| Column              | Description                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| `group_name`        | Name of the emission factor group                                                                 |
| `group_category`    | Category: `heat`, `recharge`, `process`, `water`, `electricity`, `vehicles`, `waste`, `purchases` |
| `group_ghg_type`    | GHG type: `0` or `1`                                                                              |
| `ef_name`           | Name of the individual emission factor                                                            |
| `unit_id`           | Unit UUID (use `dcy units list` to find IDs)                                                      |
| `tag`               | `simple` (CO2e value only) or `advanced` (CO2 + CH4 + N2O)                                        |
| `factor_start_date` | Start date (YYYY-MM-DD)                                                                           |
| `factor_end_date`   | End date (YYYY-MM-DD)                                                                             |

### Optional Columns

| Column                 | Applies to        | Description                |
| ---------------------- | ----------------- | -------------------------- |
| `group_description`    | All               | Group description text     |
| `uncertainty_grade`    | All               | 0–100 uncertainty rating   |
| `value_co2e`           | `tag=simple`      | CO2e emission factor value |
| `value_co2`            | `tag=advanced`    | CO2 emission factor value  |
| `value_ch4`            | `tag=advanced`    | CH4 emission factor value  |
| `value_n2o`            | `tag=advanced`    | N2O emission factor value  |
| `renewable_percentage` | Energy categories | 0–1 renewable fraction     |
| `hazardous`            | `waste`           | `true`/`false`             |
| `recycled`             | `waste`           | `true`/`false`             |
| `low_code`             | `waste`           | LoW (List of Waste) code   |
| `rd_code`              | `waste`           | R/D disposal code          |

***

## Validate Before Uploading

Run a dry-run to check your CSV for errors without actually uploading:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy custom-ef upload factors.csv --dry-run
```

Output:

```
Dry-run mode: no API calls were made
File: factors.csv
Groups to create: 2
Factors to create: 4
```

If validation errors are found, the command prints row-by-row errors and exits without uploading.

***

## Upload Emission Factors

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy custom-ef upload factors.csv
```

Output:

```
File: factors.csv
Groups to create: 2
Factors to create: 4
group created: Grid Spain 2023 (abc123-...)
  factor created: Jan-Jun 2023
  factor created: Jul-Dec 2023
group created: Custom Gas (def456-...)
  factor created: Natural Gas 2023
Groups created: 2
Groups failed: 0
Factors created: 3
Factors failed: 0
```

### Flags

| Flag                | Short | Default | Description                                            |
| ------------------- | ----- | ------- | ------------------------------------------------------ |
| `--template`        | `-t`  | `false` | Generate a blank CSV template instead of uploading     |
| `--dry-run`         | —     | `false` | Validate and summarize without making API calls        |
| `--skip-validation` | —     | `false` | Skip local CSV validation (rely on server-side checks) |
| `--org`             | —     | —       | Organization ID override                               |

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Generate template
dcy custom-ef upload --template

# Validate without uploading
dcy custom-ef upload factors.csv --dry-run

# Upload with JSON output
dcy custom-ef upload factors.csv --format json

# Skip local validation
dcy custom-ef upload factors.csv --skip-validation
```

***

## Bulk Delete Groups

Delete multiple custom emission groups by providing a text file with one ID per line:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy custom-ef delete-bulk ids.txt --yes
```

Output:

```
deleted: 3
```

If some deletions fail:

```
2 failed: group not found
deleted: 1
failed: 2
```

### Flags

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

The file should contain one custom emission group UUID per line. Blank lines and duplicates are automatically skipped.

***

## Typical Workflows

### Upload Custom Emission Factors

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Get the template
dcy custom-ef upload --template

# 2. Fill in your data (edit custom_ef_template.csv)

# 3. Validate
dcy custom-ef upload custom_ef_template.csv --dry-run

# 4. Upload
dcy custom-ef upload custom_ef_template.csv
```

### Replace Emission Factors

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Delete old groups
dcy custom-ef delete-bulk old-group-ids.txt --yes

# 2. Upload new CSV
dcy custom-ef upload updated_factors.csv
```

### Find Unit IDs for Your Factors

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Find the unit ID for kWh
dcy units list --search kWh --format json | jq -r '.[0].id'
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Units" icon="ruler" href="/cli/units">
    Find unit IDs for emission factor definitions
  </Card>

  <Card title="LCA Materials" icon="leaf" href="/cli/lca">
    Link materials to ecoinvent activities
  </Card>

  <Card title="Invoices" icon="file-invoice" href="/cli/invoices">
    Manage energy invoices using your custom factors
  </Card>

  <Card title="Data Imports" icon="upload" href="/cli/imports">
    Bulk import CSV/Excel data with guided mapping
  </Card>
</CardGroup>