Early Access - The Dcycle CLI is currently available for enterprise customers.
Contact us to learn more about access. Overview
The invoice command manages energy and utility invoice records attached to facilities. Invoices are the primary data source for Scope 1 and Scope 2 emissions calculations.
dcy invoice <subcommand> [flags]
Available Commands
| Command | Description |
|---|
list | List invoices for a facility |
show | Show invoice details |
download | Download the invoice file |
edit | Edit invoice metadata |
delete | Delete an invoice |
bulk-delete | Delete multiple invoices at once |
migrate | Move invoices to another facility |
recalculate | Recalculate invoice emissions (one-by-one via PATCH) |
recalculate-v2 | Batch recalculate via activity categories |
recalculate-legacy | Batch recalculate via legacy endpoint |
Invoice Types
| Type | Typical Unit | GHG Scope |
|---|
electricity | kWh | Scope 2 |
heat | kWh | Scope 1/2 |
water | m³ | Scope 3 |
recharge | kWh | Scope 2 |
process | varies | Scope 1 |
waste_water_treatment | m³ | Scope 3 |
List Invoices
List invoices for a specific facility. Requires --facility.
dcy invoice list --facility <facility-id>
# Aliases
dcy invoice ls --facility <facility-id>
Examples
# List all invoices for a facility
dcy invoice list --facility <facility-id>
# Filter by type and year
dcy invoice list --facility <facility-id> --type electricity --year 2024
# Filter by status
dcy invoice list --facility <facility-id> --status active
# Increase page size
dcy invoice list --facility <facility-id> --size 200
# JSON output for scripting
dcy invoice list --facility <facility-id> --format json
Flags
| Flag | Short | Required | Default | Description |
|---|
--facility | -f | Yes | — | Facility ID |
--type | -t | No | — | Filter by invoice type |
--year | — | No | — | Filter by year |
--size | — | No | 50 | Page size |
--org | — | No | — | Organization ID override |
Output
Showing 3 invoices for facility abc12345-...
def67890-... | electricity | 2024-01-01 → 2024-01-31 | 1500.00 | 0.45 | active
ghi11223-... | heat | 2024-01-01 → 2024-01-31 | 800.00 | 0.32 | active
jkl44556-... | water | 2024-01-01 → 2024-01-31 | 45.00 | 0.01 | active
Show Invoice
Display detailed information about a single invoice.
dcy invoice show <invoice-id>
Examples
dcy invoice show 00000000-0000-0000-0000-000000000000
# JSON output
dcy invoice show <invoice-id> --format json
Flags
| Flag | Description |
|---|
--org | Organization ID override |
Output Fields
ID, invoice number, type, status, period, quantity, base quantity, unit ID, CO2e, CO2e biomass, CUPS code, file URL, uploaded by, and facility distribution percentages.
Download Invoice
Download the file attached to an invoice (PDF, image, etc.).
dcy invoice download <invoice-id>
Examples
# Download to current directory
dcy invoice download <invoice-id>
# Download to specific path
dcy invoice download <invoice-id> --output ./invoices/
# Overwrite existing file
dcy invoice download <invoice-id> --output invoice.pdf --overwrite
Flags
| Flag | Short | Default | Description |
|---|
--output | -o | — | Output file path or directory |
--overwrite | — | false | Overwrite destination file if it exists |
--org | — | — | Organization ID override |
Edit Invoice
Edit metadata on one or more invoices. Supports multiple invoice IDs in a single command.
dcy invoice edit <invoice-id> [<invoice-id>...] [flags]
Examples
# Enable/disable
dcy invoice edit <invoice-id> --enabled
dcy invoice edit <invoice-id> --disabled
# Change status
dcy invoice edit <invoice-id> --status completed
# Update multiple invoices at once
dcy invoice edit <id1> <id2> <id3> --status completed --yes
# Change supplier
dcy invoice edit <invoice-id> --supplier-id <supplier-uuid>
# Trigger recalculation by changing fuel or unit
dcy invoice edit <invoice-id> --facility-fuel-id <fuel-uuid> --yes
dcy invoice edit <invoice-id> --base-quantity 1500 --unit-id <unit-uuid> --yes
Flags
| Flag | Short | Description |
|---|
--status | -s | Set invoice status |
--enabled | — | Enable the invoice |
--disabled | — | Disable the invoice |
--supplier-id | — | Set supplier ID |
--facility-fuel-id | — | Set facility fuel ID (uses PUT, triggers recalculation) |
--unit-id | — | Set unit ID (uses PUT, triggers recalculation) |
--base-quantity | — | Set base quantity / consumption (uses PUT, triggers recalculation) |
--yes | -y | Skip confirmation prompt |
--org | — | Organization ID override |
--facility-fuel-id, --unit-id, and --base-quantity use PUT instead of PATCH, which triggers full invoice recalculation. The --enabled and --disabled flags are mutually exclusive.
Delete Invoice
Delete a single invoice by ID.
dcy invoice delete <invoice-id> [flags]
Examples
# With confirmation prompt
dcy invoice delete <invoice-id>
# Skip confirmation
dcy invoice delete <invoice-id> --yes
Flags
| Flag | Short | Default | Description |
|---|
--yes | -y | false | Skip confirmation prompt |
--org | — | — | Organization ID override |
Bulk Delete
Delete multiple invoices at once, either from a CSV file or by listing IDs directly.
dcy invoice bulk-delete [flags]
Examples
# From CSV file (columns: id, facility_id, optionally type)
dcy invoice bulk-delete --file invoices.csv --yes
# By IDs (requires --facility and --type)
dcy invoice bulk-delete --ids "id1,id2,id3" --facility <facility-id> --type electricity --yes
Flags
| Flag | Short | Default | Description |
|---|
--file | — | — | CSV file with columns: id, facility_id (optional: type) |
--ids | — | — | Invoice IDs, comma or newline separated (requires --facility and --type) |
--facility | — | — | Facility ID (used with --ids) |
--type | — | — | Invoice type (used with --ids) |
--yes | -y | false | Skip confirmation prompt |
--org | — | — | Organization ID override |
Migrate
Move invoices from one facility to another using a CSV file with invoice IDs.
dcy invoice migrate --file <csv-path> --to-facility <facility-id> [flags]
Examples
# Preview what would be migrated
dcy invoice migrate --file invoices.csv --to-facility <facility-id> --dry-run
# Execute migration
dcy invoice migrate --file invoices.csv --to-facility <facility-id> --yes
Flags
| Flag | Short | Required | Default | Description |
|---|
--file | -f | Yes | — | CSV file with invoice IDs (column: id) |
--to-facility | -t | Yes | — | Target facility ID |
--dry-run | — | No | false | Show what would be migrated without executing |
--yes | -y | No | false | Skip confirmation prompt |
Recalculate
Recalculate emissions for invoices in a facility. Processes invoices one by one via PATCH.
dcy invoice recalculate --facility <facility-id> [flags]
Examples
# Recalculate all pending invoices
dcy invoice recalculate --facility <facility-id>
# Also recalculate completed invoices
dcy invoice recalculate --facility <facility-id> --completed --yes
# Override unit_id on every invoice before recalculating
dcy invoice recalculate --facility <facility-id> --unit-id <unit-uuid> --yes
Flags
| Flag | Short | Required | Default | Description |
|---|
--facility | -f | Yes | — | Facility ID |
--completed | — | No | false | Include completed invoices with no calculated emissions |
--unit-id | — | No | — | Override unit_id on every invoice before recalculating |
--yes | -y | No | false | Skip confirmation prompt |
--org | — | No | — | Organization ID override |
Recalculate V2
Batch recalculate emissions via POST with activity category filtering. Supports scope-based and category-based filtering.
dcy invoice recalculate-v2 --facility <facility-id> [flags]
Examples
# Recalculate all scopes
dcy invoice recalculate-v2 --facility <facility-id> --yes
# Only Scope 1
dcy invoice recalculate-v2 --facility <facility-id> --scope 1
# Only Scope 3
dcy invoice recalculate-v2 --facility <facility-id> --scope 3
# Explicit activity categories (overrides --scope)
dcy invoice recalculate-v2 --facility <facility-id> \
--activity-category heat --activity-category electricity --yes
# Include completed invoices
dcy invoice recalculate-v2 --facility <facility-id> --completed --yes
Flags
| Flag | Short | Required | Default | Description |
|---|
--facility | -f | Yes | — | Facility ID |
--scope | — | No | all | Scope to recalculate: 1, 3, or all |
--activity-category | — | No | — | Explicit activity category (repeatable, overrides --scope) |
--completed | — | No | false | Include completed invoices with no calculated emissions |
--yes | -y | No | false | Skip confirmation prompt |
--org | — | No | — | Organization ID override |
Recalculate Legacy
Batch recalculate via the legacy endpoint. Can target invoices by facility or by explicit IDs.
dcy invoice recalculate-legacy [flags]
Examples
# By facility
dcy invoice recalculate-legacy --facility <facility-id> --yes
# By explicit invoice IDs
dcy invoice recalculate-legacy --ids "id1,id2,id3" --yes
# Include completed invoices (with --facility)
dcy invoice recalculate-legacy --facility <facility-id> --completed --yes
Flags
| Flag | Short | Default | Description |
|---|
--facility | -f | — | Facility ID (mutually exclusive with --ids) |
--ids | — | — | Invoice IDs, comma separated (mutually exclusive with --facility) |
--completed | — | false | Include completed invoices with no calculated emissions |
--yes | -y | false | Skip confirmation prompt |
--org | — | — | Organization ID override |
Common Options
All invoice commands support:
| Flag | Description |
|---|
--format json | JSON output (default: text) |
--verbose | Show HTTP request/response details |
--timeout | Request timeout in seconds |
Workflows
Invoice Audit Pipeline
Export, filter, and verify energy invoices programmatically:
# Export all invoices for a facility as JSON
dcy invoice list --facility <facility-id> --year 2024 --format json > invoices.json
# Recalculate emissions for invoices with errors
dcy invoice recalculate --facility <facility-id> --completed --yes
# Verify results
dcy invoice list --facility <facility-id> --type electricity --year 2024
Bulk Migration Between Facilities
# 1. List invoices to identify what needs moving
dcy invoice list --facility <old-facility-id> --format json > to-migrate.json
# 2. Create CSV with invoice IDs
echo "id" > migrate.csv
dcy invoice list --facility <old-facility-id> --format json | jq -r '.[].id' >> migrate.csv
# 3. Preview migration
dcy invoice migrate --file migrate.csv --to-facility <new-facility-id> --dry-run
# 4. Execute
dcy invoice migrate --file migrate.csv --to-facility <new-facility-id> --yes
Piping with jq
# Count invoices by type
dcy invoice list --facility <facility-id> --format json | jq 'group_by(.type) | map({type: .[0].type, count: length})'
# Sum CO2e by type
dcy invoice list --facility <facility-id> --format json | jq 'group_by(.type) | map({type: .[0].type, total_co2e: map(.co2e // 0) | add})'
# Find invoices without emissions
dcy invoice list --facility <facility-id> --format json | jq '[.[] | select(.co2e == null)]'