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

# Admin

> Administrative operations for recalculations and direct data manipulation

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

<Warning>
  Admin commands are intended for platform administrators and support engineers. They trigger backend recalculations or directly modify data tables — use with caution.
</Warning>

## Overview

Admin commands provide low-level operations for triggering recalculations and inserting energy data directly. Unlike most CLI commands, admin operations take organization IDs as positional arguments rather than using `--org`.

### Available Commands

| Command                                          | Description                                           |
| ------------------------------------------------ | ----------------------------------------------------- |
| `dcy admin recalculate-scope3-td <org-id>`       | Recalculate Scope 3 T\&D data for organizations       |
| `dcy admin recalculate-waste-transport <org-id>` | Re-split waste emissions into management vs transport |
| `dcy admin energy`                               | Insert or update energy records directly (kWh)        |

***

## Recalculate Scope 3 T\&D

Trigger a backend task to recalculate Scope 3 Transmission & Distribution data for one or more organizations:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy admin recalculate-scope3-td <org-id>
```

Output:

```
Recalculation triggered for 1 organization(s)
Organizations: 550e8400-...
Timeout: 7200s
Task ID: abc123-...
Status: PROVISIONING
Logs URL: https://...
```

Multiple organizations can be recalculated in a single call:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy admin recalculate-scope3-td <org-id-1> <org-id-2> <org-id-3>
```

### Flags

| Flag        | Short | Default | Description             |
| ----------- | ----- | ------- | ----------------------- |
| `--timeout` | `-t`  | `7200`  | Task timeout in seconds |

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Single org with default timeout (2 hours)
dcy admin recalculate-scope3-td 550e8400-...

# Multiple orgs with custom timeout
dcy admin recalculate-scope3-td 550e8400-... 661f9511-... --timeout 3600

# JSON output to capture task ARN
dcy admin recalculate-scope3-td 550e8400-... --format json | jq '.task_arn'
```

***

## Recalculate Waste Transport

Re-split waste emissions into management vs transport components for one or more organizations. The backend finds waste records where the split needs recalculating and emits EventBridge events to trigger the recalculation pipeline:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy admin recalculate-waste-transport <org-id>
```

Output:

```
Waste transport recalculation triggered for 1 organization(s)
Organizations: 550e8400-...
Wastes Matched: 45
Events Emitted: 45
```

### Flags

| Flag        | Default | Description                                                 |
| ----------- | ------- | ----------------------------------------------------------- |
| `--dry-run` | `false` | Count matching wastes without emitting recalculation events |

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Preview what would be recalculated
dcy admin recalculate-waste-transport 550e8400-... --dry-run

# Trigger recalculation
dcy admin recalculate-waste-transport 550e8400-...

# Multiple orgs
dcy admin recalculate-waste-transport 550e8400-... 661f9511-...

# JSON output
dcy admin recalculate-waste-transport 550e8400-... --format json
```

Dry-run output:

```
Waste transport recalculation triggered for 1 organization(s)
Organizations: 550e8400-...
Wastes Matched: 45
Events Emitted: 0
⚠ dry run: no events were emitted
```

***

## Energy Records

Insert or update energy records directly in the energy table, bypassing the normal calculation flow. Values must be in kWh.

### Inline Mode (Single Item)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy admin energy <record-id> <record-type> <total-kwh>
```

Output:

```
✓ 550e8400-...: inserted 1 energy row(s)
```

Record types: `electricity`, `heat`, `vehicle_consumption`.

### Batch Mode (CSV File)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy admin energy --file items.csv
```

Output:

```
✓ abc-123: inserted 1 energy row(s)
✓ def-456: updated 1 energy row(s)
✗ ghi-789: record not found
```

### Flags

| Flag     | Short | Default | Description                                                            |
| -------- | ----- | ------- | ---------------------------------------------------------------------- |
| `--file` | `-f`  | —       | Path to CSV file with columns: `record_id`, `record_type`, `total_kwh` |

### CSV Format

The CSV file must have a header row with these required columns:

```csv title="items.csv" theme={"theme":{"light":"github-light","dark":"github-dark"}}
record_id,record_type,total_kwh
abc-123,electricity,500.0
def-456,heat,1200.0
ghi-789,vehicle_consumption,350.5
```

* Maximum 500 rows per file
* `total_kwh` must be non-negative
* UTF-8 BOM is automatically stripped (Excel on Windows)

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Insert a single electricity record
dcy admin energy 550e8400-... electricity 500.0

# Batch insert from CSV
dcy admin energy --file energy-records.csv

# JSON output
dcy admin energy 550e8400-... heat 1200.0 --format json
```

***

## Typical Workflows

### Recalculate After Data Migration

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Preview waste transport scope
dcy admin recalculate-waste-transport <org-id> --dry-run

# 2. Run waste transport recalculation
dcy admin recalculate-waste-transport <org-id>

# 3. Trigger Scope 3 T&D recalculation
dcy admin recalculate-scope3-td <org-id> --timeout 3600
```

### Bulk Energy Data Fix

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Prepare the CSV with corrected values
cat > fixes.csv << 'CSV'
record_id,record_type,total_kwh
abc-123,electricity,500.0
def-456,heat,1200.0
CSV

# 2. Apply fixes
dcy admin energy --file fixes.csv

# 3. Verify results
dcy admin energy --file fixes.csv --format json | jq '.results[] | {record_id, action}'
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Waste Water" icon="droplet" href="/cli/waste-water">
    Recalculate waste water treatment emissions
  </Card>

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

  <Card title="Organizations" icon="sitemap" href="/cli/organizations">
    Find organization IDs
  </Card>

  <Card title="Configuration" icon="gear" href="/cli/configuration">
    Set up environments and API keys
  </Card>
</CardGroup>