Logistics

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

Overview

The logistics commands are designed for fleet operators and transport companies with high-volume data:

Requests (Viajes): Individual transport trips with origin, destination, and cargo
Recharges (Consumos): Vehicle fuel consumption records
Upload: Bulk CSV upload for both data types
Status: Quick summary of all logistics data

Summary Status

Get a quick overview of your logistics data:

dcy logistics status

Output:

Requests:  1250  (last updated: 2024-06-15)
Recharges: 890   (last updated: 2024-06-14)
Hubs:      12    (last updated: 2024-03-01)

Flag	Description
`--org`	Organization ID override

JSON Response

dcy logistics status --format json

{
  "requests": {
    "count": 1250,
    "last_updated": "2024-06-15T14:30:00Z"
  },
  "recharges": {
    "count": 890,
    "last_updated": "2024-06-14T09:15:00Z"
  },
  "hubs": {
    "count": 12,
    "last_updated": "2024-03-01T10:00:00Z"
  }
}

Transport Requests

Transport requests represent individual trips or routes with emissions calculations.

List Requests

dcy logistics requests list

Output:

Showing 20 of 1250 logistics requests
MOV-001 | 2024-03-15 | ACME Corp   | 620 km | 145.20 kgCO2e | completed
MOV-002 | 2024-03-15 | FreshFoods  | 350 km | 82.50 kgCO2e  | completed
MOV-003 | 2024-03-16 | ACME Corp   | 350 km | 78.30 kgCO2e  | pending

Each row shows: movement ID, trip date, client, distance, carbon emissions, and status.

Flag	Short	Default	Description
`--from`	—	—	Start date filter (YYYY-MM-DD)
`--until`	—	—	End date filter (YYYY-MM-DD)
`--vehicle`	—	—	Filter by vehicle license plate
`--trailer`	—	—	Filter by trailer license plate
`--client`	—	—	Filter by client name
`--status`	—	—	Filter by status (e.g. `completed`, `pending`, `error`)
`--limit`	`-l`	`20`	Number of results to display
`--org`	—	—	Organization ID override

# Filter by date range
dcy logistics requests list --from 2024-01-01 --until 2024-03-31

# Filter by vehicle plate
dcy logistics requests list --vehicle "1234 ABC"

# Filter by client
dcy logistics requests list --client "ACME Corp"

# Show more results
dcy logistics requests list --limit 100

# JSON output for analysis
dcy logistics requests list --format json | \
  jq '.[] | {id: .unique_movement_id, date: .trip_date, km: .distance_km, co2: .kgco2e}'

JSON Response Fields

{
  "unique_movement_id": "MOV-001",
  "movement_stretch": "Madrid-Barcelona",
  "movement_stage": "transport",
  "trip_date": "2024-03-15",
  "client": "ACME Corp",
  "vehicle_type": "truck",
  "distance_km": 620,
  "load_tonne": 15.0,
  "tkm": 9300.0,
  "kgco2e": 145.20,
  "status": "completed",
  "error_messages": []
}

Field	Description
`unique_movement_id`	Unique identifier for the trip
`movement_stretch`	Route description
`movement_stage`	Stage of transport
`trip_date`	Date of the trip
`client`	Client associated with the trip
`vehicle_type`	Type of vehicle used
`distance_km`	Total distance in kilometers
`load_tonne`	Cargo weight in tonnes
`tkm`	Tonne-kilometers (distance × load)
`kgco2e`	Carbon emissions in kg CO2 equivalent
`status`	Processing status
`error_messages`	Array of error messages (if status is `error`)

Show Request Details

dcy logistics requests show <movement-id>

Output:

Movement ID: MOV-001
Trip Date: 2024-03-15
Client: ACME Corp
Vehicle Type: truck
Distance (km): 620
Load (t): 15.00
TKM: 9300.00
CO2e (kg): 145.20
Status: completed

If the request has errors, they are displayed:

Movement ID: MOV-005
...
Status: error
Errors: Unknown hub "Hub Sevilla", Missing vehicle plate

Flag	Description
`--org`	Organization ID override

Delete Requests

Delete operations are destructive and cannot be undone.

Delete by File

Delete all requests that were uploaded from a specific file:

dcy logistics requests delete file <file-id> --yes

The command first counts matching requests, then deletes them:

deleted 45 logistics requests from file 550e8400-...

Delete All

Delete ALL requests for the organization:

dcy logistics requests delete all --yes

Confirmation prompt (without --yes):

Delete all logistics requests for the current organization? [y/N]

Output:

all logistics requests deleted successfully

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

Fuel Recharges

Track fuel consumption for your fleet.

Delete Recharges

Remove all recharges for the organization:

dcy logistics recharges delete --yes

Output:

all logistics recharges deleted successfully

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

To view recharges data, use dcy logistics status for counts. Recharges don’t have a list command — use the Dcycle web interface or API for detailed views.

Bulk CSV Upload

The most efficient way to upload large amounts of logistics data.

Generate Templates

The CLI generates ready-to-fill CSV templates with correct column headers and example data:

# Transport requests template
dcy logistics upload --type requests --template

Output:

template generated: logistics_viajes_template.csv

# Fuel recharges template
dcy logistics upload --type recharges --template

Output:

template generated: logistics_consumos_template.csv

Upload Data

# Upload transport requests
dcy logistics upload viajes.csv --type requests

# Upload fuel recharges
dcy logistics upload consumos.csv --type recharges

Output:

requests file uploaded successfully
file_id: 550e8400-e29b-41d4-a716-446655440000

Flag	Short	Required	Description
`--type`	`-t`	Yes	File type: `requests` or `recharges`
`--template`	—	No	Generate a template file instead of uploading
`--org`	—	No	Organization ID override

Upload JSON Response

dcy logistics upload viajes.csv --type requests --format json

{
  "type": "requests",
  "file_name": "viajes.csv",
  "file_id": "550e8400-e29b-41d4-a716-446655440000",
  "destination_file_key": "logistics/requests/550e8400-...",
  "upload_url": "https://..."
}

Template: Requests (Viajes)

The requests template has 13 columns:

Column	Required	Description
`trip_date`	Yes	Trip date (YYYY-MM-DD)
`unique_movement_id`	Yes	Unique trip identifier
`client`	Yes	Client name
`vehicle_license_plate`	Yes	Vehicle plate number
`trailer_license_plate`	No	Trailer plate (if applicable)
`origin_hub_name`	Yes	Starting point (hub name or address)
`destination_hub_name`	Yes	End point (hub name or address)
`distance_km`	Yes	Total distance in kilometers
`load_kg`	Yes	Cargo weight in kilograms
`vehicle_type`	No	Vehicle type (e.g. `truck`)
`toc`	No	Type of cargo code
`cleaning`	No	Whether cleaning was performed (`true`/`false`)
`subcontractor`	No	Whether trip was subcontracted (`true`/`false`)

logistics_viajes_template.csv

trip_date,unique_movement_id,client,vehicle_license_plate,trailer_license_plate,origin_hub_name,destination_hub_name,distance_km,load_kg,vehicle_type,toc,cleaning,subcontractor
2024-01-15,MOV-001,Cliente Ejemplo SA,ABC1234,XYZ5678,Hub Madrid,Hub Barcelona,620,15000,truck,dry_goods,false,false
2024-01-16,MOV-002,Otro Cliente SL,DEF5678,,Hub Barcelona,Hub Valencia,350,12000,truck,refrigerated,true,false

Template: Recharges (Consumos)

The recharges template has 6 columns:

Column	Required	Description
`recharge_date`	Yes	Refueling date (YYYY-MM-DD)
`vehicle_license_plate`	Yes	Vehicle plate number
`hub_name`	No	Station or hub name
`fuel_type`	Yes	Fuel type (e.g. `diesel`, `gasoline`)
`quantity_liters`	Yes	Amount in liters
`cost`	No	Cost in local currency

logistics_consumos_template.csv

recharge_date,vehicle_license_plate,hub_name,fuel_type,quantity_liters,cost
2024-01-15,ABC1234,Hub Madrid,diesel,150.5,195.65
2024-01-16,DEF5678,Hub Barcelona,diesel,180.0,234.00

Reference Data

List Clients

Browse available logistics clients for your organization:

dcy logistics clients

Output:

Showing 3 logistics clients
ACME Corp
FreshFoods SL
Transport Express SA

Clients are returned as a flat list of names (not IDs). Use client names in --client filters.

Flag	Description
`--org`	Organization ID override

List Types of Cargo (TOCs)

dcy logistics tocs

Output:

Showing 5 logistics tocs
550e8400-... | General Cargo | dry_goods
661f9511-... | Refrigerated  | refrigerated
772a0622-... | Hazardous     | hazardous
883b1733-... | Bulk          | bulk
994c2844-... | Container     | container

Each row shows: ID, name, and type code.

Flag	Description
`--org`	Organization ID override

# JSON output
dcy logistics tocs --format json | jq '.[] | {name, type}'

Upload Workflow

Generate Template

Download the CSV template with correct columns:

dcy logistics upload --type requests --template

This creates logistics_viajes_template.csv in the current directory.

Prepare Data

Fill the template with your data using Excel, LibreOffice, or any CSV editor.

Use consistent date format: YYYY-MM-DD
Match vehicle plates exactly as registered in dcy vehicle list
Use hub names from dcy hub list for origin/destination
Use TOC codes from dcy logistics tocs

Upload

Upload the completed CSV:

dcy logistics upload viajes.csv --type requests

Verify

Confirm the data was imported:

dcy logistics status
dcy logistics requests list --from 2024-01-01

Typical Workflows

Daily TMS Integration

Automate daily data uploads from your Transport Management System:

#!/usr/bin/env bash
set -euo pipefail

export DCYCLE_API_KEY="$API_KEY"
export DCYCLE_ORG_ID="$ORG_ID"

DATE=$(date +%Y-%m-%d)

# Export from TMS (your custom script)
./export_tms_data.sh > "/tmp/requests-${DATE}.csv"

# Upload to Dcycle
dcy logistics upload "/tmp/requests-${DATE}.csv" --type requests

# Verify upload
dcy logistics status --format json
dcy logistics requests list --from "$DATE" --format json | jq 'length'

Replace Stale Data

Delete old file data and re-upload corrected CSV:

# Find the file ID from upload history
FILE_ID="550e8400-..."

# Delete the old data
dcy logistics requests delete file "$FILE_ID" --yes

# Upload corrected file
dcy logistics upload corrected_viajes.csv --type requests

# Verify
dcy logistics status

Emissions Analysis

# Total emissions for a date range
dcy logistics requests list --from 2024-01-01 --until 2024-12-31 --limit 1000 --format json | \
  jq '[.[].kgco2e] | add | . / 1000 | "Total: \(.) tCO2e"'

# Emissions by client
dcy logistics requests list --limit 1000 --format json | \
  jq 'group_by(.client) | map({client: .[0].client, total_kgco2e: ([.[].kgco2e] | add)}) | sort_by(.total_kgco2e) | reverse'

# Find error requests
dcy logistics requests list --status error --format json | \
  jq '.[] | {id: .unique_movement_id, errors: .error_messages}'

Bulk Reset All Data

# Delete all requests and recharges (for a fresh start)
dcy logistics requests delete all --yes
dcy logistics recharges delete --yes

# Verify clean state
dcy logistics status

Aliases

The list subcommand supports ls as a short alias:

dcy logistics requests ls     # same as dcy logistics requests list
dcy logistics requests ls -l 50  # same as dcy logistics requests list --limit 50

Next Steps

Vehicles

Manage fleet vehicles, fuel types, and CSV uploads

Transport Routes

Track upstream and downstream transport emissions

Data Imports

Alternative import pipeline with guided mapping

Examples

Complete workflow examples

MCP Tools

Query logistics data from AI assistants via MCP

Getting Started

Commands

Examples

Overview

Summary Status

JSON Response

Transport Requests

List Requests

JSON Response Fields

Show Request Details

Delete Requests

Delete by File

Delete All

Fuel Recharges

Delete Recharges

Bulk CSV Upload

Generate Templates

Upload Data

Upload JSON Response

Template: Requests (Viajes)

Template: Recharges (Consumos)

Reference Data

List Clients

List Types of Cargo (TOCs)

Upload Workflow

Typical Workflows

Daily TMS Integration

Replace Stale Data

Emissions Analysis

Bulk Reset All Data

Aliases

Next Steps

Vehicles

Transport Routes

Data Imports

Examples

MCP Tools

​Overview

​Summary Status

​JSON Response

​Transport Requests

​List Requests

​JSON Response Fields

​Show Request Details

​Delete Requests

​Delete by File

​Delete All

​Fuel Recharges

​Delete Recharges

​Bulk CSV Upload

​Generate Templates

​Upload Data

​Upload JSON Response

​Template: Requests (Viajes)

​Template: Recharges (Consumos)

​Reference Data

​List Clients

​List Types of Cargo (TOCs)

​Upload Workflow

​Typical Workflows

​Daily TMS Integration

​Replace Stale Data

​Emissions Analysis

​Bulk Reset All Data

​Aliases

​Next Steps

Vehicles

Transport Routes

Data Imports

Examples

MCP Tools

Overview

Summary Status

JSON Response

Transport Requests

List Requests

JSON Response Fields

Show Request Details

Delete Requests

Delete by File

Delete All

Fuel Recharges

Delete Recharges

Bulk CSV Upload

Generate Templates

Upload Data

Upload JSON Response

Template: Requests (Viajes)

Template: Recharges (Consumos)

Reference Data

List Clients

List Types of Cargo (TOCs)

Upload Workflow

Typical Workflows

Daily TMS Integration

Replace Stale Data

Emissions Analysis

Bulk Reset All Data

Aliases

Next Steps