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

# Vehicles

> Manage fleet vehicles, fuel types, consumptions, and bulk CSV uploads

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

## Overview

The `vehicle` command manages your organization's fleet of vehicles, covering GHG Protocol Scope 1 direct emissions from owned/rented vehicles. The related `vehicle-fuel` command provides reference data for fuel types and vehicle categories.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle <subcommand> [flags]
dcy vehicle-fuel <subcommand> [flags]
```

### Available Commands

| Command                       | Description                                     |
| ----------------------------- | ----------------------------------------------- |
| `vehicle list`                | List vehicles                                   |
| `vehicle show`                | Show vehicle details                            |
| `vehicle create`              | Create a vehicle                                |
| `vehicle edit`                | Edit a vehicle                                  |
| `vehicle delete`              | Delete a vehicle                                |
| `vehicle upload`              | Upload vehicles from CSV                        |
| `vehicle diagnose`            | Diagnose emission calculation issues            |
| `vehicle recalculate`         | Trigger emission recalculation                  |
| `vehicle delete-consumptions` | Bulk delete consumption records in a date range |
| `vehicle-fuel list`           | List available fuel types                       |
| `vehicle-fuel list-types`     | List vehicle type categories                    |

***

## List Vehicles

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle list [flags]

# Aliases
dcy vehicle ls
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# List all vehicles
dcy vehicle list

# Filter by type
dcy vehicle list --type freight

# Filter by ownership
dcy vehicle list --ownership owned

# By license plate (partial match)
dcy vehicle list --license-plate "1234"

# Filter by status
dcy vehicle list --status active

# Search text
dcy vehicle list --search "Tesla"

# Sort by name descending
dcy vehicle list --sort-by name --sort-order desc

# Pagination
dcy vehicle list --page 2 --size 100

# JSON output for scripting
dcy vehicle list --format json | jq '.[] | {name, license_plate, type}'
```

### Flags

| Flag              | Short | Default | Description                                                                     |
| ----------------- | ----- | ------- | ------------------------------------------------------------------------------- |
| `--type`          | `-t`  | —       | Filter by vehicle type (`passenger`, `freight`)                                 |
| `--ownership`     | `-o`  | —       | Filter by ownership (`owned`, `rented`)                                         |
| `--license-plate` | `-l`  | —       | Filter by license plate (partial match)                                         |
| `--status`        | —     | —       | Filter by status (`active`, `inactive`, `archived`)                             |
| `--search`        | —     | —       | Full-text search                                                                |
| `--sort-by`       | `-s`  | —       | Sort by: `name`, `type`, `ownership`, `country`, `status`, `created`, `updated` |
| `--sort-order`    | —     | `asc`   | Sort order: `asc` or `desc`                                                     |
| `--page`          | —     | `1`     | Page number                                                                     |
| `--size`          | —     | `50`    | Items per page                                                                  |
| `--org`           | —     | —       | Organization ID override                                                        |

### Output

```
Showing 3 of 3 vehicles in Acme Corp
v1-abc123-... | Fleet Car 1  | passenger | owned   | 1234 ABC | active
v2-def456-... | Delivery Van | freight   | rented  | 5678 DEF | active
v3-ghi789-... | (not set)    | passenger | owned   | 9012 GHI | active
```

Columns: ID, name, type, ownership, license plate, status. Vehicles without a name show `(not set)`.

***

## Show Vehicle Details

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle show <vehicle-id>
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle show 00000000-0000-0000-0000-000000000000

# JSON output
dcy vehicle show <vehicle-id> --format json
```

### Flags

| Flag    | Description              |
| ------- | ------------------------ |
| `--org` | Organization ID override |

### Output

```
ID: v1-abc123-...
Name: Fleet Car 1
Type: passenger
Ownership: owned
License Plate: 1234 ABC
Country: ES
Status: active
Vehicle Type Label: Turismo medio
Fuel: Diesel
Registration Year: 2022
Market Segment: upper_medium
Size: medium
Created: 2024-01-15
Updated: 2024-06-01
```

***

## Create Vehicle

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle create [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle create \
  --type passenger \
  --ownership owned \
  --license-plate "1234 ABC" \
  --unknown-vehicle-id <unknown-vehicle-id> \
  --vehicle-fuel-id <fuel-id>

# With optional fields
dcy vehicle create \
  --name "Company Car" \
  --type passenger \
  --ownership owned \
  --license-plate "1234 ABC" \
  --unknown-vehicle-id <unknown-vehicle-id> \
  --vehicle-fuel-id <fuel-id> \
  --country ES \
  --registration-year 2022 \
  --market-segment upper_medium \
  --size medium
```

### Flags

| Flag                          | Short | Required | Default | Description                      |
| ----------------------------- | ----- | -------- | ------- | -------------------------------- |
| `--type`                      | `-t`  | Yes      | —       | `passenger` or `freight`         |
| `--ownership`                 | `-o`  | Yes      | —       | `owned` or `rented`              |
| `--license-plate`             | `-l`  | Yes      | —       | License plate (min 3 chars)      |
| `--unknown-vehicle-id`        | `-u`  | Yes      | —       | Unknown vehicle type ID          |
| `--vehicle-fuel-id`           | `-f`  | Yes      | —       | Vehicle fuel ID                  |
| `--name`                      | `-n`  | No       | —       | Display name                     |
| `--country`                   | —     | No       | `ES`    | Country ISO-2 code               |
| `--registration-year`         | —     | No       | —       | Registration year                |
| `--market-segment`            | —     | No       | —       | Market segment (see table below) |
| `--size`                      | —     | No       | —       | Vehicle size (see table below)   |
| `--custom-emission-factor-id` | —     | No       | —       | Custom emission factor ID        |
| `--org`                       | —     | No       | —       | Organization ID override         |

#### Market Segments

`mini`, `supermini`, `lower_medium`, `upper_medium`, `executive`, `luxury`, `sports`, `dual_purpose_4x4`, `mpv`

#### Vehicle Sizes

`small_car`, `medium`, `large_car`, `average_car`

<Tip>
  Use `dcy vehicle-fuel list` to browse available fuel IDs, and `dcy vehicle-fuel list-types` for vehicle type IDs.
</Tip>

***

## Edit Vehicle

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle edit <vehicle-id> [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle edit <vehicle-id> --name "Updated Name"
dcy vehicle edit <vehicle-id> --type freight --status active
dcy vehicle edit <vehicle-id> --ownership rented --license-plate "NEW 1234"
```

### Flags

Accepts the same flags as `create` (all optional). Additionally supports:

| Flag       | Short | Description                                      |
| ---------- | ----- | ------------------------------------------------ |
| `--status` | —     | Vehicle status: `active`, `inactive`, `archived` |
| `--org`    | —     | Organization ID override                         |

***

## Delete Vehicle

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle delete <vehicle-id> [flags]

# Aliases
dcy vehicle rm <vehicle-id>
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Interactive confirmation
dcy vehicle delete <vehicle-id>

# Skip confirmation
dcy vehicle delete <vehicle-id> --yes
```

### Flags

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

### Output

Confirmation prompt:

```
Delete vehicle Fleet Car 1 (v1-abc123-...)? [y/N]
```

```
vehicle deleted successfully: Fleet Car 1
```

***

## Upload Vehicles from CSV

Bulk upload vehicles with validation and CSV templates.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle upload [file.csv] [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Generate template
dcy vehicle upload --template

# Generate template with real UUIDs from your organization
dcy vehicle upload --template-with-data

# Validate only (default behavior)
dcy vehicle upload vehicles.csv

# Validate and upload
dcy vehicle upload vehicles.csv --no-dry-run

# Verbose validation output
dcy vehicle upload vehicles.csv --no-dry-run --verbose
```

### Flags

| Flag                   | Short | Default | Description                                     |
| ---------------------- | ----- | ------- | ----------------------------------------------- |
| `--template`           | —     | `false` | Generate example CSV template                   |
| `--template-with-data` | —     | `false` | Generate template with real UUIDs from your org |
| `--dry-run`            | —     | `true`  | Validate without uploading                      |
| `--no-dry-run`         | —     | `false` | Upload after validation                         |
| `--verbose`            | `-v`  | `false` | Show detailed validation results                |
| `--org`                | —     | —       | Organization ID override                        |

### CSV Template Columns

```csv theme={"theme":{"light":"github-light","dark":"github-dark"}}
name,license_plate,country,type,ownership,unknown_vehicle_id,vehicle_fuel_id
Fleet Vehicle 1,ABC1234,ES,passenger,owned,uuid-for-car-type,uuid-for-diesel-fuel
Delivery Van,XYZ5678,ES,freight,rented,uuid-for-van-type,uuid-for-gasoline-fuel
```

The CSV upload also accepts Spanish column names (`nombre`, `matricula`, `pais`, `tipo_vehiculo`, `combustible`, `propiedad`) and normalizes type/ownership values from Spanish (`pasajero`->`passenger`, `carga`->`freight`, `propio`->`owned`, `alquiler`->`rented`).

<Tip>
  Use `--template-with-data` to get real UUIDs for `unknown_vehicle_id` and `vehicle_fuel_id` pre-filled from your organization's data.
</Tip>

***

## Diagnose Vehicle Issues

Scan a vehicle's consumption records for emission calculation issues.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle diagnose <vehicle-id> [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Basic diagnosis
dcy vehicle diagnose <vehicle-id>

# Detailed output with error messages
dcy vehicle diagnose <vehicle-id> --verbose

# JSON output
dcy vehicle diagnose <vehicle-id> --format json
```

### Flags

| Flag        | Default | Description                  |
| ----------- | ------- | ---------------------------- |
| `--verbose` | `false` | Show detailed error messages |
| `--org`     | —       | Organization ID override     |

### Output

```
Vehicle: Fleet Car 1 (v1-abc123-...)
Status: active
Total CO2e: 1250.00 kg
Consumptions: 12

2024-01 | 150.00 | 85.30 | success
2024-02 | 160.00 | 0.00  | success | zero emissions with non-zero quantity
2024-03 | 0.00   | 0.00  | error   | Missing emission factor

Issues found: 2
- 2024-02: zero emissions with non-zero quantity
- 2024-03: Missing emission factor
```

***

## Recalculate Vehicle Emissions

Trigger a recalculation of vehicle consumption emissions.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle recalculate <vehicle-id> [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# With confirmation prompt
dcy vehicle recalculate <vehicle-id>

# Force recalculation without confirmation
dcy vehicle recalculate <vehicle-id> --force --yes
```

### Flags

| Flag      | Short | Default | Description                             |
| --------- | ----- | ------- | --------------------------------------- |
| `--force` | —     | `false` | Force recalculation even if data exists |
| `--yes`   | `-y`  | `false` | Skip confirmation prompt                |
| `--org`   | —     | —       | Organization ID override                |

### Output

```
vehicle recalculation triggered successfully
event_id: evt-12345-...
```

***

## Delete Vehicle Consumptions

Bulk delete vehicle consumption records within a date range for an organization. Optionally includes subsidiary organizations.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle delete-consumptions [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Delete consumptions for a date range
dcy vehicle delete-consumptions \
  --org <org-id> \
  --start-date 2024-01-01 \
  --end-date 2024-12-31 \
  --yes

# Include subsidiary organizations
dcy vehicle delete-consumptions \
  --org <org-id> \
  --start-date 2024-01-01 \
  --end-date 2024-12-31 \
  --include-subsidiaries \
  --yes
```

### Flags

| Flag                     | Short | Default | Description                          |
| ------------------------ | ----- | ------- | ------------------------------------ |
| `--org`                  | —     | —       | Organization ID                      |
| `--start-date`           | —     | —       | Start date YYYY-MM-DD (required)     |
| `--end-date`             | —     | —       | End date YYYY-MM-DD (required)       |
| `--include-subsidiaries` | —     | `false` | Include all subsidiary organizations |
| `--yes`                  | `-y`  | `false` | Skip confirmation prompts            |

### Output

```
done. deleted: 45 | failed: 0 | skipped (no consumptions): 3
```

<Warning>
  This deletes consumption data permanently. Without `--yes`, the command prompts for confirmation including whether to include subsidiaries.
</Warning>

***

## Vehicle Fuels

List available fuel types for your organization.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle-fuel list [flags]

# Aliases
dcy vehicle-fuel ls
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# List all fuels
dcy vehicle-fuel list

# Search by fuel name
dcy vehicle-fuel list --search diesel

# JSON output
dcy vehicle-fuel list --format json | jq '.[] | {id, fuel, fuel_type}'
```

### Flags

| Flag       | Short | Default | Description              |
| ---------- | ----- | ------- | ------------------------ |
| `--search` | `-s`  | —       | Search by fuel name      |
| `--page`   | —     | `1`     | Page number              |
| `--size`   | —     | `50`    | Page size                |
| `--org`    | —     | —       | Organization ID override |

### Output

```
Showing 5 of 5 vehicle fuels in Acme Corp
f1-abc123-... | Diesel                | diesel   | units=Liters, Kilometers
f2-def456-... | Gasoline              | gasoline | units=Liters, Kilometers
f3-ghi789-... | Electric (100%)       | electric | units=kWh, Kilometers
f4-jkl012-... | Hybrid (diesel/elec)  | hybrid   | units=Liters, Kilometers
f5-mno345-... | Compressed Natural Gas| cng      | units=kg, Kilometers
```

***

## Vehicle Types

List available vehicle type categories (unknown vehicles). Use these IDs for the `--unknown-vehicle-id` flag when creating vehicles.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle-fuel list-types [flags]
```

### Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
dcy vehicle-fuel list-types

# JSON output
dcy vehicle-fuel list-types --format json
```

### Flags

| Flag    | Description              |
| ------- | ------------------------ |
| `--org` | Organization ID override |

### Output

```
Showing 3 vehicle types
uv-abc123-... | Turismo medio | ES
uv-def456-... | Furgoneta     | ES
uv-ghi789-... | Camion pesado | ES
```

***

## Common Options

All vehicle commands support:

| Flag            | Description                        |
| --------------- | ---------------------------------- |
| `--format json` | JSON output (default: `text`)      |
| `--verbose`     | Show HTTP request/response details |
| `--timeout`     | Request timeout in seconds         |

***

## Workflows

### Fleet Setup from CSV

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Get real UUIDs for your organization
dcy vehicle upload --template-with-data

# 2. Fill the template with your fleet data

# 3. Validate first
dcy vehicle upload fleet.csv

# 4. Upload
dcy vehicle upload fleet.csv --no-dry-run

# 5. Verify
dcy vehicle list
```

### Diagnose and Fix Emission Issues

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. List vehicles with issues
dcy vehicle list --format json | \
  jq '.[] | select(.co2e == 0) | {id, name: .name, plate: .license_plate}'

# 2. Diagnose a specific vehicle
dcy vehicle diagnose <vehicle-id> --verbose

# 3. Fix and recalculate
dcy vehicle recalculate <vehicle-id> --force --yes
```

### Export Fleet Data

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Export all vehicles as JSON
dcy vehicle list --format json --size 1000 > vehicles.json

# Export fuel types
dcy vehicle-fuel list --format json > fuels.json

# Count vehicles by type
dcy vehicle list --format json | jq 'group_by(.type) | map({type: .[0].type, count: length})'
```

### Piping with jq

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Find vehicles with zero emissions
dcy vehicle list --format json | jq '[.[] | select(.co2e == 0)] | length'

# List license plates
dcy vehicle list --format json | jq -r '.[].license_plate'

# Group by ownership
dcy vehicle list --format json | jq 'group_by(.ownership) | map({ownership: .[0].ownership, count: length})'
```