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

# Logistics

> Manage transport requests, fuel recharges, and bulk CSV uploads for fleet operators

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

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy logistics status --format json
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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                                |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<Warning>
  Delete operations are destructive and cannot be undone.
</Warning>

#### Delete by File

Delete all requests that were uploaded from a specific file:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 |

<Note>
  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.
</Note>

***

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Transport requests template
dcy logistics upload --type requests --template
```

Output:

```
template generated: logistics_viajes_template.csv
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Fuel recharges template
dcy logistics upload --type recharges --template
```

Output:

```
template generated: logistics_consumos_template.csv
```

### Upload Data

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy logistics upload viajes.csv --type requests --format json
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`) |

```csv title="logistics_viajes_template.csv" theme={"theme":{"light":"github-light","dark":"github-dark"}}
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                |

```csv title="logistics_consumos_template.csv" theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# JSON output
dcy logistics tocs --format json | jq '.[] | {name, type}'
```

***

## Upload Workflow

<Steps>
  <Step title="Generate Template">
    Download the CSV template with correct columns:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    dcy logistics upload --type requests --template
    ```

    This creates `logistics_viajes_template.csv` in the current directory.
  </Step>

  <Step title="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`
  </Step>

  <Step title="Upload">
    Upload the completed CSV:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    dcy logistics upload viajes.csv --type requests
    ```
  </Step>

  <Step title="Verify">
    Confirm the data was imported:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    dcy logistics status
    dcy logistics requests list --from 2024-01-01
    ```
  </Step>
</Steps>

***

## Typical Workflows

### Daily TMS Integration

Automate daily data uploads from your Transport Management System:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
#!/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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<CardGroup cols={2}>
  <Card title="Vehicles" icon="car" href="/cli/vehicles">
    Manage fleet vehicles, fuel types, and CSV uploads
  </Card>

  <Card title="Transport Routes" icon="route" href="/cli/transport">
    Track upstream and downstream transport emissions
  </Card>

  <Card title="Data Imports" icon="upload" href="/cli/imports">
    Alternative import pipeline with guided mapping
  </Card>

  <Card title="Examples" icon="code" href="/cli/examples">
    Complete workflow examples
  </Card>

  <Card title="MCP Tools" icon="robot" href="/mcp/logistics">
    Query logistics data from AI assistants via MCP
  </Card>
</CardGroup>