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

Examples & Workflows

Learn how to automate operational data management with practical, production-ready examples.

Featured Examples

CI/CD Pipeline Integration

Automate uploads with GitHub Actions, GitLab CI, and other CI/CD tools. Includes validation, notifications, and best practices for reliable pipelines.

Multi-Organization Consolidated Reporting

Generate consolidated sustainability reports across holdings, subsidiaries, and business units. Compare performance and track group-wide targets.

Logistics Data Automation

Daily automation for transport companies: upload trip data (viajes) and fuel consumption (consumos). Integration with TMS/ERP systems.

Quick Start

# 1. Login with your browser
dcy auth login

# 2. List your organizations
dcy org list

# 3. Set active organization
dcy org set <your-org-id>

# 4. Explore your data
dcy facility list
dcy vehicle list

# Set environment variables — no interactive login needed
export DCYCLE_API_KEY=dcy_live_abc123...
export DCYCLE_ORG_ID=550e8400-e29b-41d4-a716-446655440000
export DCYCLE_FORMAT=json

# Commands authenticate automatically
dcy facility list
dcy vehicle list

API keys are created by organization admins in the Dcycle web interface under Settings → API Keys. Use them for CI/CD pipelines and scheduled scripts where interactive OAuth login isn’t possible.

Verify Setup

Run dcy doctor to check everything is configured correctly:

dcy doctor

Output:

CLI Health Check

  ✓ Config file — /home/jane/.config/dcy/config.yaml
  ✓ API host — https://api.dcycle.io (production)
  ✓ Authentication — API key
  ✓ Organization — Acme Corp (550e8400-...)
  ✓ API connectivity — authenticated as jane@company.com
  ✓ Version — 0.0.45 (latest)

All checks passed.

Cross-Module Workflows

Complete Data Import Pipeline

Use the guided import flow to upload CSV/Excel data with column mapping and validation:

#!/bin/bash
set -euo pipefail

FACILITY_ID="550e8400-e29b-41d4-a716-446655440000"
FILE="invoices-q1-2025.xlsx"

# 1. Create import session
IMPORT_ID=$(dcy imports create \
  --template invoices \
  --file "$FILE" \
  --facility "$FACILITY_ID" \
  --format json | jq -r '.id')
echo "Import session: $IMPORT_ID"

# 2. Get AI-suggested column mapping
dcy imports suggest-mapping "$IMPORT_ID"

# 3. Review suggestions, then confirm
dcy imports confirm-mapping "$IMPORT_ID"

# 4. Validate rows against template rules
ERRORS=$(dcy imports validate "$IMPORT_ID" --format json | jq '.error_count')
if [ "$ERRORS" -gt 0 ]; then
  echo "Found $ERRORS validation errors — review and patch"
  dcy imports status "$IMPORT_ID"
  exit 1
fi

# 5. Submit for processing
dcy imports submit "$IMPORT_ID"
echo "Import submitted successfully"

File Upload and Processing

Upload documents (invoices, contracts) and create records from extracted readings:

#!/bin/bash
# Upload energy invoices and create records from parsed data

# Upload files
for pdf in invoices/*.pdf; do
  echo "Uploading $pdf..."
  FILE_ID=$(dcy file upload "$pdf" --format json | jq -r '.id')
  echo "  Uploaded: $FILE_ID"

  # Wait for processing, then check readings
  sleep 5
  READINGS=$(dcy file reading list --file-id "$FILE_ID" --format json)
  COUNT=$(echo "$READINGS" | jq 'length')

  if [ "$COUNT" -gt 0 ]; then
    READING_ID=$(echo "$READINGS" | jq -r '.[0].id')
    echo "  Found $COUNT reading(s), creating records from $READING_ID..."
    dcy file reading create-records "$READING_ID"
  else
    echo "  No readings found yet — check later with: dcy file reading list --file-id $FILE_ID"
  fi
done

Employee Survey Campaign

Send mobility surveys and track completion:

# Send surveys to a list of employees
dcy survey send alice@company.com bob@company.com carol@company.com

# Check who hasn't responded
dcy survey list --format json | jq '.[] | select(.status == "pending") | .email'

# Resend to non-respondents
PENDING=$(dcy survey list --format json | jq -r '.[] | select(.status == "pending") | .email')
if [ -n "$PENDING" ]; then
  dcy survey resend $PENDING
  echo "Resent surveys to $(echo "$PENDING" | wc -w) employees"
fi

Project Setup with Tasks

Create a carbon footprint project and assign tasks to team members:

#!/bin/bash

# Create project
PROJECT_ID=$(dcy project create \
  --name "2025 Carbon Footprint" \
  --type carbon \
  --start 2025-01-01 \
  --end 2025-12-31 \
  --due 2026-03-31 \
  --format json | jq -r '.id')

echo "Project created: $PROJECT_ID"

# Get team member IDs
MEMBERS=$(dcy member list --format json)
ADMIN_ID=$(echo "$MEMBERS" | jq -r '.[] | select(.role == "admin") | .id' | head -1)

# Create tasks
dcy project task create "$PROJECT_ID" \
  --title "Collect energy invoices" \
  --assigned-to "$ADMIN_ID" \
  --due 2025-06-30

dcy project task create "$PROJECT_ID" \
  --title "Upload fleet data" \
  --assigned-to "$ADMIN_ID" \
  --due 2025-06-30

dcy project task create "$PROJECT_ID" \
  --title "Verify Scope 3 purchases" \
  --assigned-to "$ADMIN_ID" \
  --due 2025-09-30

# List all tasks
dcy project task list "$PROJECT_ID"

Data Extraction with jq

Vehicle Fleet Analysis

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

# Find vehicles without plate numbers
dcy vehicle list --format json | \
  jq '.[] | select(.plate == "" or .plate == null) | {id, name}'

# Export plates for external validation
dcy vehicle list --format json | jq -r '.[].plate' > plates.txt

Facility Data Export

# List all facility names and locations
dcy facility list --format json | \
  jq '.[] | {name, country, city, postal_code}'

# Count facilities by country
dcy facility list --format json | \
  jq 'group_by(.country) | map({country: .[0].country, count: length}) | sort_by(.count) | reverse'

# Find facilities with CUPS codes (Spanish electricity)
dcy facility list --format json | \
  jq '.[] | select(.cups_list != null and (.cups_list | length) > 0) | {name, cups: .cups_list}'

Invoice Status Report

# Get all invoices for a facility
FACILITY_ID=$(dcy facility list --format json | jq -r '.[0].id')

# List enabled invoices with emissions
dcy invoice list --facility-id "$FACILITY_ID" --format json | \
  jq '.[] | select(.enabled == true) | {supplier: .supplier_name, period: .period, tco2e: .emissions_tco2e}'

Organization Hierarchy

# Show full org tree
dcy org tree

# Get all child org IDs for batch operations
dcy org tree --format json | jq -r '.. | .id? // empty' | sort -u

Bulk Operations

Bulk Delete with Filter

# Delete all vehicles matching a condition
dcy vehicle list --format json | \
  jq -r '.[] | select(.fuel == "unknown") | .id' > delete-ids.txt

echo "Will delete $(wc -l < delete-ids.txt) vehicles"

# Delete one by one (with confirmation skip)
while read -r id; do
  dcy vehicle delete "$id" --yes
done < delete-ids.txt

Bulk Delete with ID File

For commands that support delete-bulk, pass a file with one ID per line:

# Own workforce bulk delete
dcy own-workforce list --format json | \
  jq -r '.[] | select(.contract_end_date < "2024-01-01") | .id' > expired.txt

dcy own-workforce delete-bulk expired.txt --yes

# Sold product bulk delete
dcy sold-product delete-bulk product-ids.txt --yes

Batch Vehicle Upload

# Download template
dcy vehicle upload --template > vehicles-template.csv

# Fill template with your data (use Excel or any CSV editor)
# Then upload
dcy vehicle upload vehicles.csv

# Verify
dcy vehicle list --format json | jq 'length'

Scripting Best Practices

Error Handling with Retry

dcy automatically retries transient failures (429, 502, 503, 504) with exponential backoff. Shell-level retry is only needed to restart after non-retryable errors like timeouts. See Automatic Retry for details.

upload_with_retry() {
    local file=$1
    local type=$2
    local max_attempts=3

    for attempt in $(seq 1 $max_attempts); do
        echo "Attempt $attempt/$max_attempts: Uploading $file..."
        if dcy logistics upload "$file" --type "$type"; then
            echo "Success"
            return 0
        fi
        echo "Failed, retrying in 30s..."
        sleep 30
    done
    echo "ERROR: Upload failed after $max_attempts attempts"
    return 1
}

upload_with_retry viajes.csv requests
upload_with_retry consumos.csv recharges

Pagination Loop

Some commands return paginated results. Loop through all pages:

#!/bin/bash
# Collect all own-workforce records across pages
PAGE=1
SIZE=100
ALL_RECORDS="[]"

while true; do
  BATCH=$(dcy own-workforce list --page $PAGE --size $SIZE --format json)
  COUNT=$(echo "$BATCH" | jq 'length')

  if [ "$COUNT" -eq 0 ]; then
    break
  fi

  ALL_RECORDS=$(echo "$ALL_RECORDS $BATCH" | jq -s '.[0] + .[1]')
  echo "Page $PAGE: fetched $COUNT records (total: $(echo "$ALL_RECORDS" | jq 'length'))"

  if [ "$COUNT" -lt "$SIZE" ]; then
    break
  fi
  PAGE=$((PAGE + 1))
done

echo "$ALL_RECORDS" > all-workforce.json
echo "Total records: $(jq 'length' all-workforce.json)"

Conditional Logic Based on Data

#!/bin/bash
# Alert if any vehicle has missing fuel type

MISSING=$(dcy vehicle list --format json | \
  jq '[.[] | select(.fuel == null or .fuel == "")] | length')

if [ "$MISSING" -gt 0 ]; then
  echo "WARNING: $MISSING vehicles have no fuel type set"
  dcy vehicle list --format json | \
    jq -r '.[] | select(.fuel == null or .fuel == "") | "\(.id)\t\(.plate)\t\(.name)"'
  exit 1
fi

echo "All vehicles have fuel types configured"

Logging and Audit Trail

#!/bin/bash
# Wrapper that logs all CLI operations
LOG_FILE="dcycle-operations-$(date +%Y-%m-%d).log"

dcy_log() {
  local cmd="dcy $*"
  echo "[$(date -Iseconds)] CMD: $cmd" >> "$LOG_FILE"

  if output=$(dcy "$@" 2>&1); then
    echo "[$(date -Iseconds)] OK" >> "$LOG_FILE"
    echo "$output"
  else
    echo "[$(date -Iseconds)] FAIL: $output" >> "$LOG_FILE"
    echo "$output" >&2
    return 1
  fi
}

# Use the wrapper
dcy_log vehicle list --format json
dcy_log facility list

Debugging

Verbose Mode

Use --verbose to see HTTP requests and responses:

# Show full API communication
dcy vehicle list --verbose

Output on stderr:

→ GET https://api.dcycle.io/v1/vehicles?page=1&size=100
← 200 OK (245ms)

Verbose output goes to stderr, so it won’t interfere with JSON piped to other tools:

dcy vehicle list --format json --verbose 2>debug.log | jq '.'

Save Debug Output

# Capture debug info separately from data
dcy purchase list --verbose --format json 2>debug.log 1>purchases.json

# Review what API calls were made
cat debug.log

Check CLI Version

# Current version
dcy version

# Check if update is available
dcy version --check

Environment Variables Reference

All settings can be controlled via environment variables — useful for CI/CD, Docker containers, and cron jobs:

# Authentication
export DCYCLE_API_KEY=dcy_live_abc123...       # API key (skips OAuth)

# Context
export DCYCLE_ORG_ID=550e8400-...              # Active organization
export DCYCLE_HOST=https://api.dcycle.io       # API host override

# Output
export DCYCLE_FORMAT=json                       # Default output format
export DCYCLE_VERBOSE=1                         # Enable verbose logging
export NO_COLOR=1                               # Disable ANSI colors

# Timeouts
export DCYCLE_TIMEOUT=60                        # HTTP timeout in seconds

Command-line flags always take precedence over environment variables.

More Resources

Automation Guide

Comprehensive automation patterns and strategies

MCP Server

AI-assisted analysis with Claude

Data Imports

Guided CSV/Excel import with validation

API Reference

REST API for custom integrations

​Examples & Workflows

​Featured Examples

CI/CD Pipeline Integration

Multi-Organization Consolidated Reporting

Logistics Data Automation

​Quick Start

​Interactive Login

​API Key Login (for scripts and CI/CD)

​Verify Setup

​Cross-Module Workflows

​Complete Data Import Pipeline

​File Upload and Processing

​Employee Survey Campaign

​Project Setup with Tasks

​Data Extraction with jq

​Vehicle Fleet Analysis

​Facility Data Export

​Invoice Status Report

​Organization Hierarchy

​Bulk Operations

​Bulk Delete with Filter

​Bulk Delete with ID File

​Batch Vehicle Upload

​Scripting Best Practices

​Error Handling with Retry

​Pagination Loop

​Conditional Logic Based on Data

​Logging and Audit Trail

​Debugging

​Verbose Mode

​Save Debug Output

​Check CLI Version

​Environment Variables Reference

​More Resources

Automation Guide

MCP Server

Data Imports

API Reference

Examples & Workflows

Featured Examples

Quick Start

Interactive Login

API Key Login (for scripts and CI/CD)

Verify Setup

Cross-Module Workflows

Complete Data Import Pipeline

File Upload and Processing

Employee Survey Campaign

Project Setup with Tasks

Data Extraction with jq

Vehicle Fleet Analysis

Facility Data Export

Invoice Status Report

Organization Hierarchy

Bulk Operations

Bulk Delete with Filter

Bulk Delete with ID File

Batch Vehicle Upload

Scripting Best Practices

Error Handling with Retry

Pagination Loop

Conditional Logic Based on Data

Logging and Audit Trail

Debugging

Verbose Mode

Save Debug Output

Check CLI Version

Environment Variables Reference

More Resources