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

​
Overview

The dcy imports command provides a guided pipeline for bulk-importing data from CSV or Excel files. It handles column mapping, validation, error correction, and submission — all from the terminal. Supported data types (templates):
Template IDDescription
invoicesEnergy invoices (electricity, gas, water)
vehiclesFleet vehicles
vehicle_consumptionsVehicle fuel consumption records
purchasesPurchased goods and services
business_travelsBusiness travel records
logistics_requestsTransport requests
logistics_rechargesFuel recharges
employeesEmployee commute records
wastesWaste records

​
Import Workflow

A typical import follows these steps: 
create → suggest-mapping → confirm-mapping → validate → [patch] → submit
  1. Create — Upload your file and start an import session
  2. Suggest mapping — Get AI-assisted column mapping suggestions
  3. Confirm mapping — Lock in the column mapping
  4. Validate — Check all rows for errors
  5. Patch (optional) — Fix row-level errors
  6. Submit — Process the import and create records

​
Step 1: Explore the Template

Before importing, check what columns and formats the template expects: 
# View template metadata
dcy imports template invoices
Output: 
template_id: invoices
required_context_fields: facility_id
KEY                            TYPE       REQUIRED ALIASES
----------------------------------------------------------------------------------------------------
invoice_type                   category   yes      type, tipo
start_date                     date       yes      fecha_inicio, start
end_date                       date       yes      fecha_fin, end
consumption                    number     yes      consumo, kwh
provider                       text       no       proveedor, supplier
cost                           number     no       coste, cost, importe

​
Get Available Options

For category columns, check what values are accepted: 
# List countries
dcy imports options countries

# List fuel types
dcy imports options vehicle_fuels

# List invoice types
dcy imports options invoice_types

​
Step 2: Create Import Session

Upload a file and start a new import session: 
dcy imports create \
  --template invoices \
  --file invoices-2024.xlsx \
  --facility-id abc123-def456
Output: 
import_id:      550e8400-e29b-41d4-a716-446655440000
file_name:      invoices-2024.xlsx
total_rows:     150
source_columns: type, start, end, kwh, provider, cost
sample_rows (first 3):
  [0] electricity | 2024-01-01 | 2024-01-31 | 4500 | Iberdrola | 890.50
  [1] natural_gas | 2024-01-01 | 2024-01-31 | 1200 | Naturgy | 320.00
  [2] electricity | 2024-02-01 | 2024-02-28 | 4200 | Iberdrola | 850.00
FlagRequiredDescription
--templateYesTemplate ID (see table above)
--fileYesPath to CSV or XLSX file
--facility-idDependsFacility UUID (required for invoices, wastes)
--project-idNoProject UUID to attach
--sheet-nameNoSheet name for multi-sheet XLSX files
--numeric-localeNoNumeric locale hint (e.g. es_ES for comma decimals)
--date-localeNoDate format: dmy or mdy for ambiguous dates
--folder-idNoFolder UUID to attach
--raw-file-idNoLink to a pre-existing file upload
--orgNoOrganization ID override
Use --numeric-locale es_ES when your CSV uses commas as decimal separators (e.g. 4.500,50 instead of 4500.50).

​
Step 3: Map Columns

​
Get AI Suggestions

The system analyzes your source columns and suggests mappings: 
dcy imports suggest-mapping 550e8400-...
Output: 
TEMPLATE COLUMN                SUGGESTED SOURCE               CONFIDENCE   REASON
----------------------------------------------------------------------------------------------------
invoice_type                   type                           0.95         exact match [auto-mapped]
start_date                     start                          0.88         alias match [suggested]
end_date                       end                            0.88         alias match [suggested]
consumption                    kwh                            0.92         alias match [auto-mapped]
provider                       provider                       0.95         exact match [auto-mapped]
cost                           cost                           0.70         fuzzy match [suggested]
Confidence tiers:
  • ≥ 0.92 — auto-mapped: high confidence, ready to use
  • 0.60–0.91 — suggested: review recommended
  • < 0.60 — unmapped: manual mapping required

​
Confirm the Mapping

Save the mapping to a JSON file and confirm it:
mapping.json
{
  "invoice_type": "type",
  "start_date": "start",
  "end_date": "end",
  "consumption": "kwh",
  "provider": "provider",
  "cost": "cost"
}

dcy imports confirm-mapping 550e8400-... --mapping-file mapping.json

​
Check Unique Values

Before validating, preview how category values will be resolved: 
dcy imports unique-values 550e8400-... --mapping-file mapping.json
Output: 
invoice_type  ←  type  [3 unique]
  electricity                      → electricity                    [resolved]
  natural_gas                      → natural_gas                    [resolved]
  agua                             → -                              [unresolved]
Unresolved values will appear as validation errors. Fix them in your file or patch them after validation.

​
Step 4: Validate

Run validation to check all rows against the template rules: 
dcy imports validate 550e8400-... --mapping-file mapping.json
Output: 
valid_rows: 147 / 150  |  error_rows: 3  |  page 1/1
errors by column:
  invoice_type: 2
  consumption: 1
[45] invoice_type=agua, start=2024-03-01, end=2024-03-31, kwh=500 | errors: {"invoice_type":"invalid value"}
[89] invoice_type=agua, start=2024-06-01, end=2024-06-30, kwh=300 | errors: {"invoice_type":"invalid value"}
[120] invoice_type=electricity, start=2024-09-01, end=2024-09-30, kwh= | errors: {"consumption":"required"}
FlagDefaultDescription
--mapping-file—Path to JSON mapping file (required)
--page1Page number
--page-size50Rows per page
--errors-onlyfalseOnly show rows with errors

​
Browse Rows

Inspect all rows (or just error rows) with pagination: 
# Show error rows only
dcy imports rows 550e8400-... --errors-only --page-size 100

# Show all rows page by page
dcy imports rows 550e8400-... --page 1 --page-size 20

​
Step 5: Fix Errors (Optional)

Patch individual row values without re-uploading the file: 
dcy imports patch 550e8400-... --corrections '[
  {"row_index": 45, "column": "invoice_type", "value": "water"},
  {"row_index": 89, "column": "invoice_type", "value": "water"},
  {"row_index": 120, "column": "consumption", "value": "450"}
]'
Output: 
updated_rows: 3  |  total_errors_remaining: 0
Then re-validate to confirm all errors are resolved: 
dcy imports validate 550e8400-... --mapping-file mapping.json --errors-only

​
Step 6: Submit

Once validation passes, submit the import for processing: 
dcy imports submit 550e8400-... --partner dcycle
Output: 
status:            submitted
rows_submitted:    150
file_id:           abc12345-...
processing_job_id: def67890-...
FlagDefaultDescription
--partnerdcyclePartner slug (required)
--ignore-errorsfalseSubmit even if rows have validation errors
--org—Organization ID override

​
Managing Sessions

​
Check Session Status

dcy imports status 550e8400-...
Output shows current status (created, parsed, mapped, validating, validated, submitting, submitted, failed, expired), row counts, and processing info.

​
List All Sessions

dcy imports list

# Short alias
dcy imports ls

# Filter by status
dcy imports list --status validated

# Filter by template
dcy imports list --template invoices

# Include expired sessions
dcy imports list --include-expired
FlagDefaultDescription
--status—Filter by session status
--template—Filter by template ID
--user-id—Filter by user UUID
--include-expiredfalseInclude expired sessions
--page1Page number
--page-size20Sessions per page

​
Delete a Session

Remove a non-submitted session and its cached data: 
dcy imports delete 550e8400-...

​
Complete Example

End-to-end import of energy invoices: 
# 1. Check template requirements
dcy imports template invoices --format json | jq '.columns[] | {key, type, required}'

# 2. Upload file
SESSION=$(dcy imports create \
  --template invoices \
  --file invoices-q1.xlsx \
  --facility-id abc123 \
  --numeric-locale es_ES \
  --format json | jq -r '.import_id')

echo "Session: $SESSION"

# 3. Get mapping suggestions and save
dcy imports suggest-mapping $SESSION --format json | jq '.suggestions' > mapping.json

# 4. Validate
dcy imports validate $SESSION --mapping-file mapping.json

# 5. Fix any errors
dcy imports validate $SESSION --mapping-file mapping.json --errors-only --format json \
  | jq '.rows[] | {row: .row_index, errors: .errors}'

# 6. Submit
dcy imports submit $SESSION --partner dcycle
All imports subcommands support --format json for scripting. Pipe through jq to extract fields like import_id, total_rows, or error_rows.

​
Next Steps

Emissions Data

Manage invoices, purchases, and travel data

Files

Upload and process documents

Examples

See end-to-end workflow examples

Configuration

Set up environments and API keys