CLI Overview - Dcycle Platform Docs

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

What is the Dcycle CLI?

The Dcycle CLI (dcy) is a command-line tool that allows you to interact with Dcycle’s operational data platform directly from your terminal. It’s designed for:

Bulk operations: Upload large datasets via CSV files
Automation: Integrate Dcycle into your CI/CD pipelines and scripts
Power users: Quick access to data without navigating the web interface
Data management: Export, filter, and manage your operational data programmatically

Key Features

Organization Management

List, search, and switch between organizations. Manage members, invite users, and view hierarchy.

Facilities & Hubs

Manage facilities, logistic hubs, and bulk upload vehicles via CSV templates.

Emissions Data

Work with employee commute, travel, invoices, purchases, shipments, and transport routes.

Logistics Integration

Upload transport requests, fuel recharges, and manage logistics hubs.

Projects & Tasks

Create sustainability projects (carbon footprint, LCA, ISO audits) and manage tasks.

Files & Readings

Upload documents, view extracted readings, and create invoices from parsed files.

Widgets & Dashboards

Build pivot tables, charts, and KPI widgets on project dashboards. Filter, add intensity measures, and export CSV.

Admin Operations

Trigger backend recalculations (Scope 3 T&D, waste transport) and insert energy records.

Installation

Install with Homebrew (macOS and Linux):

brew tap Dcycle-by-WUM/tap https://github.com/Dcycle-by-WUM/homebrew-tap
brew install dcy

Verify the install:

dcy version

Updating

To update to the latest version:

brew update && brew upgrade dcy

Quick Reference

Authentication & Config

Command	Description
`dcy auth login`	Authenticate with Dcycle
`dcy auth logout`	Log out
`dcy auth status`	View current session info
`dcy auth set-api-key <key>`	Store API key for non-interactive auth
`dcy config list`	Show current configuration
`dcy config host set <env>`	Switch environment (production/staging/dev/local)
`dcy config reset`	Reset configuration to defaults
`dcy version`	Print CLI version
`dcy version --check`	Check for updates
`dcy doctor`	Verify CLI setup and connectivity
`dcy completion <shell>`	Generate shell completion script

Organization & Members

Command	Description
`dcy org list`	List accessible organizations
`dcy org set <id>`	Set active organization
`dcy org show <id>`	Show organization details
`dcy org tree`	Show organization hierarchy
`dcy org create`	Create organization
`dcy org edit <id>`	Edit organization
`dcy org invite <email>`	Invite user to organization
`dcy org bulk-create-children <csv>`	Create child organizations from CSV
`dcy org request-parent-link`	Request parent-child link
`dcy org confirm-parent-link`	Accept/reject parent link requests
`dcy member list`	List organization members
`dcy member invite <email>`	Invite member
`dcy member edit <id>`	Change member role
`dcy member delete <id>`	Remove member

Assets

Command	Description
`dcy facility list`	List facilities
`dcy facility create`	Create facility
`dcy facility edit <id>`	Edit facility
`dcy facility delete <id>`	Delete facility
`dcy vehicle list`	List fleet vehicles
`dcy vehicle create`	Create vehicle
`dcy vehicle edit <id>`	Edit vehicle
`dcy vehicle upload`	Bulk upload vehicles from CSV
`dcy vehicle diagnose <id>`	Diagnose vehicle emission issues
`dcy vehicle recalculate <id>`	Trigger emission recalculation
`dcy vehicle delete-consumptions`	Bulk delete consumption records
`dcy vehicle-fuel list`	List available vehicle fuels
`dcy vehicle-fuel list-types`	List vehicle type categories
`dcy hub list`	List logistic hubs
`dcy hub create`	Create hub
`dcy hub edit <id>`	Edit hub
`dcy hub delete <id>`	Delete hub

Emissions Data

Command	Description
`dcy survey send <emails>`	Send mobility surveys to employees
`dcy survey resend <emails>`	Resend surveys to pending employees
`dcy survey list`	List survey employees and status
`dcy employee list`	List employee commute records
`dcy employee create employee`	Create employee
`dcy employee create add-period <id>`	Add commute period
`dcy employee create import-periods`	Bulk import employees from CSV
`dcy employee set update-historic <csv>`	Bulk update historic periods from CSV
`dcy travel list`	List business travel records
`dcy transport list`	List transport routes
`dcy invoice list`	List energy invoices
`dcy invoice edit <id> [<id>...]`	Enable/disable/update invoice(s)
`dcy invoice recalculate`	Recalculate invoice emissions (one-by-one)
`dcy invoice recalculate-v2`	Batch recalculate by activity category
`dcy invoice recalculate-legacy`	Batch recalculate via legacy endpoint
`dcy purchase list`	List purchases
`dcy purchase upload`	Bulk upload purchases from CSV
`dcy shipment list`	List shipments
`dcy shipment create`	Create shipment

Logistics

Command	Description
`dcy logistics requests list`	List transport requests
`dcy logistics requests show <id>`	Show request details
`dcy logistics status`	Show logistics summary (requests, recharges, hubs)
`dcy logistics upload`	Upload CSV data (requests or recharges)
`dcy logistics clients`	List available clients
`dcy logistics tocs`	List cargo types

Files & Projects

Command	Description
`dcy file upload <path>`	Upload a file
`dcy file list`	List uploaded files
`dcy file reading list`	List file readings
`dcy file reading create-records <id>`	Create invoices from a reading
`dcy project list`	List projects
`dcy project create`	Create project
`dcy project task list <id>`	List project tasks
`dcy project task create <id>`	Create project task

Widgets

Command	Description
`dcy widget list <project-id>`	List dashboard widgets
`dcy widget create <project-id>`	Create a widget
`dcy widget update <project-id> <widget-id>`	Update a widget’s config
`dcy widget results <project-id> <widget-id>`	Compute results (JSON or CSV)
`dcy widget catalog [category]`	Show available dimensions and measures
`dcy widget filter add`	Add a hierarchy filter
`dcy widget intensity groups`	List intensity metric groups

Data Imports

Command	Description
`dcy imports create`	Upload a file and start an import session
`dcy imports suggest-mapping <id>`	Get AI-assisted column mapping suggestions
`dcy imports confirm-mapping <id>`	Lock in the column mapping
`dcy imports validate <id>`	Validate rows against template rules
`dcy imports patch <id>`	Fix row-level errors
`dcy imports submit <id>`	Submit import for processing
`dcy imports status <id>`	Check import session status
`dcy imports list`	List import sessions
`dcy imports template <id>`	View template columns and rules

Reference & Advanced

Command	Description
`dcy supplier list`	List available suppliers
`dcy units list`	List available units
`dcy own-workforce list`	List own workforce records
`dcy own-workforce delete-bulk`	Bulk delete own workforce records
`dcy sold-product delete-bulk`	Bulk delete sold product records
`dcy waste-water-treatments recalculate`	Recalculate WWT emissions
`dcy custom-ef upload`	Upload custom emission factors
`dcy custom-ef delete-bulk`	Bulk delete custom emission groups
`dcy lca link`	Link LCA materials to ecoinvent
`dcy lca edit <id>`	Edit ecoinvent match for a material

Admin

Command	Description
`dcy admin recalculate-scope3-td <org-id>`	Recalculate Scope 3 T&D data
`dcy admin recalculate-waste-transport <org-id>`	Re-split waste emissions into management vs transport
`dcy admin energy`	Insert or update energy records directly (kWh)

Global Flags

These flags are available on every command:

Flag	Description
`--format <text\|json>`	Output format (default: `text`)
`--json`	Shorthand for `--format json`
`--verbose`, `-v`	Show HTTP requests and responses on stderr
`--timeout <seconds>`	HTTP request timeout (default: `30`)
`--no-color`	Disable ANSI color output

# JSON output (shorthand)
dcy vehicle list --json

# Debug an API call
dcy vehicle list --verbose

# Increase timeout for slow connections
dcy facility list --timeout 60

# Combine flags
dcy purchase list --json --verbose --timeout 90

Verbose output goes to stderr, so it won’t interfere with JSON piped to other tools: dcy vehicle list --json --verbose | jq '.'

Output Formats

The CLI supports multiple output formats:

# Default: Rich table format (human-readable)
dcy vehicle list

# JSON format (for scripting)
dcy vehicle list --json

# Pipe to other tools
dcy vehicle list --json | jq '.[] | .plate'

# Disable colors (also respects NO_COLOR env var)
dcy vehicle list --no-color

Set a default format via environment variable:

export DCYCLE_FORMAT=json
dcy vehicle list  # outputs JSON without --format flag

Environment Variables

All settings can be controlled via environment variables, useful for CI/CD pipelines and scripts:

Variable	Description	Default
`DCYCLE_API_KEY`	API key for non-interactive auth (skips OAuth login)	—
`DCYCLE_HOST`	Override the API host URL	—
`DCYCLE_ORG_ID`	Override the active organization	—
`DCYCLE_FORMAT`	Default output format: `text` or `json`	`text`
`DCYCLE_VERBOSE`	Enable verbose HTTP logging (`1` or `true`)	—
`DCYCLE_TIMEOUT`	HTTP request timeout in seconds	`30`
`NO_COLOR`	Disable ANSI colors when set to any value	—

Command-line flags always take precedence over environment variables.

Shell Completions

Enable tab completion for commands, flags, and values:

# Bash
source <(dcy completion bash)

# Zsh
source <(dcy completion zsh)

# Fish
dcy completion fish | source

# PowerShell
dcy completion powershell | Out-String | Invoke-Expression

To load completions permanently, see dcy completion --help for per-shell instructions.

Shell completions include context-aware values — for example, --status suggests valid status values and --format suggests text or json.

Aliases

Most list subcommands support ls as a short alias:

dcy facility ls       # same as dcy facility list
dcy vehicle ls        # same as dcy vehicle list
dcy purchase ls       # same as dcy purchase list

Troubleshooting

Run dcy doctor to verify your CLI setup:

dcy doctor

This checks your config file, API host, authentication, organization, and CLI version. Use --format json for machine-readable output.

Getting Help

Every command supports the --help flag:

dcy --help              # Show all commands
dcy org --help          # Show organization commands
dcy vehicle list --help # Show list options and filters

Next Steps

Authentication

Learn how to authenticate and configure the CLI

Organizations

Manage your organization context and members

Vehicles

Manage fleet vehicles, fuel types, and CSV uploads

Facilities

Manage physical locations and their emissions

Invoices

Manage energy invoices for Scope 1 and Scope 2 emissions

Projects

Create and manage sustainability projects

Data Imports

Bulk import CSV/Excel with guided mapping and validation

Widgets

Build dashboard widgets, charts, and export data

Admin

Recalculations and direct data manipulation

MCP Server

Query your data from AI assistants via MCP

​What is the Dcycle CLI?

​Key Features

Organization Management

Facilities & Hubs

Emissions Data

Logistics Integration

Projects & Tasks

Files & Readings

Widgets & Dashboards

Admin Operations

​Installation

​Updating

​Quick Reference

​Authentication & Config

​Organization & Members

​Assets

​Emissions Data

​Logistics

​Files & Projects

​Widgets

​Data Imports

​Reference & Advanced

​Admin

​Global Flags

​Output Formats

​Environment Variables

​Shell Completions

​Aliases

​Troubleshooting

​Getting Help

​Next Steps

Authentication

Organizations

Vehicles

Facilities

Invoices

Projects

Data Imports

Widgets

Admin

MCP Server

What is the Dcycle CLI?

Key Features

Installation

Updating

Quick Reference

Authentication & Config

Organization & Members

Assets

Emissions Data

Logistics

Files & Projects

Widgets

Data Imports

Reference & Advanced

Admin

Global Flags

Output Formats

Environment Variables

Shell Completions

Aliases

Troubleshooting

Getting Help

Next Steps